| 1 |
# AGENTS.md |
| 2 |
|
| 3 |
Guidance for AI coding agents working on the **Update Control** plugin. |
| 4 |
|
| 5 |
## Plugin Structure |
| 6 |
|
| 7 |
This plugin is a single-file classically-structured PHP plugin utilizing separate script and style assets for settings interactions: |
| 8 |
- **`update-control.php`** — Main entrypoint. Registers namespace `Stephanis\UpdateControl`, contains the static class `Update_Control` and bootstraps hook callbacks for the WordPress Settings API and auto-update filters. |
| 9 |
- **`update-control.js`** — Enqueued on the admin `options-general.php` settings screen. Handles dynamic showing/hiding and enabling/disabling of dependent inputs. |
| 10 |
- **`update-control.css`** — Declares simple stylesheet rules adjusting the opacity of disabled settings options. |
| 11 |
- **`readme.txt`** — Standard WordPress.org metadata and changelog document. |
| 12 |
|
| 13 |
## No Asset Compilation |
| 14 |
|
| 15 |
The plugin's assets are shipped as-is — `update-control.js` is a jQuery-based script and `update-control.css` is hand-written CSS. There is **no asset compilation, bundling, or transpilation** (no Babel/webpack/wp-scripts build of the source). |
| 16 |
|
| 17 |
There is, however, an npm packaging step: `package.json` defines a `plugin-zip` script (`wp-scripts plugin-zip`) used only to assemble the WordPress.org distribution ZIP. It does not transform the assets. |
| 18 |
|
| 19 |
## Database Options Schema |
| 20 |
|
| 21 |
All configuration options are stored as a single associative array option in the database under the key `update_control_options`. Defaults are merged on retrieval via `get_options()`: |
| 22 |
- `active` (`yes` | `no`) — Globally enables/disables automatic updates. |
| 23 |
- `core` (`minor` | `major` | `dev`) — Core update level filters. |
| 24 |
- `plugin` (`yes` | `no` | `core`) — Auto-update all plugins, disable all plugin auto-updates, or defer to WordPress's per-plugin defaults. |
| 25 |
- `theme` (`yes` | `no` | `core`) — Auto-update all themes, disable all theme auto-updates, or defer to WordPress's per-theme defaults. |
| 26 |
- `translation` (bool) — Permit automatic translation updates. |
| 27 |
- `toggleadvanced` (`show` | `hide`) — Toggle visibility of advanced settings. |
| 28 |
- `vcscheck` (bool) — Bypasses VCS directory checkups to force updates on version controlled codebases. |
| 29 |
- `emailactive` (`yes` | `no`) — Toggle update emails. |
| 30 |
- `successemail` (bool) — Send email for successful updates. |
| 31 |
- `failureemail` (bool) — Send email for failed updates. |
| 32 |
- `criticalemail` (bool) — Send email for critically failed updates. |
| 33 |
- `debugemail` (bool) — Disable debug emails for development builds of WordPress. |
| 34 |
- `notification_email` (string) — Optional email address to send auto-update notifications to; empty falls back to the site admin email. |
| 35 |
|
| 36 |
## Coding Conventions & Linting |
| 37 |
|
| 38 |
- PHP code must use PSR-4 namespacing under `Stephanis\UpdateControl` and follow WordPress Coding Standards (WPCS). |
| 39 |
- Avoid calling `wp_get_wp_version()` to ensure full backward compatibility down to WordPress 6.0 without triggering Plugin Check static analysis errors. Access `$GLOBALS['wp_version']` directly instead. |
| 40 |
- The `update_modification_detected` warning flagged by the WordPress Plugin Check tool is a false positive / expected behavior, as the plugin's primary design is to filter automatic updates via hooks like `auto_update_plugin`. |
| 41 |
- Always verify changes against phpcs before proposing or committing edits: |
| 42 |
|
| 43 |
```bash |
| 44 |
# Lint code |
| 45 |
../vendor/bin/phpcs --standard=phpcs.xml |
| 46 |
|
| 47 |
# Auto-fix formatting issues |
| 48 |
../vendor/bin/phpcbf --standard=phpcs.xml |
| 49 |
``` |
| 50 |
|
