CI/CD Pipeline

Purpose and Scope

This document describes the Continuous Integration and Continuous Delivery (CI/CD) pipeline for the maho-phpstan-plugin. The pipeline automatically validates code quality by running PHPStan analysis against multiple PHP versions on every push and pull request.

For information about local development setup, see Development Setup. For details about the plugin's architecture, see Architecture.

Overview

The maho-phpstan-plugin uses GitHub Actions to provide automated testing and validation. The CI/CD pipeline is defined in a single workflow file that runs PHPStan analysis across a matrix of PHP versions to ensure compatibility and code quality.

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

Workflow Architecture

Workflow Triggers: The on: key defines two event triggers without branch restrictions: push and pull_request .github/workflows/phpstan.yml3-5

Job Definition: The jobs.phpstan key defines a single job with name: "PHPStan Analysis" that executes on runs-on: ubuntu-latest runners .github/workflows/phpstan.yml8-10

Matrix Strategy: The strategy.matrix.php-version array contains three string values: '8.3', '8.4', and '8.5'. GitHub Actions creates three parallel job instances by iterating over this array .github/workflows/phpstan.yml12-14

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

Configuration Integration

The workflow integrates with two configuration files that control PHPStan's behavior:

PHPStan Configuration (.phpstan.dist.neon):

• includes: Loads bleeding-edge features, strict rules, and deprecation rules .phpstan.dist.neon1-4
• parameters.phpVersion: Specifies minimum PHP 8.2.0 and maximum PHP 8.4.99 .phpstan.dist.neon6-8
• parameters.scanFiles: Includes mock framework classes for type resolution .phpstan.dist.neon9-11
• parameters.paths: Analyzes only the src directory .phpstan.dist.neon12-13
• parameters.level: Set to maximum strictness (10) .phpstan.dist.neon14

Plugin Configuration (extension.neon): Automatically loaded through Composer's PHPStan extension discovery mechanism. Registers all plugin services including MageCoreConfig, four MageTypeExtension instances, MageInvalidTypeRule, VarienObjectReflectionExtension, and BindThisScopeResolverExtension.

Sources: .github/workflows/phpstan.yml28-29 .phpstan.dist.neon1-14

Pipeline Execution Flow

The pipeline executes four sequential steps for each PHP version in the matrix:

Step 1: Checkout Code (steps[0])

The first step uses actions/checkout@v4 to clone the repository. The YAML structure is:

This action clones the repository at the specific commit SHA that triggered the workflow into the runner's workspace directory .github/workflows/phpstan.yml17-18

Sources: .github/workflows/phpstan.yml17-18

Step 2: Setup PHP (steps[1])

The second step uses shivammathur/setup-php@v2 to install PHP. The YAML structure is:

The with.php-version field uses GitHub Actions' template syntax to reference the current matrix value, which will be '8.3', '8.4', or '8.5' .github/workflows/phpstan.yml20-23

Sources: .github/workflows/phpstan.yml20-23

Step 3: Install Dependencies (steps[2])

The third step executes a shell command to install Composer dependencies:

Flag	Purpose
--prefer-dist	Download distribution archives instead of cloning from source (faster)
--no-progress	Disable progress display for cleaner logs

This command reads composer.json and composer.lock to install:

• phpstan/phpstan (PHPStan core)
• phpstan/phpstan-strict-rules (strict analysis rules)
• phpstan/phpstan-deprecation-rules (deprecation detection)
• Plugin source files from src/
• Mock framework files from mock/

Sources: .github/workflows/phpstan.yml25-26

Step 4: Run PHPStan (steps[3])

The fourth step executes PHPStan analysis:

Command Breakdown:

Component	Description
vendor/bin/phpstan	PHPStan executable (installed by Composer)
analyse	PHPStan subcommand to perform static analysis
--error-format=github	Output format for GitHub Actions annotations

Implicit Configuration: PHPStan automatically discovers .phpstan.dist.neon in the repository root. This file configures:

• parameters.level: 10 - Maximum analysis strictness
• parameters.paths: [src] - Analyze only the src/ directory
• includes: - Load bleeding-edge rules, strict rules, and deprecation rules
• parameters.scanFiles: - Include mock files for type resolution

The workflow does not explicitly specify the configuration file because PHPStan's default behavior is to search for .phpstan.dist.neon or .phpstan.neon in the current directory .github/workflows/phpstan.yml28-29

Sources: .github/workflows/phpstan.yml28-29 .phpstan.dist.neon1-14

Error Reporting Integration

The --error-format=github flag enables native GitHub Actions integration. When PHPStan detects issues:

1. Inline Annotations: Errors appear directly on the changed lines in pull request file views
2. Workflow Summary: A summary of all errors appears in the workflow run output
3. Status Checks: The workflow status (pass/fail) is reported to the pull request
4. Annotations API: GitHub's annotations API displays errors in the "Files changed" tab

This integration provides immediate feedback to developers without requiring them to parse raw PHPStan output.

Sources: .github/workflows/phpstan.yml29

Build Matrix Details

The strategy.matrix.php-version array defines three values that GitHub Actions expands into three parallel job instances. Each instance:

1. Runs in an isolated Ubuntu runner
2. Accesses its matrix value via ${{ matrix.php-version }}
3. Executes all four steps independently
4. Reports success or failure independently

PHP Version Coverage:

Version	Status	Coverage
'8.3'	Stable	Minimum supported version in composer.json (^8.2)
'8.4'	Stable	Latest stable release
'8.5'	Alpha/Beta	Forward compatibility testing

Configuration Alignment: The parameters.phpVersion in .phpstan.dist.neon specifies min: 80200 and max: 80499, indicating the plugin is designed for PHP 8.2.0 through 8.4.99. The matrix includes 8.5 for early compatibility testing .phpstan.dist.neon6-8

Sources: .github/workflows/phpstan.yml12-14 .phpstan.dist.neon6-8

Workflow Execution Context

Execution Environment:

• Operating System: ubuntu-latest (currently Ubuntu 22.04 LTS)
• User: runner
• Working Directory: /home/runner/work/maho-phpstan-plugin/maho-phpstan-plugin
• Network Access: Full internet access for downloading Composer packages

Available GitHub Context:

• github.event_name: Type of event (push or pull_request)
• github.ref: Branch or tag ref that triggered the workflow
• github.sha: Commit SHA being tested
• matrix.php-version: Current PHP version (8.3, 8.4, or 8.5)

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

CI/CD Workflow Characteristics

Performance

Metric	Value
Average duration per job	1-2 minutes
Parallel execution	3 jobs simultaneously
Total pipeline time	1-2 minutes (due to parallelization)

Cost Efficiency

• Uses free GitHub Actions minutes for public repositories
• Matrix strategy maximizes parallelization
• Composer cache could be added for faster dependency installation (not currently implemented)

Reliability

• No external dependencies beyond GitHub-provided actions
• Idempotent: Can be re-run safely
• Deterministic: Same commit produces same results
• Isolated: Each matrix job has independent environment

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

Validation Scope

The CI/CD pipeline validates:

1. PHP Compatibility: Plugin code works across PHP 8.3-8.5
2. Dependency Resolution: All Composer dependencies can be installed
3. Type Safety: PHPStan analysis passes with no errors
4. Extension Loading: Plugin extensions load successfully
5. Mock Definitions: Mock classes provide valid type information

The pipeline does not validate:

• Functional behavior against a real Maho/Magento installation
• Performance characteristics
• Integration with actual PHPStan consumer projects
• Documentation accuracy

For functional testing, developers must use the plugin in a real project context.

Sources: .github/workflows/phpstan.yml28-29