Local Development Environments

A professional WordPress project has at least three copies of the site, each with its own database, URL and WP_ENVIRONMENT_TYPE. Code moves up the chain through version control; content moves down as database exports. A lower environment’s database is never pushed over production, which keeps receiving comments, orders, users and edits that the copies do not have.

Figure: code (solid arrows) moves from the local machine to production through Git, CI and staging; content (dotted arrows) is copied down from production.

The Block Editor Handbook recommends wp-env, maintained by the WordPress project, and the Playground CLI for quick tests. The Advanced Administration Handbook lists many more options. The common ones:

The npm package @wp-now/wp-now is deprecated; its npm entry points to the Playground CLI, which has an equivalent for every wp-now start option (see The Playground CLI).

All the set-ups below run the same lumen-press repository: lumen-catalog/ (the plugin), themes/lumen/ (the block theme), mu-plugins/lumen-environment.php, content/ (import fixtures), and the committed configuration files .wp-env.json, compose.yaml, .env.example, blueprint.json and package.json. .wp-env.override.json and .env are ignored by Git.

wp-env is a Node.js command that writes a Docker Compose configuration and runs it: a wordpress container (Apache and PHP), a cli container (WP-CLI, Composer and PHPUnit) and a mysql container running MariaDB. It mounts the project into the install and activates it. Generated files live in a per-project directory under ~/.wp-env (~/wp-env on Linux), or under WP_ENV_HOME. Install it as a pinned development dependency, so every developer and CI run the same version:

Source: Block Editor Handbook: @wordpress/env

Flags passed through npm run need an extra double dash (npm run env:start -- --xdebug), otherwise npm keeps them. npx wp-env <command> runs the local copy directly.

A hand-written Compose file is the better choice when the project needs a specific web server, PHP-FPM, MySQL instead of MariaDB, or the same images as a containerised production. The official wordpress image has apache (default), fpm and fpm-alpine variants for PHP 8.2 to 8.5, and a cli variant with WP-CLI on Alpine. On first start, the entrypoint copies WordPress into an empty /var/www/html and writes a wp-config.php that reads the WORDPRESS_* variables through getenv(). The database must exist; the mariadb image creates it from MARIADB_DATABASE.

Source: Docker Hub: wordpress (Docker Official Image)

The password comes from a .env file next to compose.yaml that is never committed; the repository carries only .env.example with LUMEN_DB_PASSWORD=<choose-a-local-password>. Starting the stack and installing WordPress:

Source: WP-CLI Commands: wp core install

Without --admin_password, wp core install generates a random password and prints it once. The choices in the file avoid these errors:

Docker itself is covered in Compose for Local Development; production containers in Containers, Docker and Kubernetes.

Playground runs WordPress entirely in WebAssembly: PHP compiled to WASM and SQLite instead of MySQL, with no server. https://playground.wordpress.net/ starts a site in seconds in the browser. It keeps up to five autosaves in browser storage, which are recovery points, not backups; a temporary Playground (?storage=temp) is lost when the tab is closed or refreshed. The WebAssembly files (15 to 30 MB) are downloaded first, large plugins take 30 to 60 seconds to load, and not every WP-CLI command is supported. It suits demos, bug reproduction and teaching rather than daily work on a large site.

A Blueprint is a JSON file describing a Playground site: versions, landing page, login and a list of steps. The same file drives the browser and the Playground CLI. Lumen Press keeps one in the repository:

Source: Playground documentation: Blueprint steps

WordPress Studio, an open source application from Automattic for macOS, Windows and Linux, creates local sites, starts them from Blueprints and can sync with WordPress.com and Pressable sites. Local (LocalWP, from WP Engine) creates sites with a chosen web server, PHP and MySQL version. MAMP and XAMPP install a general Apache, PHP and MySQL stack on which WordPress is installed by hand; DDEV and Lando are Docker-based project tools; VVV is a Vagrant set-up. None is endorsed here. What matters is the same for every tool: PHP and database versions that match production, a configuration reproducible from files in the repository, and a site that is not reachable from the network. A purely graphical set-up is hard to reproduce on another machine or in CI, which is why Lumen Press commits its configuration files.

A staging site is a copy of production on the same hosting stack (PHP build, database server, web server, caches, CDN rules), used to approve a release. Managed hosts often create one with a click; on a self-managed server it is built from a database export and a copy of wp-content/uploads:

Source: WP-CLI Commands: wp search-replace

wp search-replace handles PHP-serialized values (options, widget settings), which a plain SQL REPLACE() corrupts because serialized strings store their length. The GUID column must never change. Run with --dry-run first and add --precise for complex serialized data. The same steps pull a copy into wp-env, with http://localhost:8888 as the target URL. Copying production data to a laptop is a transfer of personal data: delete or anonymise customers and subscribers first and keep dumps encrypted. Uploads and Multisite are covered in Importing, Exporting and Migrating.

A staging site must sit behind HTTP authentication or an IP allow list, must not be indexed, must not mail real users (password resets, order notifications, newsletters), and its cron jobs must not act on external services as production would, such as the Lumen Catalog distributor stock sync.

WordPress 5.5 added wp_get_environment_type(). It returns local, development, staging or production, read from the WP_ENVIRONMENT_TYPE environment variable or the constant of the same name; the constant wins. A missing or unknown value returns production, and the filters for custom types were removed in 5.5.1. With development and no WP_DEBUG defined, WordPress defines WP_DEBUG as true. The result is cached on the first call, so set the value in wp-config.php or the server environment, never later in a plugin. Hosts are asked to set staging on staging copies.

Source: Code Reference: wp_get_environment_type()

The Lumen Press must-use plugin, mapped into every environment above, keeps non-production copies out of search engines and stops them sending mail:

Source: Code Reference: pre_wp_mail filter

pre_wp_mail (5.7) short-circuits wp_mail() when a callback returns a non-null value; true reports the mail as sent. The filter is skipped on a local or development copy whose LUMEN_SMTP_HOST points at a mail catcher such as Mailpit, as set up in Email Delivery, while staging never sends mail. wp_robots_no_robots() (5.7) adds noindex to the robots meta tag. Because a missing or misspelt value means production, code must never read "not configured" as "test".