Setting up .wp-env for local development

Introduction

WordPress has a tool called wp-env which allows you to setup and run containers in docker very easily to use for your own themes and/or plugins.

During this tutorial we will setup a local example-plugin.php and install fakerpress (really awesome to generate fake posts for testing). which will get you setup for working with WordPress locally.

Lets setup the following directory structure and associated files in order to get the environment running locally.

example-plugin/.wp-env.json
example-plugin/example-plugin.php
example-plugin/resource/error-reporting.php
example-plugin/resource/.htaccess
example-plugin/resource/debug.log

If you would like to find out more what the WordPress docs says about wp-env the following is worth reading before diving in.

Step 1: Install `wp-env`

First, you need to install `wp-env` globally using npm:

npm install -g @wordpress/env

Step 2: Create the example-plugin/.wp-env.json

This configuration file specifies the plugins to be used, WordPress configuration settings, and file mappings.

{
  "plugins": [
    ".",
    "https://downloads.wordpress.org/plugin/fakerpress.0.6.6.zip"
  ],
  "config": {
    "WP_DEBUG": true,
    "WP_DEBUG_LOG": true,
    "WP_DEBUG_DISPLAY": false,
    "SCRIPT_DEBUG": true,
    "WP_ENVIRONMENT_TYPE": "local"
  },
  "mappings": {
    ".htaccess": "./resource/.htaccess",
    "wp-content/debug.log": "./resource/debug.log",
    "wp-content/mu-plugins/error-reporting.php": "./resource/error-reporting.php"
  }    
}

Step 3: Create the example-plugin/example-plugin.php file

This is a basic example plugin.

<?php
/**
 * Plugin Name: Example Plugin
 * Plugin URI: https://example.com
 * Description: A simple WordPress plugin with activation and deactivation hooks.
 * Version: 1.0
 * Author: Your Name
 * Author URI: https://yourwebsite.com
 * License: GPL2
 */

// Prevent direct access to the file
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Function to run on plugin activation
 */
function example_plugin_activate() {
    // Log plugin activation.
    error_log('plugin activated');
}

/**
 * Function to run on plugin deactivation
 */
function example_plugin_deactivate() {
    // Log plugin deactivation.
    error_log('plugin deactivated');
}

// Register activation and deactivation hooks
register_activation_hook(__FILE__, 'example_plugin_activate');
register_deactivation_hook(__FILE__, 'example_plugin_deactivate');

Step 4: Create the example-plugin/resource/error-reporting.php file

This will prevent any deprecated errors being written to the debug.log.

<?php
/**
 * PHP - Don't report deprecation warnings
 *
 * @package  MU Plugin
 */
/**
 * Plugin Name: PHP - Don't report deprecation warnings
 * Description: Don't report deprecation warnings
 */
error_reporting( E_ALL & ~E_DEPRECATED ); // phpcs:ignore

Step 5: Create the example-plugin/resource/.htaccess file

This will alter the php values used for the wordpress install.

php_value post_max_size 512M
php_value upload_max_filesize 512M
php_value memory_limit 512M

Step 6: Create the example-plugin/resource/debug.log file

This is simply an empty file which will be used for logging from our container.

Step 7: Start the WordPress Environment

Run the following command to start the WordPress environment which will set up a local WordPress environment using the configuration specified in the  .wp-env.json file.

wp-env start

Step 8: Access the WordPress Site

Once the environment is up and running, you can access your WordPress site at `http://localhost:8888`.

Step 9: Debugging and Logs

Since `WP_DEBUG` and `WP_DEBUG_LOG` are enabled in the configuration, you can check the `debug.log` file for any errors or warnings. The log file is mapped to debug.log.

If everything has been configured correctly you should see the following in your debug.log

[15-Nov-2024 00:00:44 UTC] plugin activated

Step 10: Stopping the Environment

To stop the WordPress environment, run:

wp-env stop

Step 11: Destroying the Environment

If you want to completely remove the environment, run the following which will remove all the containers and volumes created by `wp-env`.

wp-env destroy

Conclusion

By following these steps, you can set up and manage a local WordPress development environment using wp-env with your theme and or plugin files.