Development Setup

This page documents the local development environment setup for the Auth0 WordPress plugin. It covers cloning the repository, installing dependencies via Composer, configuring optional PSR-18/PSR-17 implementations, and verifying the setup. For information about running tests, see Testing Framework. For build and distribution procedures, see Build and Packaging.

Prerequisites

The development environment requires specific PHP versions, extensions, and tools as defined in the project configuration.

Required Software

Requirement	Version	Purpose
PHP	^8.1	Runtime environment
Composer	Latest 2.x	Dependency management
ext-json	*	JSON encoding/decoding
ext-openssl	*	Cryptographic operations

Sources: composer.json35-40

Development Dependencies

The plugin uses several development tools managed through Composer's require-dev section:

Category	Tools
Testing	pestphp/pest, mockery/mockery
Static Analysis	phpstan/phpstan, vimeo/psalm
Code Quality	friendsofphp/php-cs-fixer, rector/rector
Build Tools	humbug/php-scoper
PSR Implementations	nyholm/psr7, symfony/cache, psr-mock/http
WordPress Integration	szepeviktor/phpstan-wordpress

Sources: composer.json42-58

Repository Setup

Clone the Repository

Directory Structure for Development

wordpress/
├── src/ # Plugin source code (PSR-4: Auth0\WordPress\)
├── tests/ # Test suite (PSR-4: Auth0\Tests\)
│ └── Unit/ # PHPUnit/Pest unit tests
├── vendor/ # Composer dependencies (git-ignored)
├── build/ # Build artifacts (created by build.sh)
├── composer.json # Dependency configuration
├── composer.lock # Locked dependency versions
├── composer.local.json # Optional local overrides (git-ignored)
├── phpunit.xml.dist # PHPUnit configuration template
├── build.sh # Build and packaging script
└── wpAuth0.php # Plugin bootstrap file

Sources: composer.json61-69

Dependency Installation

Initial Setup

Install all dependencies including development tools:

This command:

1. Reads composer.json and composer.lock
2. Downloads all required and dev dependencies
3. Generates the PSR-4 autoloader for Auth0\WordPress\ and Auth0\Tests\ namespaces
4. Applies optimized autoloader configuration
5. Merges composer.local.json if present (via wikimedia/composer-merge-plugin)

Sources: composer.json61-69 composer.json83-95

Update Dependencies

To update dependencies to their latest compatible versions:

Warning: This updates composer.lock and may introduce breaking changes. Run the full test suite after updating.

Understanding the Dependency Graph

The following diagram maps the plugin's runtime and development dependencies to their actual package names and purposes:

Diagram: Composer Dependency Graph

Sources: composer.json35-58

Critical Dependency Notes

auth0/auth0-php: The Auth0 PHP SDK requires PSR-18 (HTTP Client) and PSR-17 (HTTP Factory) implementations but does not bundle them. These must be provided either by the WordPress environment or via composer.local.json.

psr/cache: Required for token caching. The SDK can use any PSR-6 compatible cache implementation.

humbug/php-scoper: Used during the build process to namespace vendor dependencies under Auth0\WordPress\Vendor\, preventing conflicts with other WordPress plugins.

Sources: composer.json35-40 composer.json42-43

Development Workflow

Composer Scripts

The plugin provides several Composer scripts for common development tasks:

Diagram: Development Scripts Workflow

Sources: composer.json97-117

Script Descriptions

Script	Command	Purpose
pest	@php vendor/bin/pest --order-by random --fail-on-risky --parallel --no-progress	Run all Pest tests in random order with parallel execution
pest:coverage	@php vendor/bin/pest --order-by random --fail-on-risky --coverage --parallel --no-progress	Generate code coverage reports
pest:debug	@php vendor/bin/pest --log-events-verbose-text pest.log --display-errors --fail-on-risky --no-progress	Run tests with verbose logging for debugging
pest:profile	@php vendor/bin/pest --profile	Profile test execution time
phpstan	@php vendor/bin/phpstan analyze	Run PHPStan static analysis
psalm	@php vendor/bin/psalm	Run Psalm static analysis
psalm:fix	@php vendor/bin/psalter --issues=all	Auto-fix Psalm issues
phpcs	@php vendor/bin/php-cs-fixer fix --dry-run --diff	Check code style without fixing
phpcs:fix	@php vendor/bin/php-cs-fixer fix	Auto-fix code style issues
rector	@php vendor/bin/rector process src --dry-run	Check for code modernization opportunities
rector:fix	@php vendor/bin/rector process src	Apply Rector refactoring
build	./build.sh	Execute the build script
test	Composite	Run all quality checks (pest, phpstan, psalm, rector, phpcs)

Sources: composer.json97-117

Recommended Development Workflow

1. Make code changes in src/ directory
2. Run quick tests: composer pest
3. Run full validation: composer test
4. Fix issues: Use composer phpcs:fix, composer psalm:fix, composer rector:fix as needed
5. Verify: Run composer test again to ensure all checks pass
6. Commit changes when all checks pass

composer.local.json Configuration

The plugin uses the wikimedia/composer-merge-plugin to support a local configuration file for environment-specific dependency overrides.

Purpose

composer.local.json allows developers to:

• Provide custom PSR-18 HTTP client implementations
• Provide custom PSR-17 HTTP factory implementations
• Override any dependency version for local testing
• Add project-specific development tools

This file is git-ignored and never committed to the repository.

Sources: composer.json83-95

Merge Plugin Configuration

The merge plugin is configured with the following settings:

Setting	Value	Meaning
ignore-duplicates	false	Report errors for duplicate package definitions
include	["composer.local.json"]	Merge this file if it exists
merge-dev	true	Merge both require and require-dev sections
merge-extra	false	Do not merge extra section
merge-extra-deep	false	Do not deep-merge extra section
merge-scripts	false	Do not merge scripts section
recurse	true	Recursively process merged files
replace	true	Replace existing package versions

Sources: composer.json84-94

Example composer.local.json

To provide PSR-18 and PSR-17 implementations for development:

After creating this file, run:

The merge plugin will combine this with the main composer.json during the install/update process.

Common Use Cases

Case 1: Testing with Guzzle

Case 2: Testing with Symfony HTTP Client

Case 3: Adding Local Development Tools

Sources: composer.json83-95

Autoloader Configuration

The plugin uses PSR-4 autoloading for both production and development code:

Diagram: Autoloader Configuration

Sources: composer.json61-81

Autoloader Settings

Setting	Value	Impact
optimize-autoloader	true	Generates class map for faster autoloading in production
preferred-install	dist	Downloads distribution archives instead of cloning repositories
process-timeout	0	No timeout for long-running operations
sort-packages	true	Alphabetically sorts packages in composer.json

Sources: composer.json71-81

PHPUnit Configuration for Development

Test configuration is defined in phpunit.xml.dist:

Test Suites

Suite	Directory	Purpose
unit	tests/Unit/	Unit tests for all plugin classes

Sources: phpunit.xml.dist9-13

Coverage Configuration

Coverage reports are generated in two formats:

• Clover XML: coverage/clover.xml
• Cobertura XML: coverage/cobertura.xml

These formats are compatible with most CI/CD platforms and coverage analysis tools.

Sources: phpunit.xml.dist3-8

Source Code Coverage

Coverage analysis includes all files in src/ except:

• src/Events/ - Event classes (excluded)
• src/Exceptions/ - Exception classes (excluded)

Sources: phpunit.xml.dist17-25

Environment Variables

Variable	Value	Purpose
CACHE_DRIVER	array	Use in-memory array cache for tests

Sources: phpunit.xml.dist14-16

Verification Steps

After completing the development setup, verify the environment is correctly configured:

1. Verify PHP Version

Expected output: PHP 8.1.x or higher

2. Verify Extensions

Expected output:

json
openssl

3. Verify Composer Installation

Expected output: Composer version 2.x

4. Verify Autoloader

This should complete without errors and generate:

• vendor/autoload.php
• vendor/composer/autoload_psr4.php

5. Run Test Suite

This runs the comprehensive test suite including:

• Pest unit tests
• PHPStan static analysis
• Psalm static analysis
• Rector code quality checks
• PHP-CS-Fixer code style validation

All checks should pass on a clean checkout.

6. Verify Build System

This executes build.sh which should:

• Clean previous builds
• Install scoped dependencies
• Create a distributable ZIP file
• Generate a digital signature

The build artifacts appear in the build/ directory.

Sources: composer.json97-117

Common Issues and Solutions

Issue: Missing PSR-18/PSR-17 Implementation

Error:

Could not find a PSR-18 HTTP client implementation

Solution: Create composer.local.json with a compatible implementation:

Then run:

Issue: Composer Plugin Not Allowed

Error:

wikimedia/composer-merge-plugin contains a Composer plugin which is blocked by your allow-plugins config

Solution: The plugin is already allowed in composer.json. If this error persists, run:

Sources: composer.json72-77

Issue: Memory Limit During Testing

Error:

Fatal error: Allowed memory size exhausted

Solution: Increase PHP memory limit for Composer:

Or update php.ini:

Next Steps

After setting up the development environment:

1. Review Testing Framework: See Testing Framework for detailed information about running and writing tests
2. Understand Code Quality Tools: See Code Quality Tools for static analysis and formatting guidelines
3. Learn Build Process: See Build and Packaging for distribution procedures
4. Explore Extension Patterns: See Extending the Plugin for customization approaches

Sources: composer.json1-118 phpunit.xml.dist1-27