🔌 WordPress Plugins

Professional guidelines and genius best practices for WordPress plugin development, optimized for our Debian-based server environment with Nginx and MariaDB 10.11.

---

🚨 1. Critical Gotchas

• Double-Prefix Route Paths: Route files must use bare paths (/spawn), not domain-prefixed (/acp/spawn). FastAPI / WordPress routing adds prefixes automatically.
• Plugin Context has no log: Avoid ctx.log.info() (AttributeError). Use module-level log = logging.getLogger(__name__).
• Database constraints: Empty strings ("") in foreign keys violate constraints. Ensure empty/blank workspace IDs are converted to NULL/None.
• FPM permissions: Files must be owned by www-data and have strict permissions (directories 0755, files 0644, configurations 0600).

---

📦 2. Best Practice YAML Configuration

topic: WordPress Plugin Development (Debian + Nginx + MariaDB 10.11)
rules:
  standards:
    wp_php: Follow WP CS (snake_case, prefixing globals/functions/classes). Strict type-hinting.
    wp_js_ts: Follow WP CS. Prefer TypeScript over JavaScript for Gutenberg blocks.
    paradigms: Favor functional & composition over OOP/inheritance. Keep ecosystem alignment.
    readability: Code must be readable, self-documenting, and clean.
  architecture:
    http_client: Use Guzzle. Implement timeouts, retries, and strict error handling (try/catch).
    rest_api: Register via `register_rest_route` with namespaces, versions, and validation/permission callbacks (never return true unconditionally).
    gutenberg: Modern block.json-based registration. Use React, TypeScript, and block-editor components.
  debian_server_env:
    os_distro: Debian 12 Bookworm (Kernel 6.1)
    web_server: Nginx + PHP-FPM. Socket at `/run/php/php8.2-fpm.sock` or `unix:/var/run/php/php-fpm.sock`.
    fastcgi: Configure FastCGI cache/buffers. Map PHP requests to PHP-FPM securely (`cgi.fix_pathinfo=0`).
    database: MariaDB 10.11.11. Use `utf8mb4_unicode_ci` collations. Avoid raw SQL; use WP_Query or `$wpdb->prepare()`.
    security: Run under `www-data` owner. Dir permission 755, file 644, config 600.
    caching: Enable Zend OPcache, Redis/Memcached object cache for DB query reduction.
  practices:
    errors: Use `try-catch` for external APIs. Return WP_Error on REST failures.
    modular: Modularize domain logic; avoid monolithic plugins. Use composition.

---

🔧 3. Developer Best Practices

Area	Best Practice	Rationale
PHP	Use strict type-hinting & return types.	Prevents runtime type mismatches and improves code intelligence.
JS / TS	Write Gutenberg blocks in TypeScript.	Enhances build-time safety and IDE auto-completion.
API	Implement Guzzle timeouts and retry limits.	Prevents HTTP request hangs from blocking php-fpm processes.
Database	Prepare all SQL statements with $wpdb->prepare().	Shields database queries from SQL injection attacks.

---

💡 4. Debian Environment Optimization

• PHP-FPM Socket: Configure Nginx upstream to communicate via UNIX sockets (e.g. unix:/run/php/php8.2-fpm.sock) rather than TCP.
• OPcache Enabled: Keep Zend OPcache enabled in PHP-FPM settings to cache precompiled script bytecode in shared memory.
• FastCGI Buffering: Ensure proper fastcgi_buffers and fastcgi_buffer_size sizes are defined in Nginx configs to prevent big response body drops.

---

✅ 5. Verification Checklist

• No global namespaces polluted: All classes/functions are prefixed or enclosed in namespaces.
• REST permissions validated: REST endpoints reject unauthorized actions with a custom permission callback.
• Error handlers verified: Guzzle calls are wrapped in try-catch blocks and throw graceful exceptions.
• File permissions clean: Directories are 0755, PHP/JS files are 0644, config files are 0600/0640.

---

🔗 6. Related

• 🦾 Skills — master reference list for all skills
• 🔌 omp — ACP agent commands and guidelines