Static Analysis with PHPStan

Purpose and Scope

This document describes the PHPStan static analysis configuration for the maho-composer-plugin codebase. PHPStan performs maximum-strictness analysis (level 10) with bleeding edge features, strict rules, and deprecation detection to enforce code quality standards across all plugin implementations. This page covers the configuration file structure, included rulesets, PHP version compatibility range (8.2-8.4), and the GitHub Actions integration that runs analysis on every push and pull request. For information about other CI/CD workflows, see page 6.2.

Sources: .phpstan.dist.neon1-13 .github/workflows/phpstan.yml1-46

---

PHPStan Configuration File

The static analysis configuration is defined in .phpstan.dist.neon, which establishes a multi-layered ruleset by including external rule configurations and setting project-specific parameters.

Configuration Structure

Sources: .phpstan.dist.neon1-13

Included Rulesets

The configuration includes four external rule files that extend PHPStan's analysis capabilities:

Ruleset	Include Path	Purpose
Bleeding Edge	vendor/phpstan/phpstan/conf/bleedingEdge.neon	Enables unreleased PHPStan features that will be in next major version, providing early access to stricter checks
Strict Rules	vendor/phpstan/phpstan-strict-rules/rules.neon	Enforces additional type safety constraints beyond standard level 10, including stricter comparison checks and variable usage validation
Deprecation Rules	vendor/phpstan/phpstan-deprecation-rules/rules.neon	Detects usage of deprecated PHP features and Composer API methods, preventing reliance on deprecated functionality
Composer Rules	vendor/composer/composer/phpstan/rules.neon	Provides Composer-specific validation rules for plugin implementations, ensuring correct usage of Composer APIs

Sources: .phpstan.dist.neon1-5

PHP Version Compatibility Range

The phpVersion parameter constrains analysis to PHP 8.2 through 8.4:

This configuration ensures PHPStan validates compatibility across this version range, preventing usage of:

• PHP features introduced after 8.4
• Deprecated features removed in 8.2 or later
• Type declarations incompatible with any version in the range

Sources: .phpstan.dist.neon7-9

Strictness Level

The analysis operates at level: 10, which is PHPStan's maximum strictness level. This enforces:

• Complete type coverage for all properties, parameters, and return values
• Dead code detection for unreachable statements
• Strict validation of array shapes and property access
• Detection of impossible type assertions and conditions
• Validation of all method calls against actual class definitions

Sources: .phpstan.dist.neon12

Analysis Scope

The paths parameter restricts analysis to the src directory, which contains all plugin implementations:

File	Class	Lines	Purpose
src/FileCopyPlugin.php	FileCopyPlugin	~271	Asset deployment plugin
src/AutoloadPlugin.php	AutoloadPlugin	~71	Autoload configuration plugin
src/ModmanPlugin.php	ModmanPlugin	~205	Module symlink management plugin
src/AutoloadRuntime.php	AutoloadRuntime	~242	Runtime package discovery utility

Sources: .phpstan.dist.neon10-11

---

GitHub Actions Integration

The .github/workflows/phpstan.yml workflow automates static analysis execution on every code change, running PHPStan against both the target branch and pull request head to detect new issues.

Workflow Execution Flow

Sources: .github/workflows/phpstan.yml1-46

Workflow Triggers

The workflow executes on multiple event types defined in .github/workflows/phpstan.yml3-7:

Event Type	Trigger Condition	Branch Analyzed
push	Any commit pushed to repository	The pushed branch (github.ref_name)
pull_request	PR created or updated	Both target branch (github.base_ref) and PR head (github.head_ref)
workflow_call	Called by another workflow	Caller-specified reference
workflow_dispatch	Manually triggered	Current branch

Sources: .github/workflows/phpstan.yml3-7

Matrix Strategy: Target Branch vs PR Head

The workflow uses a matrix strategy to analyze both the target branch and the PR head separately during pull request events:

This configuration creates two parallel jobs for pull requests:

Matrix Job	Checkout Reference	Purpose
target-branch	github.base_ref (PR target)	Establish baseline analysis result
pr-head	github.event.pull_request.head.sha	Detect issues introduced in PR

The exclude clause prevents the pr-head job from running on non-PR events (push, workflow_call, workflow_dispatch).

Sources: .github/workflows/phpstan.yml13-18 .github/workflows/phpstan.yml26-28

Execution Steps

The workflow performs seven sequential steps:

1. PHP Environment Setup

Uses latest PHP version (currently 8.4) for analysis, ensuring compatibility with the upper bound of the configured range.

Sources: .github/workflows/phpstan.yml21-24

2. Code Checkout

The checkout step uses conditional logic to select the appropriate Git reference:

• For pr-head matrix job: checks out github.event.pull_request.head.sha
• For target-branch matrix job and push events: checks out default branch

Sources: .github/workflows/phpstan.yml26-28

3. Composer Cache Configuration

Determines the Composer cache directory path and outputs it for subsequent steps:

Sources: .github/workflows/phpstan.yml30-32

4. Dependency Caching

Caches Composer dependencies using the composer.lock file hash as the cache key, with fallback to OS-specific cache. This significantly reduces workflow execution time on subsequent runs.

Sources: .github/workflows/phpstan.yml34-39

5. Dependency Installation

Installs dependencies with --ignore-platform-req=ext-* to bypass PHP extension requirements, as the analysis doesn't require actual extension loading.

Sources: .github/workflows/phpstan.yml41-42

6. PHPStan Analysis Execution

Executes PHPStan with:

• XDEBUG_MODE=off: Disables Xdebug to improve performance
• -vvv: Maximum verbosity for detailed diagnostic output
• Implicit configuration: Reads .phpstan.dist.neon automatically

Sources: .github/workflows/phpstan.yml44-45

---

Analysis Coverage and Error Detection

Source Files Analyzed

PHPStan analyzes all PHP files in the src/ directory, covering the complete plugin implementation:

Sources: .phpstan.dist.neon10-11

Error Detection Capabilities

The combination of level 10 analysis plus four additional rulesets enables comprehensive error detection across multiple categories:

Error Category	Detected Issues	Ruleset Source
Type Violations	Missing type declarations, incorrect type assignments, invalid array access, undefined properties	Level 10 base rules
Strict Comparisons	Non-strict comparisons (== vs ===), loose boolean checks, implicit type coercions	phpstan-strict-rules
Dead Code	Unreachable statements, always-true/false conditions, unused variables, redundant type checks	Level 10 + bleeding edge
Deprecations	Usage of @deprecated methods, deprecated PHP features (8.2-8.4 range), deprecated Composer APIs	phpstan-deprecation-rules
Composer API	Incorrect plugin interface implementations, invalid event subscriber patterns, misused Composer classes	composer/phpstan/rules.neon
Bleeding Edge	Future breaking changes, stricter type interpretations, new analysis patterns	bleedingEdge.neon

Sources: .phpstan.dist.neon1-5 .phpstan.dist.neon12

Local Development Usage

Developers can run PHPStan locally using the same configuration:

The .phpstan.dist.neon configuration is version-controlled, ensuring local analysis matches CI behavior. Developers can create a local .phpstan.neon file (excluded by .gitignore) to override configuration for development purposes.

Sources: .phpstan.dist.neon1-13 .github/workflows/phpstan.yml44-45

---

Quality Gate Integration

PHPStan serves as a mandatory quality gate in the development workflow. The workflow's fail-fast: false setting ensures both matrix jobs complete even if one fails, providing complete diagnostic information. Any PHPStan errors cause the workflow to fail with a non-zero exit code, blocking pull request merges until all issues are resolved.

The maximum strictness configuration (level 10 + all additional rules) ensures the plugin codebase maintains high code quality standards and API compatibility across the PHP 8.2-8.4 version range.

Sources: .github/workflows/phpstan.yml14 .github/workflows/phpstan.yml44-45