Development Guide

This page is the parent for all contributor-facing documentation. It covers the toolchain architecture, the relationship between the project's quality-enforcement tools, and the overall development workflow. For step-by-step setup instructions see Development Environment Setup; for test execution see Testing Framework; for linter and static-analysis configuration see Code Quality Tools; for PHAR packaging and tagging see Build and Release Process; and for GitHub Actions automation see CI/CD Workflows.

---

Toolchain Overview

The project enforces code quality through a layered set of tools coordinated via composer scripts. The checks script in composer.json222-242 is the canonical gate that runs before every commit (via git hooks) and is the reference checklist for contributors.

Toolchain map:

Layer	Tool	Composer Script
Formatting	php-cs-fixer	style-lint / style-fix
Static analysis	phpstan	phpstan
Automated refactoring	rector	rector-dry-run / rector
Tests	pest	pest
Dependency audit	composer-dependency-analyser	composer-dependency-analyser
Magic-number detection	phpmnd	phpmnd
Merge-conflict check	swiss-knife	sk-check-conflicts
Commented-code check	swiss-knife	sk-check-commented-code
Markdown linting	lint-md	md-lint
YAML linting	yaml-lint	yaml-lint
Git hooks	brainmaestro/composer-git-hooks	cghooks

Sources: composer.json185-439

---

Development Workflow Diagram

Contributor workflow and tool invocation order

Sources: composer.json222-242

---

Key Scripts Reference

All scripts are defined in the scripts section of composer.json185-439 The table below lists the most frequently used ones.

Script alias	What it runs
composer checks	Full pre-commit gate (see diagram above)
composer pest	pest --colors=always --min=80 --coverage
composer pest-coverage	Pest with HTML and Clover coverage output
composer phpstan	phpstan analyse --ansi -v
composer phpstan-baseline	Regenerate phpstan baseline
composer rector	Apply Rector refactors
composer rector-dry-run	Preview Rector changes only
composer style-fix	php-cs-fixer fix
composer style-lint	php-cs-fixer fix --dry-run --diff
composer composer-dependency-analyser	Run shipmonk/composer-dependency-analyser
composer release	Invoke monorepo-builder release
composer vhs	Record demo GIFs via VHS

Sources: composer.json185-439

---

Tool-to-File Mapping

Where each tool's configuration lives

Sources: composer.json176-184 rector.php71-297

---

Git Hooks

Git hooks are managed by brainmaestro/composer-git-hooks. The hook configuration is embedded directly in composer.json176-184:

"hooks": {
 "post-merge": ["composer checks"],
 "pre-commit": ["composer checks"]
}

Hooks are installed automatically as part of post-install-cmd by running cghooks add --ignore-lock and cghooks update. They can be manually re-installed via composer cghooks-install or temporarily removed with composer cghooks-uninstall (used, for example, when recording VHS demos).

Sources: composer.json176-184 composer.json214-221

---

PHP Version and Runtime Requirements

Requirement	Value
Minimum PHP version	>=8.2
Target PHP version (Rector)	PhpVersion::PHP_82
Required extensions	ext-curl, ext-mbstring

rector.php102-104 pins the Rector downgrade and PHP sets to PHP 8.2. composer.json59-62 declares runtime requirements.

Sources: composer.json58-67 rector.php102-104

---

Vendor-Bin Tools

Several additional tools are managed through bamarni/composer-bin-plugin, which stores them isolated under vendor-bin/. The composer-bin-all-update script updates all of them. The bamarni-bin configuration is set in composer.json164-168:

"bamarni-bin": {
 "bin-links": true,
 "forward-command": true,
 "target-directory": "vendor-bin"
}

This means each tool group under vendor-bin/ has its own composer.json and is kept separate from the main dependency graph.

Sources: composer.json164-168 composer.json247-248

---

Xdebug Mode Management

The checks script explicitly toggles Xdebug around test execution to avoid performance overhead for other tools. Three environment-control scripts handle this:

Script	Effect
env-put-xdebug-off	Sets XDEBUG_MODE=off
env-put-xdebug-on	Sets XDEBUG_MODE=coverage,debug and XDEBUG_SESSION=1

The pattern inside checks is: disable Xdebug → run all linters and static analysis → enable Xdebug → run Pest → disable Xdebug again → run Rector and PHPStan.

Sources: composer.json222-242 composer.json280-284

---

Child Pages

Page	Topic
Development Environment Setup	Cloning, composer install, git hooks, vendor-bin tools
Testing Framework	Pest setup, Feature/Unit suites, HTTP fakes, PHPMock
Code Quality Tools	PHP-CS-Fixer, PHPStan, Rector configuration details
Build and Release Process	PHAR build, box.json, monorepo-builder release workers
CI/CD Workflows	GitHub Actions: tests matrix, auto-merge, labeler, PHPStan