Installation

This page documents the installation process for maho-phpstan-plugin, including system requirements, dependency structure, autoloading configuration, and PHPStan's automatic extension discovery mechanism. For configuration options, see section 2.2.

Overview

The plugin is a Composer package with type: phpstan-extension composer.json4 PHPStan automatically discovers and loads the plugin via the extra.phpstan.includes mechanism defined in composer.json24-30

Sources: composer.json1-31

System Requirements

Requirement	Version Constraint	Defined In
PHP	>= 8.2	composer.json7
PHPStan	^2.1	composer.json8

The plugin requires PHP 8.2+ composer.json7 while PHPStan itself supports PHP 7.4+ composer.lock19 PHPStan is listed in require composer.json6-9 rather than require-dev, ensuring it is available when the plugin is installed as a dependency.

Sources: composer.json6-9 composer.lock18-21

Installation Steps

Standard Installation

This installs the package to vendor/mahocommerce/maho-phpstan-plugin/ and registers:

• PSR-4 autoloading: Maho\PHPStanPlugin\ → src/ composer.json14-18
• Classmap autoloading (dev): mock/maho-phpstan-plugin/ composer.json20-22
• PHPStan extension discovery via extra.phpstan.includes composer.json24-30

Sources: composer.json1-31

Package Configuration

Dependency Structure

The type: phpstan-extension declaration composer.json4 enables automatic discovery. PHPStan is in require composer.json8 not require-dev, ensuring availability when the plugin is installed in end-user projects. The require-dev dependencies composer.json10-13 are only used for analyzing the plugin itself.

Sources: composer.json2-13

Autoloading Configuration

Autoloading Mechanism Mapping

Namespace to File Mapping

Namespace/Class	File Path	Configuration
Maho\PHPStanPlugin\Type\MageTypeExtension	src/Type/MageTypeExtension.php	composer.json14-18
Maho\PHPStanPlugin\Config\MageCoreConfig	src/Config/MageCoreConfig.php	composer.json14-18
Mage	mock/maho-phpstan-plugin/Mage.php	composer.json19-23
Varien_Object	mock/maho-phpstan-plugin/Varien/Object.php	composer.json19-23

The classmap autoloading composer.json19-23 provides mock framework classes used by MageCoreConfig for type resolution. See section 6.1 for details on mock classes.

Sources: composer.json14-23

Automatic Extension Discovery

PHPStan Extension Discovery Flow

Extension Discovery Configuration

composer.json24-30 defines the discovery mechanism:

Key	Value	Effect
type	phpstan-extension composer.json4	Marks package as PHPStan extension
extra.phpstan.includes	["extension.neon"] composer.json26-28	Specifies configuration file(s) to load

PHPStan automatically loads extension.neon without requiring manual inclusion in user's phpstan.neon files. The extension.neon file registers all plugin services (see section 3.1).

Sources: composer.json4 composer.json24-30

Dependency Locking

composer.lock1-171 locks dependency versions for reproducible builds:

Package	Locked Version	Location
phpstan/phpstan	2.1.38	composer.lock10-61
phpstan/phpstan-strict-rules	2.0.8	composer.lock112-158
phpstan/phpstan-deprecation-rules	2.0.3	composer.lock64-110

The lock file contains exact versions, distribution URLs, checksums, and the complete dependency tree. End users installing the plugin receive versions matching their own PHPStan constraints, not the versions locked in the plugin's composer.lock.

Sources: composer.lock1-171

Installation Directory Structure

Installed Directory Layout

Key Files and Directories

Path	Purpose	Autoload Method
extension.neon	PHPStan service registration	extra.phpstan.includes
src/Type/MageTypeExtension.php	Dynamic return type inference	PSR-4 composer.json15-17
src/Config/MageCoreConfig.php	Magento alias resolution	PSR-4 composer.json15-17
mock/maho-phpstan-plugin/Mage.php	Framework mock for type resolution	Classmap composer.json20-22

Sources: composer.json14-23

Verification

Verify Composer Installation

Expected output includes version, license, dependencies, and autoload configuration.

Verify PHPStan Discovery

Should show extension.neon loaded from vendor/mahocommerce/maho-phpstan-plugin/.

Verify Autoloading

Should output bool(true).

Sources: composer.json14-18

Troubleshooting

Plugin Not Discovered

If PHPStan does not automatically load the plugin:

1. Verify package type: Ensure composer.json has "type": "phpstan-extension" composer.json4
2. Check extra configuration: Confirm extra.phpstan.includes exists composer.json24-30
3. Reinstall dependencies: Run composer install --no-cache to force fresh installation
4. Update PHPStan: Ensure PHPStan version supports automatic extension discovery (^2.0+)

Autoloading Issues

If classes cannot be autoloaded:

1. Regenerate autoload files: Run composer dump-autoload
2. Verify namespace: Check that PSR-4 mapping in composer.json14-18 is correct
3. Check file permissions: Ensure vendor/ directory is readable

Version Conflicts

If Composer reports version conflicts:

1. Check PHP version: Ensure PHP >= 8.2 is installed composer.json7
2. Update dependencies: Run composer update to resolve conflicts
3. Check PHPStan version: Ensure PHPStan ^2.0 is available

Sources: composer.json1-31