Development Guide

This guide provides an introduction to developing for the BuddyPress VIP Go plugin, including common pitfalls, workflow overview, and essential tooling. The plugin bridges BuddyPress functionality with WordPress VIP Go's distributed file system, requiring careful consideration of platform-specific constraints.

For detailed setup instructions, see Local Development Setup. For information about the testing infrastructure, see Testing Infrastructure. For code quality requirements and standards enforcement, see Code Quality and Standards.

Purpose and Scope

This guide is designed for developers who need to:

• Understand the plugin's architectural constraints and design decisions
• Avoid common pitfalls when working with VIP Go file operations
• Set up a local development environment with required dependencies
• Run tests and code quality checks using Composer scripts
• Contribute code changes that meet WordPress VIP standards

The plugin requires PHP 8.2+ and follows WordPress VIP coding standards. Development workflows are managed through Composer scripts and GitHub Actions for continuous integration.

Sources: README.md1-62 composer.json21-23

Common Pitfalls and Warnings

Before beginning development, developers must understand these critical constraints to avoid breaking media functionality on VIP Go sites:

VIP Go File System Constraints

Constraint	Implication	What to Avoid
No direct file system access	Standard PHP file functions fail on VIP FHS	fopen(), file_get_contents(), is_dir(), opendir() on upload paths
No flock() support	File locking operations are not available	Chunked upload assembly directly on VIP FHS
Distributed storage	Files are not on local disk	Assumptions about file paths being readable via PHP
CDN-based delivery	All files served through CDN layer	Direct file serving or path-based access

Key Rule: Do not assume standard WordPress file system behavior. VIP Go uses a different storage backend, and this plugin exists specifically to handle those differences.

Sources: AGENTS.md69-78 README.md11-22

Critical Code Areas

The following areas require special attention when making changes:

1. files.php - Intentionally Monolithic

The files.php1-999 file (~31KB) is intentionally large because it contains cohesive file-handling logic for the VIP Go environment. The logic is tightly coupled to VIP Go's file system API.

⚠️ Do not refactor or split files.php without understanding VIP Go file system constraints. The monolithic structure ensures all VIP file operations remain centralized and maintainable.

2. Media Upload Operations

Changes to upload handling in files.php can break media uploads on production VIP Go sites. All upload operations must:

• Use wp_handle_upload() or wp_handle_sideload() (WordPress VIP approved functions)
• Store metadata in WordPress database tables (vipbp-avatars, vipbp-group-avatars, vipbp-user-cover, vipbp-group-cover)
• Generate VIP FHS URLs with dynamic transformation parameters
• Never create multiple physical file sizes (rely on CDN transformations)

3. BuddyPress Dependency

The plugin hooks into BuddyPress initialization via the bp_loaded action in buddypress-vip-go.php17-33 Test environments must have BuddyPress installed and active before this plugin activates, or integration tests will fail.

4. Environment Detection

The plugin only loads its integration layer when VIP Go environment markers are detected in buddypress-vip-go.php23-27:

• class_exists( 'A8C_Files' )
• defined( 'FILES_CLIENT_SITE_ID' )
• defined( 'FILES_ACCESS_TOKEN' )

Changes to this detection logic affect whether the plugin activates on VIP Go sites.

Sources: AGENTS.md64-78 files.php1-999 buddypress-vip-go.php1-35

Development Workflow Pitfalls

Pitfall	Why It Happens	How to Avoid
CI rejects code with standard violations	VIP enforces strict PHPCS rules	Run composer cs before committing
Integration tests fail in wp-env	wp-env not running or BuddyPress not installed	Run npx wp-env start and verify BuddyPress is active
Unit tests pass but integration tests fail	Different test environments (BrainMonkey vs real WordPress)	Run both test suites: composer test:unit and composer test:integration
Changes break media on VIP Go	Local environment doesn't replicate VIP FHS behavior	Review System Architecture and test on VIP Go staging environment

Sources: AGENTS.md69-78 composer.json52-54

Architectural Constraints

Understanding why the plugin is structured as it is helps avoid introducing bugs:

Design Principle: Metadata-Driven Transformations

Design Rationale: VIP Go's distributed file system makes pre-generating multiple image sizes inefficient and complex. Instead, the plugin stores only the original file and transformation metadata, relying on VIP FHS's Photon-like CDN to perform transformations on-demand.

Code Implementation:

• Metadata storage: files.php86-129 (avatar metadata functions)
• URL generation: files.php295-354 (avatar URL filters)
• Dynamic parameters: ?w=150&crop={x},{y},{w},{h}&resize=150,150&strip=info

Sources: README.md24-41 files.php1-999

Design Principle: Hook Priority Orchestration

The plugin must register certain filters before BuddyPress initializes to prevent filesystem errors:

Critical Hooks:

• bp_core_avatar_folder_dir - Must return empty string before BuddyPress attempts opendir() files.php230-232
• bp_avatar_history_dir - Must disable avatar history to prevent filesystem access files.php233-235
• bp_core_pre_avatar_handle_upload - Must override upload handler before BuddyPress processes uploads files.php102-117

Sources: buddypress-vip-go.php17-33 files.php55-83

Design Principle: Temporary Directory Workaround

BuddyBoss video uploads require flock() for chunked assembly, which VIP FHS doesn't support. The solution uses a two-stage upload:

Code Implementation:

• Temp directory filter: files.php424-436
• Cleanup hook: files.php440-454
• Cache invalidation: files.php459-469

Sources: files.php424-469 README.md43-46

Development Requirements

The plugin has specific technical requirements that must be met before development can begin:

Requirement	Version	Purpose	Installation
PHP	8.2+	Minimum runtime version	System package manager
Composer	2.x	Dependency and script management	getcomposer.org
wp-env	Latest	Local WordPress environment	npm install -g @wordpress/env
Node.js	16+	Required by wp-env	nodejs.org
Docker	Latest	Backend for wp-env	docker.com
BuddyPress	Latest	Required plugin dependency	Installed via wp-env

Note: BuddyPress must be installed and active in the test environment for integration tests to run successfully.

Sources: composer.json21-23 AGENTS.md72-74

Development Toolchain Architecture

The following diagram shows how the development tools interact and what they validate:

Purpose: This diagram illustrates the development toolchain flow from code changes through local validation and CI/CD checks. All code changes must pass PHP syntax validation, VIP coding standards, compatibility checks, and automated tests before being merged.

Sources: composer.json44-67 .claude/CLAUDE.md17-21

Essential Composer Scripts

The plugin provides a comprehensive set of Composer scripts for development tasks. These scripts are the primary interface for local development workflows:

Purpose: This diagram maps the available Composer scripts and their relationships. The scripts are organized by function: code quality validation, testing, coverage analysis, and internationalization.

Sources: composer.json44-67

Core Commands Reference

Command	Purpose	Output	When to Use
composer lint	Validates PHP syntax across all files	Terminal output with syntax errors	Before committing (catches parse errors)
composer cs	Checks code against VIP standards	List of coding standard violations	Before committing (required by CI)
composer cs-fix	Auto-fixes coding standard violations	Modified files and remaining issues	After composer cs finds issues
composer test:unit	Runs unit tests (BrainMonkey mocks)	PHPUnit test results	Testing isolated logic without WordPress
composer test:integration	Runs integration tests with WordPress	PHPUnit test results with WP context	Testing WordPress-dependent behavior
composer test:integration-ms	Runs multisite integration tests	PHPUnit test results in multisite mode	Testing multisite-specific functionality
composer coverage	Generates HTML coverage report	./build/coverage-html/ directory	Analyzing test coverage locally
composer i18n	Generates translation template	./languages/buddypress-vip-go.pot	Preparing translations

Critical: CI will reject commits that fail composer cs. Always run code standards checks before pushing.

Sources: composer.json44-67 AGENTS.md69-78

Standard Development Workflow

The recommended workflow ensures code quality and prevents CI failures:

Workflow Notes:

• Integration tests require wp-env start to be running
• BuddyPress must be installed in the wp-env environment
• The cs-fix command can auto-fix most standard violations, but some require manual fixes
• CI runs the same checks as local commands, so passing locally should pass in CI

Sources: composer.json44-67 AGENTS.md69-78

Quick Start Commands

For a typical development session, run this sequence:

Common Issues:

Error	Cause	Solution
composer test:integration fails with "BuddyPress not found"	BuddyPress not installed in wp-env	Install BuddyPress via wp-env: wp-env run cli wp plugin install buddypress --activate
composer cs finds violations after composer cs-fix	Some violations require manual fixes	Review PHPCS output and fix manually
Integration tests fail locally but pass in CI	Different wp-env or BuddyPress versions	Match CI versions: WordPress 6.6, PHP 8.2 (see .github/workflows/integration.yml)

Sources: composer.json44-67 AGENTS.md69-78

Development Dependencies

The plugin uses several key development dependencies that enforce code quality and enable testing:

Package	Purpose	Version
automattic/vipwpcs	WordPress VIP coding standards	^3
php-parallel-lint/php-parallel-lint	Parallel PHP syntax checking	^1.0
phpcompatibility/phpcompatibility-wp	PHP version compatibility	^2.1
phpunit/phpunit	Unit and integration testing	^9.6
yoast/wp-test-utils	WordPress test utilities	^1.2

These dependencies are automatically installed via composer install and should not be committed to the repository (they are excluded via .distignore).

Sources: composer.json25-30

Code Organization and Key Files

The plugin follows a flat file structure focused on the core integration layer:

Key File Responsibilities:

File	Lines	Purpose	Entry Points
buddypress-vip-go.php	~35	Bootstrap, environment detection, conditional loading	vip_init_buddypress_media()
files.php	~999	All VIP FHS integration, hook registration, media operations	30+ filter/action callbacks
tests/Unit/	Various	Unit tests with BrainMonkey mocks	Extends YoastTestCase
tests/Integration/	Various	Integration tests with real WordPress	Extends WPIntegration\TestCase

Critical Functions in files.php:

• vipbp_handle_avatar_upload() - Avatar upload handler files.php102-117
• vip_handle_cover_image_upload() - Cover image upload handler files.php140-158
• vipbp_get_user_avatar_metadata() - Retrieve avatar metadata files.php86-103
• vipbp_default_avatar_user() - Generate avatar URLs with dynamic params files.php295-354
• vipbp_filter_chunked_upload_temp_dir() - Video upload temp dir workaround files.php424-436

Sources: buddypress-vip-go.php1-35 files.php1-999 composer.json1-68

Autoloader Configuration

The plugin uses PSR-4 autoloading for development code, specifically the test namespace:

This configuration maps the Automattic\BuddyPressVIPGo\Tests namespace to the tests/ directory, enabling automatic loading of test helper classes and utilities.

Sources: composer.json32-36

Contribution Prerequisites

Before contributing code, developers must:

1. Understand VIP Go Platform Constraints

Review the following pages to understand why the code is structured as it is:

• System Architecture - Overall plugin design and VIP FHS integration
• VIP File Hosting Service Integration - How CDN and dynamic transformations work
• Metadata Storage Architecture - Why metadata is stored instead of generating file sizes

Critical Understanding: This plugin exists because VIP Go's distributed file system does not support standard PHP filesystem operations. Do not introduce code that assumes local filesystem access.

2. Set Up Required Tools

Tool	Minimum Version	Verification Command
PHP	8.2	php -v
Composer	2.0	composer --version
Node.js	16	node --version
Docker	20.10	docker --version

3. Review Code Quality Requirements

Read Code Quality and Standards for:

• PHPCS configuration in .phpcs.xml.dist
• WordPress VIP coding standards (WordPress-VIP-Go ruleset)
• PHP 8.2+ compatibility requirements
• Internationalization requirements (buddypress-vip-go text domain)

4. Understand Testing Requirements

Read Testing Infrastructure for:

• When to write unit tests vs integration tests
• How to use YoastTestCase for unit tests (BrainMonkey)
• How to use WPIntegration\TestCase for integration tests (real WordPress)
• How to run tests locally and in CI

5. Study the Core Integration Layer

Before modifying files.php understand:

• Hook registration timing (why some hooks must fire before bp_init priority 8)
• Metadata storage structure (vipbp-avatars, vipbp-group-avatars, etc.)
• Dynamic URL generation with query parameters
• The chunked video upload workaround for flock() incompatibility

Plugin Maturity: The plugin is classified as "Tier 3" in the internal audit, indicating it needs ongoing modernization. Improvements to testing and documentation are welcome, but changes should be incremental and thoroughly tested.

Sources: AGENTS.md64-78 README.md1-62

Next Steps

For detailed information about specific aspects of development:

• Environment Setup: See Local Development Setup for complete wp-env configuration and installation
• Writing Tests: See Testing Infrastructure for test suite organization and writing tests
• Code Standards: See Code Quality and Standards for PHPCS configuration and VIP standards compliance
• Building Packages: See Build and Distribution Process for creating production-ready builds
• CI/CD Details: See CI/CD Pipeline for GitHub Actions workflow configuration

Sources: composer.json1-68 .claude/CLAUDE.md1-26