|
| 1 | +# Agent Workflow |
| 2 | + |
| 3 | +## What This Is |
| 4 | + |
| 5 | +Optimole WordPress plugin — cloud-based image optimization with CDN delivery, lazy loading, WebP/AVIF conversion, media offloading, and a Digital Asset Management (DAM) interface. Requires a supported PHP and WordPress version; see the plugin header or readme for the current version and system requirements. |
| 6 | + |
| 7 | +## Build & Dev Commands |
| 8 | + |
| 9 | +```bash |
| 10 | +# Install dependencies |
| 11 | +npm install && composer install |
| 12 | + |
| 13 | +# Build all assets (production) |
| 14 | +npm run build |
| 15 | + |
| 16 | +# Development with HMR (all targets in parallel) |
| 17 | +npm run dev |
| 18 | + |
| 19 | +# Build individual targets |
| 20 | +npm run build:dashboard # Admin settings UI |
| 21 | +npm run build:widget # Dashboard widget |
| 22 | +npm run build:media # Media library integration |
| 23 | +npm run build:optimizer # Frontend lazy loading script |
| 24 | +npm run build:video-player-editor |
| 25 | +npm run build:video-player-frontend |
| 26 | +``` |
| 27 | + |
| 28 | +## Testing |
| 29 | + |
| 30 | +```bash |
| 31 | +# PHP unit tests (requires WP test suite) |
| 32 | +composer phpunit |
| 33 | +composer install-wp-tests # First-time setup |
| 34 | + |
| 35 | +# Run a specific PHP test file |
| 36 | +composer phpunit -- tests/test-replacer.php |
| 37 | + |
| 38 | +# Run a specific test method |
| 39 | +composer phpunit -- --filter="test_method_name" |
| 40 | + |
| 41 | +# JavaScript tests |
| 42 | +npm test |
| 43 | +npm run test:watch |
| 44 | +npm run test:coverage |
| 45 | + |
| 46 | +# E2E tests (Playwright — configure use.baseURL in playwright.config.ts to your local WP URL; do not run against the shared http://testing.optimole.com by default) |
| 47 | +npm run e2e:run |
| 48 | +npm run e2e:open # Interactive UI mode |
| 49 | +``` |
| 50 | + |
| 51 | +## Linting & Static Analysis |
| 52 | + |
| 53 | +```bash |
| 54 | +# JavaScript |
| 55 | +npm run lint # ESLint |
| 56 | +npm run format # ESLint --fix |
| 57 | + |
| 58 | +# PHP |
| 59 | +composer phpcs # PHP CodeSniffer (WordPress-Core standard) |
| 60 | +composer format # Auto-fix with phpcbf |
| 61 | +composer phpstan # PHPStan level 6 |
| 62 | +``` |
| 63 | + |
| 64 | +## Architecture |
| 65 | + |
| 66 | +### Two-era codebase: v1 (legacy) and v2 (modern) |
| 67 | + |
| 68 | +**Legacy code (`inc/*.php`)** — Class prefix `Optml_*`, loaded by custom autoloader in `optimole-wp.php`. This is the bulk of the plugin. |
| 69 | + |
| 70 | +**Modern code (`inc/v2/`)** — PSR-4 autoloaded under `OptimoleWP\` namespace via Composer. New features should go here. |
| 71 | + |
| 72 | +### Plugin initialization flow |
| 73 | + |
| 74 | +``` |
| 75 | +optimole-wp.php → optml() → Optml_Main::instance() (singleton) |
| 76 | + ├── Optml_Manager — Orchestrates replacers and loads compatibilities |
| 77 | + ├── Optml_Admin — Admin dashboard UI, conflict detection |
| 78 | + ├── Optml_Rest — REST API endpoints for the dashboard |
| 79 | + ├── Optml_Media_Offload — Cloud offloading/restoration of media |
| 80 | + ├── Optml_Dam — Digital Asset Management UI |
| 81 | + ├── Optml_Video_Player — Video player blocks |
| 82 | + └── Optml_Cli — WP-CLI commands (when available) |
| 83 | +``` |
| 84 | + |
| 85 | +### Core subsystems |
| 86 | + |
| 87 | +- **URL/Tag replacement** (`tag_replacer.php`, `url_replacer.php`, `app_replacer.php`) — Parses HTML output, rewrites image URLs to Optimole CDN URLs with optimization parameters. |
| 88 | +- **Lazy loading** (`lazyload_replacer.php`, `inc/v2/BgOptimizer/`) — Viewport-based and background-image lazy loading. Frontend JS in `assets/js/optimizer.js`. |
| 89 | +- **Media offloading** (`media_offload.php`) — Moves media to/from Optimole cloud storage, handles bulk operations. |
| 90 | +- **Settings** (`settings.php`) — Central settings schema and management, stores in `wp_options`. |
| 91 | +- **Compatibility layer** (`inc/compatibilities/`) — 47+ integrations for page builders (Elementor, Divi, Beaver Builder), caching plugins (WP Rocket, LiteSpeed), WooCommerce, etc. Each extends `Optml_compatibility`. |
| 92 | + |
| 93 | +### Frontend assets (`assets/src/`) |
| 94 | + |
| 95 | +React-based, built with `@wordpress/scripts`: |
| 96 | +- `dashboard/` — Main admin settings page (React + @wordpress/components) |
| 97 | +- `widget/` — Admin dashboard widget |
| 98 | +- `media/` — Media library DAM integration |
| 99 | +- `video-player/` — Editor and frontend video player blocks |
| 100 | + |
| 101 | +Built output goes to `assets/build/`. The `assets/js/optimizer.js` is the frontend lazy-loading script. |
| 102 | + |
| 103 | +## Task Routing (Where to Start) |
| 104 | + |
| 105 | +- Bootstrap/hooks: `optimole-wp.php`, `inc/main.php`, `inc/manager.php`, `inc/filters.php`. |
| 106 | +- URL/CDN rewriting: `inc/tag_replacer.php`, `inc/url_replacer.php`, `inc/app_replacer.php` + `tests/test-replacer.php`. |
| 107 | +- Lazyload: `inc/lazyload_replacer.php`, `inc/v2/BgOptimizer/Lazyload.php`, `assets/js/optimizer.js` + `tests/test-lazyload.php`. |
| 108 | +- Admin/REST/settings: `inc/admin.php`, `inc/rest.php`, `inc/settings.php`, `assets/src/dashboard/`. |
| 109 | +- Media/DAM: `inc/media_offload.php`, `inc/dam.php`, `assets/src/media/`. |
| 110 | +- Compat/conflicts: `inc/compatibilities/`, `inc/conflicts/`, related `tests/e2e/*.spec.ts`. |
| 111 | +- Video player: `inc/video_player.php`, `assets/src/video-player/`, `tests/test-video.php`. |
| 112 | + |
| 113 | +## Security Checklist (WordPress-Specific) |
| 114 | + |
| 115 | +- State-changing actions: capability check + nonce verification. |
| 116 | +- Input/output: sanitize on input, escape on output. |
| 117 | +- REST: always set strict `permission_callback` for write routes. |
| 118 | +- SQL: use `$wpdb->prepare()` for dynamic queries. |
| 119 | +- Safety: do not leak secrets/tokens; validate remote and file/media operations before mutate/delete. |
| 120 | + |
| 121 | +## Agent Execution Policy |
| 122 | + |
| 123 | +- Keep changes surgical; avoid unrelated refactors/cleanups. |
| 124 | +- Prefer `inc/v2/` for new logic unless legacy coupling forces `inc/*.php`. |
| 125 | +- Trace hooks and callsites before editing behavior. |
| 126 | +- Add/update the smallest relevant test and run targeted checks first. |
| 127 | +- Build only touched frontend targets; call out intentional build artifacts. |
| 128 | + |
| 129 | +## Code Standards |
| 130 | + |
| 131 | +- **PHP**: WordPress-Core via PHPCS. Text domain: `optimole-wp`. |
| 132 | +- **JS**: WordPress ESLint config. Tabs, single quotes, semicolons. |
| 133 | +- **v2 PHP code** requires PHPStan-compatible PHPDoc annotations, full namespace paths, type hints, and constants for magic values (e.g., `Profile::DEVICE_TYPE_MOBILE` not `1`). |
| 134 | +- Error handling: return `WP_Error` for WordPress-compatible errors, `false` for simple failures. |
| 135 | +- Debug logging: `do_action( 'optml_log', $message )` when `OPTML_DEBUG` is true. |
| 136 | + |
| 137 | +## Key Constants |
| 138 | + |
| 139 | +Defined in `optimole-wp.php`: `OPTML_URL`, `OPTML_PATH`, `OPTML_VERSION`, `OPTML_NAMESPACE` (`'optml'`), `OPTML_BASEFILE`, `OPTML_DEBUG`, `OPTML_DEBUG_MEDIA`. |
0 commit comments