Local Environment
Local Development Setup
Setting up a local development environment ensures a safe space to build, test, and contribute to this WordPress project without affecting production data. This repository is optimized for use with wp-env, but can be configured for traditional LAMP/LEMP stacks as well.
Prerequisites
Before starting, ensure you have the following installed on your machine:
- Docker Desktop (Required for the recommended
wp-envsetup) - Node.js & NPM (For managing development dependencies)
- Composer (For PHP dependency management)
Using wp-env (Recommended)
The simplest way to spin up a local server, database, and WordPress instance is using the official @wordpress/env tool. This creates a Docker-based environment pre-configured for this project.
-
Install the environment tool globally:
npm install -g @wordpress/env -
Start the environment: Navigate to the root directory and run:
wp-env start -
Access the Local Site:
- Site URL:
http://localhost:8888 - Dashboard:
http://localhost:8888/wp-admin - Credentials: Username:
admin, Password:password
- Site URL:
Database Configuration
If you are not using wp-env and prefer a manual setup (e.g., LocalWP, XAMPP, or Valet), configure your wp-config.php file with the following database constants:
// Local Database Configuration
define( 'DB_NAME', 'wordpress_local' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'root' );
define( 'DB_HOST', 'localhost' );
define( 'DB_CHARSET', 'utf8' );
define( 'DB_COLLATE', '' );
To import the base schema, you can use the WP-CLI:
wp db import setup/database-dump.sql
Debugging & Development Tools
To effectively troubleshoot contributions, enable the built-in WordPress debugging suite in your local wp-config.php.
Enabling WP_DEBUG
Add these lines to your configuration to log errors and display them during development:
// Enable Debugging
define( 'WP_DEBUG', true );
// Log errors to /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );
// Display errors on the screen
define( 'WP_DEBUG_DISPLAY', true );
// Use unminified core scripts and styles
define( 'SCRIPT_DEBUG', true );
Recommended Plugins
For a more robust debugging experience, it is recommended to install the following tools locally:
- Query Monitor: For viewing database queries, hooks, and HTTP requests.
- Debug Bar: For profiling the WordPress environment.
Dependency Management
This project utilizes both PHP and JavaScript dependencies. Run these commands to ensure your local environment matches the production requirements:
# Install PHP dependencies (Plugins/Libraries)
composer install
# Install JS dependencies and compile assets
npm install
npm run dev
Mail Testing
For testing email functionality (e.g., password resets, notifications), we recommend using MailHog. If you are using the default wp-env setup, MailHog is often accessible at http://localhost:8025.