|
| 1 | +# Known improvement areas |
| 2 | + |
| 3 | +This document tracks known issues and improvement opportunities identified |
| 4 | +during a modernization review of this plugin. The focus is on error handling, |
| 5 | +user feedback, and silent failure modes. |
| 6 | + |
| 7 | +The broader context for this work is a shift toward using the WordPress |
| 8 | +Settings Errors API (`add_settings_error()` / `settings_errors()`) to collect |
| 9 | +and display status messages after operations complete, rather than scattering |
| 10 | +`echo()` calls throughout the business logic. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +## 1. `set_properties()` does not stop `harvest()` on failure |
| 15 | + |
| 16 | +**File:** `src/class-harvester.php` — `set_properties()` and `harvest()` |
| 17 | + |
| 18 | +There are two silent failure modes in `set_properties()`: |
| 19 | + |
| 20 | +### 1a. `wp_upload_dir()` error is ignored |
| 21 | + |
| 22 | +`wp_upload_dir()` returns an array that includes an `['error']` key, set to a |
| 23 | +non-empty string if the upload directory cannot be determined. The current code |
| 24 | +reads `['basedir']` unconditionally without checking whether `['error']` is |
| 25 | +set. If `wp_upload_dir()` fails, `$this->path` will be set to a wrong or empty |
| 26 | +value, and subsequent file writes will fail silently. |
| 27 | + |
| 28 | +**Suggested fix:** Check `wp_upload_dir()['error']` before using `['basedir']`. |
| 29 | +If it is non-empty, queue an error via `add_settings_error()` and return |
| 30 | +`false` to signal failure to `harvest()`. |
| 31 | + |
| 32 | +### 1b. `wp_mkdir_p()` failure does not propagate to `harvest()` |
| 33 | + |
| 34 | +If the cache directory cannot be created, `set_properties()` queues an error |
| 35 | +message but returns nothing, so `harvest()` has no way of knowing that the |
| 36 | +directory step failed. Execution continues into the try/catch block, the |
| 37 | +Google Sheets API is contacted successfully, and then `write()` silently fails |
| 38 | +when it tries to put files into a non-existent directory. The final result |
| 39 | +reported to the admin will be `true` (success), which is incorrect. |
| 40 | + |
| 41 | +**Suggested fix:** Have `set_properties()` return a boolean, and have |
| 42 | +`harvest()` check that return value before proceeding. If `set_properties()` |
| 43 | +returns `false`, `harvest()` should queue an error and return `false` without |
| 44 | +contacting the API. |
| 45 | + |
| 46 | +--- |
| 47 | + |
| 48 | +## 2. Per-sheet fetch errors are indistinguishable from step-3 errors |
| 49 | + |
| 50 | +**File:** `src/class-harvester.php` — `fetch()` |
| 51 | + |
| 52 | +Inside `fetch()`, `$service->spreadsheets_values->get()` can throw a |
| 53 | +`\Google\Service\Exception` — for example if permissions allow reading the |
| 54 | +spreadsheet index but not the individual sheet contents, or if a sheet name |
| 55 | +is somehow invalid. This is caught by the existing try/catch block in |
| 56 | +`harvest()`, but the error message won't identify which sheet caused the |
| 57 | +problem, making it harder to diagnose. |
| 58 | + |
| 59 | +**Suggested fix:** This is a lower-priority improvement. Options include |
| 60 | +wrapping the inner call in its own try/catch within `fetch()` to capture |
| 61 | +per-sheet errors with the sheet name included in the message, or having |
| 62 | +`fetch()` return a list of per-sheet results. The current broad catch is |
| 63 | +acceptable for now. |
| 64 | + |
| 65 | +--- |
| 66 | + |
| 67 | +## 3. `Admin_Widget` never calls the Harvester |
| 68 | + |
| 69 | +**File:** `src/class-admin-widget.php` — `widget()` |
| 70 | + |
| 71 | +The `widget()` method handles a POST action by updating the `cache_timestamp` |
| 72 | +option and queuing a message saying "Harvester activated..." — but it never |
| 73 | +actually instantiates or calls the `Harvester` class. The timestamp is updated |
| 74 | +to the current time without any data being fetched, which means the admin |
| 75 | +dashboard widget can display a recent "last updated" timestamp even though the |
| 76 | +cache content has not changed. |
| 77 | + |
| 78 | +This appears to be either a stub left over from an earlier design, or an |
| 79 | +incomplete implementation of a planned feature to trigger harvesting from the |
| 80 | +dashboard widget. |
| 81 | + |
| 82 | +**Suggested fix:** Either complete the implementation by calling |
| 83 | +`$harvester->harvest()` (and handling the return value as `Dashboard::update()` |
| 84 | +already does), or remove the POST-handling block entirely from `Admin_Widget` |
| 85 | +if the intent is that harvesting should only be triggered from the settings |
| 86 | +page. |
| 87 | + |
| 88 | +--- |
| 89 | + |
| 90 | +## 4. `admin-widget.php` template is fragile with an unset timestamp |
| 91 | + |
| 92 | +**File:** `templates/admin-widget.php` |
| 93 | + |
| 94 | +On a fresh install, or if the `cache_timestamp` option is deleted, `get_option( |
| 95 | +'cache_timestamp' )` returns `false`. This is passed to `gmdate()`, which |
| 96 | +treats it as `0` (the Unix epoch, January 1 1970), producing a misleading but |
| 97 | +non-fatal timestamp display. |
| 98 | + |
| 99 | +Additionally, the `switch` block that calculates the human-readable "X ago" |
| 100 | +string compares a `DateInterval` object against boolean expressions in each |
| 101 | +`case`. This works due to PHP's type coercion rules in switch statements, but |
| 102 | +it is a fragile antipattern that could behave unexpectedly across PHP version |
| 103 | +changes. |
| 104 | + |
| 105 | +**Suggested fix:** Guard the timestamp block with a check for a falsy |
| 106 | +`cache_timestamp` value, and display a "never harvested" message in that case. |
| 107 | +Replace the `switch` on the `DateInterval` object with explicit `if/elseif` |
| 108 | +comparisons on its properties (`$ago->y`, `$ago->m`, etc.). |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## Summary table |
| 113 | + |
| 114 | +| # | File | Issue | Risk | |
| 115 | +|---|---|---|---| |
| 116 | +| 1a | `class-harvester.php` | `wp_upload_dir()` error key ignored | Wrong path used silently | |
| 117 | +| 1b | `class-harvester.php` | `wp_mkdir_p()` failure doesn't stop `harvest()` | False success reported | |
| 118 | +| 2 | `class-harvester.php` | Per-sheet errors indistinguishable from index errors | Unhelpful error messages | |
| 119 | +| 3 | `class-admin-widget.php` | `Harvester` never called | Timestamp updated, cache stale | |
| 120 | +| 4 | `templates/admin-widget.php` | Unguarded timestamp and fragile switch | Misleading display on fresh install | |
0 commit comments