Configuration

This document describes the configuration parameters available in the maho-phpstan-plugin and how to customize PHPStan analysis for your Maho/Magento 1 codebase. For details about the internal plugin configuration system and service registration, see Plugin Configuration System.

Overview

The plugin provides configuration parameters through its extension.neon file, which is automatically loaded when the plugin is installed via Composer. Users can override these parameters in their project's phpstan.neon or phpstan.neon.dist file to customize the plugin's behavior.

The plugin defines three main configurable parameters:

• magentoRootPath (deprecated)
• enforceMagicMethodDocBlock
• useLocalXml

Additionally, it configures a scanDirectories parameter to include mock class definitions.

Sources: extension.neon1-11

Configuration Parameters

Parameter Schema

The plugin defines its parameter schema at the top of the configuration file:

Sources: extension.neon1-8

Available Parameters

Parameter	Type	Default	Description
magentoRootPath	string|null	null	Deprecated. Previously used to specify the Magento installation root path. No longer required.
enforceMagicMethodDocBlock	bool	false	When enabled, requires PHPDoc blocks for magic methods like getName(), setName(), etc. on Varien_Object descendants.
useLocalXml	bool	false	When enabled, includes local.xml configuration files when resolving class aliases. Useful for analyzing projects with local customizations.
scanDirectories	array	['mock/maho', 'mock/maho-phpstan-plugin']	Directories containing stub/mock class definitions for PHPStan analysis.

Sources: extension.neon1-11

Parameter Details

magentoRootPath (Deprecated)

This parameter is deprecated and no longer required. In earlier versions, it was used to specify the path to the Magento installation. The plugin now automatically detects configuration from the analyzed codebase.

Type: string|null
Default: null
Used by: None (deprecated)

Sources: extension.neon2-6

enforceMagicMethodDocBlock

Controls whether PHPDoc blocks are required for magic getter/setter methods on Varien_Object and Maho\DataObject descendants.

When false (default):

• PHPStan accepts calls like $product->getName() without requiring a PHPDoc block
• The VarienObjectReflectionExtension automatically resolves these to the underlying getData() method

When true:

• Requires explicit PHPDoc annotations like @method string getName()
• Provides stricter type checking for magic methods
• Helps document expected data structure in code

Type: bool
Default: false
Used by: VarienObjectReflectionExtension

Sources: extension.neon3-63

useLocalXml

Controls whether local.xml configuration files are included when the MageCoreConfig service resolves class aliases to fully qualified class names.

When false (default):

• Only reads config.xml files from modules
• Suitable for analyzing core Maho/Magento code

When true:

• Includes app/etc/local.xml and module-specific local overrides
• Necessary when analyzing projects with custom class rewrites defined in local configuration
• Useful for projects that override core classes via XML configuration

Type: bool
Default: false
Used by: MageCoreConfig

Sources: extension.neon4-17

scanDirectories

Specifies directories containing stub/mock class definitions that PHPStan should scan. These mocks provide type information for Maho core classes without requiring a full Maho installation.

Type: array<string>
Default: ['mock/maho', 'mock/maho-phpstan-plugin']
Purpose: Provides class definitions for PHPStan analysis

The plugin ships with mock definitions for:

• Mage static class
• Varien_Object / Maho\DataObject
• Laminas framework components (SOAP, XML-RPC, JSON-RPC servers)

For more details, see Mock Framework.

Sources: extension.neon9-11

Configuration Architecture

The following diagram shows how configuration parameters flow through the plugin's service architecture:

Sources: extension.neon1-71

Customizing Configuration

Basic Customization

To customize the plugin's behavior, create or edit your project's phpstan.neon file and override the desired parameters:

Integration with Project Configuration

The plugin configuration integrates seamlessly with standard PHPStan configuration:

Sources: .phpstan.dist.neon1-14

Configuration Use Cases

Use Case 1: Strict Type Checking

For projects that want maximum type safety:

This configuration:

• Requires explicit PHPDoc for all magic methods
• Resolves custom class rewrites from local.xml
• Enforces PHPStan level 9 rules

Use Case 2: Legacy Codebase Analysis

For analyzing legacy codebases with minimal false positives:

This configuration:

• Allows magic methods without documentation
• Only uses standard module configuration
• Uses a lower strictness level

Use Case 3: Custom Module Development

For developing new modules with custom class rewrites:

This configuration:

• Focuses analysis on custom module code
• Resolves rewrites from local.xml
• Requires documentation for magic methods

Plugin Self-Analysis Configuration

The plugin includes its own PHPStan configuration file for self-analysis at .phpstan.dist.neon. This configuration demonstrates best practices:

Sources: .phpstan.dist.neon1-14

Key Configuration Elements

The self-analysis configuration uses:

Setting	Value	Purpose
phpVersion.min	80200 (PHP 8.2)	Minimum supported PHP version
phpVersion.max	80499 (PHP 8.4)	Maximum supported PHP version
scanFiles	Mock definitions	Provides stubs for Maho classes
paths	['src']	Analyzes plugin source code
level	10	Maximum strictness level

This ensures the plugin itself is analyzed with the strictest possible rules.

Sources: .phpstan.dist.neon6-14

Service Configuration

The plugin registers multiple services that consume configuration parameters. The service configuration section defines:

1. mageCoreConfig service - Consumes useLocalXml parameter
2. MageTypeExtension instances (4x) - Use mageCoreConfig service
3. MageInvalidTypeRule - Uses mageCoreConfig service
4. VarienObjectReflectionExtension - Consumes enforceMagicMethodDocBlock parameter
5. BindThisScopeResolverExtension - No configuration parameters

For detailed information about service registration and the plugin's internal architecture, see Plugin Configuration System.

Sources: extension.neon13-71

Summary

The maho-phpstan-plugin provides a simple yet flexible configuration system through three main parameters:

• enforceMagicMethodDocBlock: Controls magic method documentation requirements
• useLocalXml: Enables local configuration file support for class resolution
• scanDirectories: Specifies mock class locations

These parameters can be customized in your project's phpstan.neon file to balance between analysis strictness and compatibility with your codebase's structure and conventions.