Wordpress

WordPress

You are building the WordPress application layer — themes, plugins, the dashboard/CLI surface, security, and stores — for someone treating WordPress as the product. Know the difference between a functions.php hack and a real plugin. Refuse to paste secrets into the dashboard file editor. Pick block themes over page builders by default. Reach for wp before clicking through wp-admin.

This is not generic PHP. If there is no WordPress API in sight (value objects, Composer/PSR-4, PHPStan), that is php. A Laravel app is laravel.

Version & runtime targeting

Target current. Stale version assumptions are the most common way WP code rots.

• WordPress 6.9 (released 2025-12-02) is current; it refines speculative loading and supports PHP 8.5. WP 6.8 ("Cecil", 2025-04-15) added bcrypt password hashing and speculative loading. Why: features below assume 6.6+ APIs (wp_enqueue_block_style, theme.json v3).
• PHP 8.4 is the recommended runtime for 2026. WP 6.9 fully supports PHP 8.5; WP 6.8+ fully supports 8.4; WP 6.4+ supports 8.3. Never target PHP 7.x or 8.0–8.2 for new code — all EOL. Why: writing for a dead runtime ships deprecation bugs the host will eventually refuse to run.
• theme.json v3 is the schema for new block themes (WP 6.6+). Locally set WP_DEVELOPMENT_MODE to all so theme.json edits are not cached for 30+ seconds. Why: without it you will edit theme.json, see nothing change, and waste an hour.

// wp-config.php — local dev only, never on production
define( 'WP_DEVELOPMENT_MODE', 'all' );
define( 'WP_DEBUG', true );
define( 'SCRIPT_DEBUG', true );

Decision: how heavy is the change?

Pick the lightest artifact that survives an update. The failure mode is everyone reaching for functions.php or editing files that get overwritten.

Block themes

A block theme is theme.json + HTML templates in templates/ and parts/. Start from a v3 skeleton:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "color": {
      "palette": [
        { "slug": "base", "color": "#ffffff", "name": "Base" },
        { "slug": "contrast", "color": "#111111", "name": "Contrast" }
      ]
    },
    "typography": {
      "fluid": true,
      "fontFamilies": [
        { "fontFamily": "system-ui, sans-serif", "slug": "system", "name": "System" }
      ]
    },
    "layout": { "contentSize": "640px", "wideSize": "1100px" }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--base)", "text": "var(--wp--preset--color--contrast)" }
  }
}

Templates resolve by hierarchy: templates/index.html is the fallback; single.html, archive.html, page.html, 404.html override it. Reusable chunks live in parts/ (header.html, footer.html).

Register patterns by dropping PHP-headered HTML in patterns/; they appear in the inserter automatically. Enqueue CSS per block so it only loads when the block renders:

add_action( 'init', function () {
	wp_enqueue_block_style( 'core/group', array(
		'handle' => 'mytheme-group',
		'src'    => get_theme_file_uri( 'assets/blocks/group.css' ),
		'path'   => get_theme_file_path( 'assets/blocks/group.css' ),
	) );
} );

Rule: never hand-write <link>/<script> tags in templates — the browser cannot cache them and you lose dependency management. Always enqueue. And never edit a parent theme directly; make a child theme.

Plugins

A plugin is a folder with a headered main file. That header is what makes it a plugin:

<?php
/**
 * Plugin Name: Acme Books
 * Description: Registers the book CPT and a related block.
 * Version:     1.0.0
 * Requires PHP: 8.4
 * Requires at least: 6.9
 */
defined( 'ABSPATH' ) || exit; // never expose a direct hit

Hooks split two ways: actions fire at a point in execution (add_action('init', …)); filters transform a value and must return it (add_filter('the_content', …)). Confusing them is a top-five WP bug.

Register a block from a block.json — never duplicate metadata in PHP:

add_action( 'init', function () {
	register_block_type( __DIR__ . '/build/related-books' ); // reads block.json
} );

Register a custom post type with explicit capabilities and labels:

add_action( 'init', function () {
	register_post_type( 'book', array(
		'public'       => true,
		'show_in_rest' => true, // required for the block editor
		'supports'     => array( 'title', 'editor', 'thumbnail' ),
		'labels'       => array( 'name' => 'Books', 'singular_name' => 'Book' ),
	) );
} );

Every write path needs a capability check + nonce, and every output/query needs escaping/sanitizing. This is the line between a plugin and a vulnerability.

// Bad — SQL injection, no auth
$rows = $wpdb->get_results( "SELECT * FROM {$wpdb->posts} WHERE post_author = $id" );

// Good — capability, nonce, prepared statement
if ( ! current_user_can( 'edit_posts' ) ) { wp_die( 'nope' ); }
check_admin_referer( 'acme_save' );
$rows = $wpdb->get_results( $wpdb->prepare(
	"SELECT * FROM {$wpdb->posts} WHERE post_author = %d", $id
) );
echo esc_html( $rows[0]->post_title );

Sanitize on input (sanitize_text_field, absint), escape on output (esc_html, esc_attr, esc_url, wp_kses for allowed HTML).

Security hardening

The single highest-impact habit is keeping core, plugins, and themes updated — 2024 saw 7,966 new ecosystem vulnerabilities, +34% YoY, and the vast majority hit known-vulnerable extensions. Baseline wp-config.php constants:

define( 'DISALLOW_FILE_EDIT', true );  // kills dashboard Theme/Plugin editor; SFTP/Git unaffected
define( 'WP_AUTO_UPDATE_CORE', 'minor' );
define( 'FORCE_SSL_ADMIN', true );

Use Application Passwords (WP 5.6+) for REST/API machine auth — individually revocable, cannot log into wp-login.php, and the right answer when a script or nextjs front end needs to talk to WP. Never reuse the admin password in a script.

For the full block — file-permission matrix (dirs 755 / files 644 / wp-config 600), DISALLOW_FILE_MODS, nginx/.htaccess security headers, login lockdown, XML-RPC and user-enumeration disabling, version-disclosure removal — see references/hardening.md. Generic OWASP/threat-modeling not tied to the WP attack surface is secure-coding.

Performance

Two caches, different jobs: an object cache (Redis/Memcached via a drop-in) memoizes DB query results across requests; a page cache stores whole rendered HTML pages. You usually want both. Then:

• Audit autoloaded options first when wp-admin crawls — a few MB of autoloaded junk loads on every request. Find offenders with the SQL in the reference.
• Enqueue assets per block (above); defer/async non-critical scripts.
• Speculative loading (prerender/prefetch on hover) ships in 6.8+; tune it rather than bolting on a plugin.

Full Redis wiring, the autoload audit query, transients, and a WP-tied Core Web Vitals checklist are in references/performance.md. Generic CWV/load-testing methodology divorced from WordPress is the performance sibling.

WooCommerce

HPOS (High-Performance Order Storage) is the default order datastore for new installs since WooCommerce 8.2 — orders live in dedicated tables, not wp_posts. Enable/migrate and verify with WP-CLI:

wp wc hpos enable            # turn on custom order tables
wp wc cot sync               # backfill/sync existing orders
wp wc cot verify_cot_data    # confirm parity before flipping authority

Any plugin that touches orders must declare HPOS compatibility, or WooCommerce disables it in HPOS mode:

add_action( 'before_woocommerce_init', function () {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility(
			'custom_order_tables', __FILE__, true
		);
	}
} );

Store/checkout/product setup checklist and migration caveats: references/woocommerce.md. A Shopify store is the shopify sibling.

WP-CLI & local dev

wp is the operational backbone — scriptable, faster than the dashboard, and safe on serialized data.

• Local stack: wp-env start (Dockerized WP). Scaffold a block/plugin with npx @wordpress/create-block acme-block.
• Migrations: wp search-replace is serialization-safe — never run a raw SQL REPLACE on the DB, it corrupts serialized arrays. Dry-run first:

wp search-replace 'https://staging.example.com' 'https://example.com' --all-tables --dry-run
wp db export backup.sql        # always export before a real run
wp search-replace 'https://staging.example.com' 'https://example.com' --all-tables

• Cron: WP's pseudo-cron only fires on traffic. For reliable schedules, define DISABLE_WP_CRON true and run wp cron event run --due-now from real system cron.

Anti-patterns

verify.sh

scripts/verify.sh <path> statically scans theme/plugin/config code for these anti-patterns — committed DB creds or AUTH_KEY/salt literals, missing DISALLOW_FILE_EDIT when a wp-config.php is in scope, eval(/base64_decode(, query_posts(, unprepared $wpdb interpolation, and hardcoded <script src=/<link rel="stylesheet"> in PHP templates. Read-only; exits 0 on a clean or empty target, non-zero on any FAIL so it can gate CI.