VOOZH about

URL: https://deepwiki.com/MahoCommerce/maho-phpstan-plugin/7-development-and-contributing

⇱ Development and Contributing | MahoCommerce/maho-phpstan-plugin | DeepWiki

Loading...
Loading...
Menu

Development and Contributing

This page provides an overview for developers who wish to contribute to the maho-phpstan-plugin project itself. It covers the development environment, workflow, and quality standards required for contributions.

For specific setup instructions, see Development Setup. For details on the automated testing pipeline, see CI/CD Pipeline. For information about quality assurance processes, see Testing and Quality Assurance.

Purpose and Scope

This page addresses contributors working on the plugin's source code, not end users integrating the plugin into their Maho projects. The plugin is self-analyzing, meaning it uses PHPStan to validate its own code quality. This creates specific requirements for the development environment and contribution process.

The plugin maintains maximum strictness (PHPStan level 10) with additional strict rules and deprecation rules enabled. All contributions must pass these checks across multiple PHP versions (8.3, 8.4, 8.5) before being merged.

Sources: composer.json1-31 .phpstan.dist.neon1-15 .github/workflows/phpstan.yml1-29

Repository Structure

The following diagram maps the conceptual organization of the repository to actual file paths and directory structures:



Repository Structure


The repository is organized into four primary areas:
































Directory/FilePurposeKey Files
src/Plugin implementation8 PHP classes implementing PHPStan extensions
mock/maho-phpstan-plugin/Framework mocksMage.php, DataObject.php, Laminas components
Configuration filesPlugin and analysis configextension.neon, .phpstan.dist.neon, composer.json
.github/workflows/CI automationphpstan.yml


The src/ directory contains all plugin logic, organized by functionality rather than by PHPStan extension type. The mock/ directory provides stub implementations of Maho framework classes necessary for type resolution, defined via autoload-dev in composer.json19-23


Sources: composer.json1-31 .phpstan.dist.neon1-15 .github/workflows/phpstan.yml1-29




Development Workflow


The development workflow involves local development and automated CI validation:




Workflow Steps


    

  1. Clone and Install - Clone the repository and run composer install to fetch dependencies defined in composer.json6-13
    2. 

  2. Local Development - Edit source files in src/ directory
    3. 

  3. Local Validation - Run vendor/bin/phpstan analyse which uses .phpstan.dist.neon1-15 configuration
    4. 

  4. Commit and Push - Push changes trigger the GitHub Actions workflow defined in .github/workflows/phpstan.yml1-29
    5. 

  5. CI Validation - Workflow tests across PHP 8.3, 8.4, 8.5 using matrix strategy .github/workflows/phpstan.yml12-14
    6. 

  6. Publication - Successful merge to main triggers Packagist update via composer configuration composer.json24-30
    7. 



Sources: composer.json1-31 .phpstan.dist.neon1-15 .github/workflows/phpstan.yml1-29




Package Configuration


The composer.json file serves dual purposes in development:




Key Configuration Elements










































ElementValuePurpose
typephpstan-extensionEnables PHPStan's automatic discovery mechanism composer.json4
require.php>= 8.2Minimum PHP version for plugin composer.json7
require.phpstan/phpstan^2.1PHPStan version compatibility composer.json8
autoload.psr-4Maho\PHPStanPlugin\: src/Maps namespace to source directory composer.json14-17
autoload-dev.classmapmock/maho-phpstan-plugin/Loads mock framework classes composer.json19-23
extra.phpstan.includesextension.neonEntry point for plugin configuration composer.json24-30


The require-dev dependencies composer.json10-13 add additional strictness rules that the plugin must satisfy, ensuring high code quality standards.


Sources: composer.json1-31




Self-Analysis Configuration


The plugin analyzes itself using .phpstan.dist.neon:




Analysis Configuration Breakdown


The configuration file .phpstan.dist.neon1-15 enforces maximum strictness:


    

  • 

    Includes .phpstan.dist.neon1-4 - Loads three rule sets:
    

      

    • bleedingEdge.neon - Enables experimental features and future compatibility checks
      • 

    • strict-rules.neon - Adds strict type checking rules from phpstan-strict-rules package
      • 

    • deprecation-rules.neon - Detects usage of deprecated features from phpstan-deprecation-rules package
      • 

    

    • 

  • 

    PHP Version .phpstan.dist.neon6-8 - Constrains analysis to PHP 8.2.0-8.4.99 range, ensuring compatibility
    

    • 

  • 

    Scan Files .phpstan.dist.neon9-11 - Loads mock framework files Mage.php and DataObject.php so type resolution logic can reference them during analysis
    

    • 

  • 

    Paths .phpstan.dist.neon12-13 - Analyzes only the src/ directory, not tests or mocks
    

    • 

  • 

    Level .phpstan.dist.neon14 - Sets level 10 (maximum) for strictest possible analysis
    

    • 



This configuration creates a bootstrap scenario where the plugin must successfully analyze itself to be valid. The mock files must be scanned .phpstan.dist.neon9-11 because classes like MageCoreConfig reference Mage class methods during type resolution.


Sources: .phpstan.dist.neon1-15




Contribution Guidelines


Prerequisites


    

  • PHP 8.2 or higher installed locally
    • 

  • Composer installed
    • 

  • Git installed
    • 

  • Familiarity with PHPStan extension development
    • 



Local Development Process


    

  1. Fork and clone the repository
    2. 

  2. Run composer install to install dependencies from composer.json6-13
    3. 

  3. Make changes to files in src/ directory
    4. 

  4. Run vendor/bin/phpstan analyse to verify changes
    5. 

  5. Ensure all errors are resolved before committing
    6. 

  6. Submit pull request with clear description
    7. 



Code Quality Requirements


All contributions must:


    

  • Pass PHPStan level 10 analysis
    • 

  • Pass strict rules from phpstan-strict-rules package
    • 

  • Pass deprecation rules from phpstan-deprecation-rules package
    • 

  • Support PHP 8.3, 8.4, and 8.5 as validated by CI matrix .github/workflows/phpstan.yml12-14
    • 

  • Follow PSR-4 autoloading convention in Maho\PHPStanPlugin namespace composer.json14-17
    • 



CI Validation


Every push and pull request triggers the GitHub Actions workflow .github/workflows/phpstan.yml1-29 The workflow:


    

  1. Checks out code using actions/checkout@v4 .github/workflows/phpstan.yml17-18
    2. 

  2. Sets up PHP using shivammathur/setup-php@v2 .github/workflows/phpstan.yml20-23
    3. 

  3. Installs dependencies with composer install .github/workflows/phpstan.yml25-26
    4. 

  4. Runs analysis with vendor/bin/phpstan analyse --error-format=github .github/workflows/phpstan.yml28-29
    5. 



The --error-format=github flag formats errors as GitHub annotations, making them visible directly in the pull request interface.


Sources: composer.json1-31 .phpstan.dist.neon1-15 .github/workflows/phpstan.yml1-29




Testing Strategy


The plugin uses a self-validation approach rather than traditional unit tests:































Testing AspectImplementation
Type SafetyPHPStan level 10 on own source code
Strict Rulesphpstan-strict-rules package enforces strict comparisons, type declarations
Deprecationsphpstan-deprecation-rules package prevents deprecated API usage
PHP CompatibilityCI matrix tests PHP 8.3, 8.4, 8.5
Mock CorrectnessMock files must load during self-analysis for type resolution


The plugin's functionality is validated by:


    

  1. Self-Analysis - If the plugin can successfully analyze itself, its type resolution logic works
    2. 

  2. Strict Rules - Additional rules catch common mistakes beyond basic type errors
    3. 

  3. Multi-Version Testing - CI ensures compatibility across PHP versions .github/workflows/phpstan.yml12-14
    4. 



The mock files .phpstan.dist.neon9-11 serve as both implementation stubs and test fixtures - if they're incorrectly structured, self-analysis fails.


For detailed information about the testing approach, see Testing and Quality Assurance.


Sources: .phpstan.dist.neon1-15 .github/workflows/phpstan.yml1-29




Release Process


The package is published to Packagist automatically:


    

  1. Changes merged to main branch
    2. 

  2. Packagist webhook detects repository update
    3. 

  3. Package metadata from composer.json1-5 updates on Packagist
    4. 

  4. New version available via composer require mahocommerce/maho-phpstan-plugin
    5. 



The type: phpstan-extension declaration composer.json4 and extra.phpstan.includes configuration composer.json24-30 enable automatic plugin discovery in end-user projects.


Version Constraints


The plugin declares:



End users installing the plugin will have these constraints enforced by Composer.


Sources: composer.json1-31