Development

This page provides guidance for developers working with or extending the Auth0 WordPress plugin codebase. It covers the development environment structure, available tooling, testing practices, and how to programmatically interact with the plugin.

For details on specific topics:

• Local development environment setup: see Development Setup
• Testing framework and test execution: see Testing Framework
• Static analysis and code quality tools: see Code Quality Tools
• Build process and dependency scoping: see Build and Packaging
• Using the plugin in custom development: see Extending the Plugin
• Configuration options available: see Configuration Options
• Plugin API reference: see Plugin API Reference

Development Environment Structure

The plugin uses a standard PHP development environment with Composer for dependency management and PSR-4 autoloading. The codebase is organized to separate production code from development tooling and tests.

Directory and File Structure

Path	Purpose
src/	Production source code organized under Auth0\WordPress namespace
tests/	Test suites organized under Auth0\Tests namespace
vendor/	Composer dependencies (gitignored, created by composer install)
build/	Production build output with scoped dependencies (gitignored)
wpAuth0.php	Plugin entry point that bootstraps the plugin
composer.json	Dependency declarations and development scripts
phpunit.xml.dist	PHPUnit/Pest test framework configuration
phpstan.neon	PHPStan static analysis configuration
psalm.xml	Psalm static analysis configuration
rector.php	Rector refactoring rules configuration
.php-cs-fixer.php	PHP-CS-Fixer code style configuration
scoper.inc.php	PHP-Scoper namespace prefixing configuration

Sources: README.md56-76 composer.json61-69

Composer Scripts

The plugin provides Composer scripts for common development tasks. All scripts are defined in composer.json97-117 and can be executed using composer <script-name>.

Available Scripts

Script	Command	Purpose
build	./build.sh	Execute full build process including dependency scoping
pest	@php vendor/bin/pest --order-by random --fail-on-risky --parallel --no-progress	Run test suite with Pest
pest:coverage	@php vendor/bin/pest --order-by random --fail-on-risky --coverage --parallel --no-progress	Run tests with code coverage reporting
pest:debug	@php vendor/bin/pest --log-events-verbose-text pest.log --display-errors --fail-on-risky --no-progress	Run tests with verbose debug logging
pest:profile	@php vendor/bin/pest --profile	Run tests with performance profiling
phpcs	@php vendor/bin/php-cs-fixer fix --dry-run --diff	Check code style without modifying files
phpcs:fix	@php vendor/bin/php-cs-fixer fix	Auto-fix code style violations
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 issues detected by Psalm
rector	@php vendor/bin/rector process src --dry-run	Check for available refactorings
rector:fix	@php vendor/bin/rector process src	Apply automated refactorings
test	Multiple	Run complete test suite: Pest, PHPStan, Psalm, Rector, PHP-CS-Fixer

Composite Test Command

The composer test command executes all quality assurance tools in sequence:

This runs:

1. @pest - Test suite execution
2. @phpstan - PHPStan static analysis
3. @psalm - Psalm static analysis
4. @rector - Rector refactoring checks
5. @phpcs - PHP-CS-Fixer code style checks

Sources: composer.json97-117

Development Dependencies

The plugin requires several development dependencies for testing and code quality assurance. These are declared in composer.json42-59

Key Development Dependencies

Package	Version	Purpose
pestphp/pest	^2	Modern PHP testing framework (PHPUnit wrapper)
mockery/mockery	^1	Object mocking for tests
phpstan/phpstan	^1	Static analysis for type checking
vimeo/psalm	^5	Alternative static analysis tool
friendsofphp/php-cs-fixer	^3	Automated code style fixing
rector/rector	0.17.0	Automated refactoring tool
humbug/php-scoper	^0.18	Namespace prefixing for distribution
nyholm/psr7	^1	PSR-7 HTTP message implementation
symfony/cache	^6	PSR-6 cache implementation

Sources: composer.json42-59

Plugin Access Pattern

The plugin provides the wpAuth0() helper function for accessing the plugin instance and the underlying Auth0-PHP SDK. This is the recommended pattern for custom development.

Plugin Singleton Access

Important Warning

The plugin's internal APIs are not stable and will change without notice. Do not extend or subclass the plugin's classes directly. Instead, use the wpAuth0() helper to access the Auth0-PHP SDK for custom development.

Usage Example

From README.md176-182:

The Plugin class exposes the following public methods:

Method	Return Type	Purpose
getSdk()	Auth0\SDK\Auth0	Returns configured Auth0-PHP SDK instance
getConfiguration()	Auth0\SDK\Configuration\SdkConfiguration	Returns SDK configuration object
run()	self	Initializes plugin hooks (called once during bootstrap)

Sources: README.md14-15 README.md169-184

Development Workflow

A typical development workflow involves making code changes, running tests and quality checks, and creating production builds.

Recommended Workflow Steps

1. Install Dependencies: Run composer install to fetch all development dependencies
2. Make Changes: Edit source code in src/ directory
3. Run Tests: Execute composer pest to verify functionality
4. Check Types: Run composer phpstan and composer psalm for type safety
5. Check Style: Run composer phpcs to verify code style compliance
6. Auto-fix: Use composer phpcs:fix and composer psalm:fix to automatically resolve issues
7. Full Validation: Run composer test to execute all quality checks
8. Build: Execute composer build (via ./build.sh) to create production-ready package

Development vs Production Autoloading

The plugin's bootstrap file wpAuth0.php checks for different autoloader files depending on the environment:

• Production: Loads scoper-autoload.php which includes scoped dependencies under Auth0\WordPress\Vendor namespace
• Development: Falls back to autoload.php for unscoped dependencies during development

This allows development to proceed with standard Composer dependencies while production builds use isolated, prefixed namespaces to prevent conflicts with other plugins.

Sources: composer.json97-117 README.md203-216

Test Configuration

The test suite uses PHPUnit/Pest configuration defined in phpunit.xml.dist1-27

Test Configuration Settings

Setting	Value	Purpose
Test Suite	tests/Unit/	Location of unit tests
Coverage Output	coverage/clover.xml, coverage/cobertura.xml	Code coverage report formats
Source Include	src/	Files to include in coverage analysis
Source Exclude	src/Events/, src/Exceptions/	Directories excluded from coverage
Environment	CACHE_DRIVER=array	Test environment configuration

Coverage Reports

When running composer pest:coverage, the test suite generates two coverage report formats:

• Clover XML: coverage/clover.xml - Machine-readable coverage data
• Cobertura XML: coverage/cobertura.xml - Compatible with CI/CD tools

Sources: phpunit.xml.dist1-27

Code Organization

The plugin's source code follows PSR-4 autoloading standards with a namespace structure that maps to the directory layout.

PSR-4 Autoload Configuration

From composer.json61-69:

Namespace	Directory	Environment
Auth0\WordPress\	src/	Production
Auth0\Tests\	tests/	Development

This configuration allows classes to be referenced by their fully-qualified namespace, with the autoloader automatically mapping to the correct file path.

Sources: composer.json61-69