Local Development Setup

This document describes how to set up a local development environment for the BuddyPress VIP Go plugin. It covers installation of required dependencies, configuration of the wp-env development environment, and the basic development workflow. For information about testing infrastructure, see Testing Infrastructure. For code quality tools and standards enforcement, see Code Quality and Standards.

Prerequisites

The following tools must be installed on your development machine before setting up the local environment:

Tool	Minimum Version	Purpose
PHP	8.2	Runtime requirement for the plugin
Composer	2.0+	PHP dependency management and script execution
Node.js	16+	Required for wp-env
npm	8+	Package manager for Node.js dependencies
Docker	Latest	Backend for wp-env containers

The plugin enforces a minimum PHP version of 8.2 as specified in composer.json22 The wp-env tool requires Node.js and Docker to run containerized WordPress instances.

Sources: composer.json22 AGENTS.md14

Dependency Installation

After cloning the repository, install PHP and Node.js dependencies:

The composer install command installs several development dependencies defined in composer.json25-30:

Package	Purpose
automattic/vipwpcs	WordPress VIP coding standards for PHPCS
php-parallel-lint/php-parallel-lint	PHP syntax validation
phpcompatibility/phpcompatibility-wp	PHP version compatibility checks
phpunit/phpunit	Test framework
yoast/wp-test-utils	WordPress test utilities (BrainMonkey, WP_Mock)

These packages enable the Composer scripts defined in composer.json44-54 for code quality checks and testing.

Sources: composer.json25-30 composer.json44-54

wp-env Configuration

The plugin uses wp-env to provide a containerized WordPress development environment. Configuration is defined in .wp-env.json:

The configuration in .wp-env.json1-20 establishes two separate WordPress environments:

Development Environment (Port 8888)

The primary development environment uses:

• WordPress 6.6 (stable release)
• PHP 8.2 (minimum supported version from composer.json22)
• Debug flags enabled: WP_DEBUG, WP_DEBUG_LOG, SCRIPT_DEBUG (.wp-env.json6-10)
• Query Monitor plugin automatically installed via afterStart lifecycle script (.wp-env.json12)

Test Environment (Port 8889)

The test environment uses:

• WordPress trunk (bleeding-edge development version from WordPress/WordPress#trunk)
• PHP 8.4 (latest PHP version for forward compatibility testing)
• Same plugin mounting as development environment

This dual-environment approach ensures the plugin works with both minimum and maximum PHP/WordPress versions.

Sources: .wp-env.json1-20 composer.json22

Starting the Development Environment

To start the development environment:

The wp-env start command:

1. Pulls Docker images for WordPress and MySQL (first run only)
2. Creates containers for development and test environments
3. Mounts the current directory as a plugin in wp-content/plugins/buddypress-vip-go
4. Executes the afterStart lifecycle script to install Query Monitor (.wp-env.json12)
5. Starts the WordPress instances on ports 8888 (dev) and 8889 (test)

BuddyPress Installation Requirement

Critical: BuddyPress must be manually installed and activated in the wp-env environment. The plugin has a hard dependency on BuddyPress as documented in AGENTS.md37 The main plugin file checks for BuddyPress availability via the bp_loaded action hook before loading the VIP integration layer.

To install BuddyPress in wp-env:

Without BuddyPress, the plugin will not load its core functionality (buddypress-vip-go.php waits for the bp_loaded action as documented in Diagram 4 of the high-level architecture).

Sources: .wp-env.json1-20 AGENTS.md37 AGENTS.md72

Development Workflow and Available Scripts

The plugin provides several Composer scripts for common development tasks, defined in composer.json44-54:

Script Reference

Script	Command	Purpose	Pre-commit Use
composer lint	parallel-lint	Check PHP syntax errors	✓ Required
composer cs	phpcs -q	Check coding standards	✓ Required
composer cs-fix	phpcbf -q	Auto-fix coding standard violations	Optional
composer test:unit	phpunit --testsuite Unit	Run unit tests with BrainMonkey	Recommended
composer test:integration	wp-env run tests-cli ./vendor/bin/phpunit	Run integration tests in wp-env	Recommended
composer test:integration-ms	WP_MULTISITE=1 phpunit	Run multisite integration tests	Optional
composer coverage	phpunit --coverage-html	Generate HTML coverage report	Optional
composer i18n	wp i18n make-pot	Generate translation template	As needed

Typical Development Workflow

1. Start environment:

2. Make code changes in your editor

3. Check syntax and standards:

4. Auto-fix violations:

5. Run tests:

6. Commit changes (CI will reject commits that fail lint or cs checks)

Integration Test Execution

The integration test scripts (composer.json53-54) use wp-env run tests-cli to execute PHPUnit inside the test environment container. The command structure is:

This:

• Executes in the tests-cli container (PHP 8.4, WordPress trunk)
• Sets working directory to the plugin path within the container
• Runs PHPUnit with the WP_Tests suite defined in phpunit.xml.dist
• For multisite tests, sets WP_MULTISITE=1 environment variable

The integration tests require the wp-env environment to be running, as documented in AGENTS.md74

Sources: composer.json44-67 AGENTS.md42-50 AGENTS.md74

Environment Management

Stopping the Environment

Accessing WordPress CLI

Database Access

wp-env creates separate MySQL databases for each environment. Access credentials:

• Database name: wordpress
• User: root
• Password: password
• Host (dev): localhost:3306 (port may vary)
• Host (test): Different port, check npx wp-env start output

Sources: .wp-env.json1-20

Common Setup Issues

BuddyPress Missing Error

Symptom: Plugin appears inactive, no VIP integration loads

Cause: BuddyPress is not installed or activated

Solution: The plugin requires BuddyPress as a hard dependency (AGENTS.md37 AGENTS.md72). Install via:

The main plugin file (buddypress-vip-go.php) waits for the bp_loaded action before initializing (see Diagram 4 in the high-level architecture overview).

Docker Not Running

Symptom: wp-env start fails with connection errors

Cause: Docker daemon not started

Solution: Start Docker Desktop or Docker service before running wp-env start

Port Conflicts

Symptom: wp-env start fails with port binding errors

Cause: Ports 8888 or 8889 already in use

Solution: Stop conflicting services or modify .wp-env.json1-20 to use different ports

Integration Tests Fail

Symptom: composer test:integration produces connection errors

Cause: wp-env not running

Solution: Start wp-env before running integration tests:

As noted in AGENTS.md74 integration tests require the wp-env environment to be active.

Composer Dependencies Out of Date

Symptom: Missing classes or methods in tests

Cause: Dependencies not installed after repository clone

Solution: Run composer install from the plugin root directory

Sources: AGENTS.md69-77 AGENTS.md72 AGENTS.md74

Next Steps

After completing local setup:

• Review Testing Infrastructure to understand the test architecture
• Consult Code Quality and Standards for PHPCS configuration and editor setup
• See CI/CD Pipeline for how automated checks validate your changes
• Reference BuddyPress VIP Go Overview for understanding the plugin's purpose

Sources: composer.json1-68 .wp-env.json1-20 AGENTS.md1-78