Build and Packaging

This document details the build and packaging process for distributing the Auth0 WordPress plugin. It covers dependency management, namespace scoping to prevent conflicts, production build creation, archive generation, and digital signing. For information about development environment setup and testing, see Development Setup and Testing Framework. For details on the update mechanism that delivers these packages to users, see Updates and Versioning.

Overview

The plugin uses a sophisticated build pipeline to create production-ready distribution packages. The primary goals are:

1. Dependency Isolation: Prefix all vendor namespaces to prevent conflicts with other plugins
2. Production Optimization: Remove development dependencies and optimize autoloader
3. Integrity Verification: Digitally sign packages for security
4. Clean Distribution: Package only necessary files for WordPress installation

The build process is orchestrated by build.sh1-62 and uses PHP Scoper to transform the codebase into a conflict-free distribution.

Sources: build.sh1-62 composer.json1-119

Build Process Flow

Build Process Flow Diagram: Shows the complete build pipeline from version selection through package signing.

The build.sh1-62 script executes the following sequence:

1. Version Input build.sh31-34: Prompts for a semantic version number
2. Validation build.sh13-29: Validates version against semver regex ^([0-9]+\.){2}(\*|[0-9]+)(-.*)?$
3. Environment Cleanup build.sh37-42: Removes all build artifacts and vendor directories
4. Development Dependencies build.sh44-45: Installs all dependencies including dev tools
5. Namespace Prefixing build.sh47-48: Runs PHP Scoper to prefix vendor namespaces
6. Production Dependencies build.sh50-55: Installs production dependencies in build/ directory with optimized autoloader
7. Cleanup build.sh53-54: Removes Composer metadata files
8. Archiving build.sh57-58: Creates versioned ZIP file excluding .DS_Store files
9. Signing build.sh60-61: Generates SHA256 signature using private key

Sources: build.sh1-62

Composer Configuration

The composer.json1-119 file defines the plugin's dependency structure and build scripts:

Section	Purpose	Key Elements
require composer.json35-41	Production dependencies	auth0/auth0-php: ^8.18, psr/cache: ^3.0
require-dev composer.json42-59	Development tools	humbug/php-scoper, pestphp/pest, phpstan/phpstan, vimeo/psalm
autoload composer.json61-65	PSR-4 autoloading	Auth0\WordPress\ => src/
scripts composer.json97-117	Build and test commands	build, test, pest, phpstan, psalm, phpcs, rector
config composer.json71-82	Composer behavior	optimize-autoloader: true, preferred-install: dist

The build script composer.json98 is an alias for ./build.sh, allowing execution via composer build.

Sources: composer.json1-119

Dependency Scoping with PHP Scoper

Dependency Scoping Diagram: Illustrates how PHP Scoper transforms vendor namespaces while preserving plugin code.

The scoper.inc.php1-42 configuration controls the scoping process:

Scoper Configuration

prefix: "Auth0\\WordPress\\Vendor"

scoper.inc.php8 - All vendor namespaces are prefixed with this prefix.

File Selection

The finders configuration scoper.inc.php10-28 uses Symfony Finder to:

• Include all files from vendor/ and project root
• Exclude test directories: doc, test, tests, Tests, vendor-bin
• Exclude build artifacts: *.dist, Makefile, *.yml, build scripts
• Include composer.json for metadata

Namespace Exclusions

scoper.inc.php30-34 excludes namespaces that should not be prefixed:

Pattern	Reason
/^Auth0\\\\WordPress\\\\/	Plugin's own namespace must remain unchanged
/^Psr\\\\/	PSR interfaces are contracts that must not be prefixed

Global Exposure

scoper.inc.php36-38 disables exposure of global constants, classes, and functions to prevent namespace pollution.

Sources: scoper.inc.php1-42 build.sh47-48

Production Build Structure

After scoping completes, the build process enters the build/ directory and performs final optimization:

build/
├── src/
│ └── ... (unchanged plugin source)
├── vendor/
│ ├── auth0/
│ │ └── auth0-php/
│ │ └── ... (prefixed to Auth0\WordPress\Vendor\Auth0\SDK)
│ ├── guzzlehttp/
│ │ └── ... (prefixed)
│ ├── psr/
│ │ └── ... (PSR interfaces unchanged)
│ └── ...
├── scoper-autoload.php (generated by PHP Scoper)
├── wpAuth0.php (main plugin file)
└── ... (other plugin files)

The build.sh50-55 commands:

This:

1. Installs production dependencies only (no require-dev)
2. Generates optimized autoloader with class maps
3. Removes Composer metadata to reduce package size

Sources: build.sh50-55 .gitignore2

Archive Creation

The build.sh57-58 command creates the distribution archive:

Where ${filename} is constructed as Auth0_WordPress_${version}.zip build.sh35

Filename Convention

Format: Auth0_WordPress_X.Y.Z.zip

Example: Auth0_WordPress_5.3.0.zip

The archive contains the entire build/ directory with all subdirectories. The -x "*.DS_Store" flag excludes macOS metadata files.

Sources: build.sh35 build.sh57-58

Digital Signing

The build process signs the distribution package for integrity verification:

build.sh60-61

Signing Process

Component	Purpose
private-signing-key.pem	RSA private key for signing (not in repository)
SHA256 digest	Cryptographic hash algorithm
${filename}.sig	Binary signature file

The signature file (e.g., Auth0_WordPress_5.3.0.zip.sig) is distributed alongside the ZIP archive and can be verified using the corresponding public key.

Excluded from Repository

The .gitignore19-21 explicitly excludes signing artifacts:

• private-signing-key.pem - Private key must be kept secure
• build.zip - Build artifact
• build.zip.sig - Signature artifact

Sources: build.sh60-61 .gitignore19-21

Build Artifacts

The complete build process generates the following artifacts:

Build Artifacts Diagram: Shows generated files and their exclusion from version control.

All artifacts are excluded from version control via .gitignore2 (build), .gitignore20 (build.zip), and .gitignore21 (build.zip.sig).

Sources: .gitignore2 .gitignore20-21

Integration with Update System

The build package connects to the WordPress update system through two components:

Version Manifest

The updates.json1-6 file tracks available versions:

Each version entry maps to the corresponding ZIP filename produced by the build process.

Updates Action Class

The Updates class src/Actions/Updates.php1-38 hooks into WordPress's transient update system:

registry: [
 'site_transient_update_plugins' => 'doUpdateCheck',
 'transient_update_plugins' => 'doUpdateCheck'
]

src/Actions/Updates.php12-15

The doUpdateCheck method src/Actions/Updates.php17-37 modifies the plugin update object to inject custom update information. While currently commented out src/Actions/Updates.php29-34 this mechanism can provide update notifications from a custom updates manifest rather than WordPress.org.

Sources: updates.json1-6 src/Actions/Updates.php1-38

Build Script Invocation

Developers can invoke the build process through multiple methods:

Direct Execution

Via Composer

composer.json98

Both methods execute the same build.sh1-62 script. The Composer script alias provides consistency with other development commands like composer test.

Sources: composer.json98 build.sh1-62

Quality Assurance Integration

While not part of the build script itself, the composer.json97-117 defines quality assurance commands that should be run before building:

Command	Purpose	Script Reference
composer test	Run all QA checks	composer.json110-116
composer pest	Execute test suite	composer.json99
composer phpstan	Static analysis	composer.json105
composer psalm	Type checking	composer.json106
composer phpcs	Code style check	composer.json103
composer rector	Refactoring check	composer.json108

The composite test command runs all checks sequentially, ensuring code quality before distribution. See Code Quality Tools for detailed documentation of these tools.

Sources: composer.json97-117