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-env setup)
• 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.

1. Install the environment tool globally:

   npm install -g @wordpress/env
   

2. Start the environment: Navigate to the root directory and run:

   wp-env start
   

3. Access the Local Site:

   • Site URL: http://localhost:8888
   • Dashboard: http://localhost:8888/wp-admin
   • Credentials: Username: admin, Password: password

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.