 |
VOOZH | about |
|
VOOZH | about |
This guide provides a practical introduction to using the maho-phpstan-plugin in your Maho project. It demonstrates the plugin's key features through concrete examples and shows you how to start analyzing your codebase immediately after installation.
Prerequisites: This guide assumes you have already completed Installation and reviewed Configuration. For detailed information about the plugin's architecture, see Architecture. For specifics on each feature, consult Type Inference System and Reflection Extensions.
After installing the plugin, verify your setup by checking that PHPStan can discover the plugin's configuration:
The plugin is automatically loaded through composer.json which declares the plugin as type phpstan-extension and points to extension.neon1-71 via the extra.phpstan.includes section.
Sources: extension.neon1-71
Create a minimal phpstan.neon file in your Maho project root:
Run the analysis:
PHPStan will now analyze your Maho codebase with the plugin's enhancements active. The plugin automatically extends PHPStan's capabilities without requiring explicit configuration.
Diagram: Plugin Activation Flow
Sources: extension.neon1-71 composer.json
The plugin resolves return types for Magento factory methods, which PHPStan normally cannot infer.
Consider this typical Maho code:
The plugin achieves this through MageTypeExtension1-104 registered in extension.neon19-47 which resolves the string alias 'catalog/product' to the class name Mage_Catalog_Model_Product using MageCoreConfig
The plugin provides type inference for four categories of factory methods:
| Factory Method | Registered For | Extension Point | Line Reference |
|---|---|---|---|
Mage::getModel() | Mage static class | dynamicStaticMethodReturnTypeExtension | extension.neon20-26 |
Mage::getSingleton() | Mage static class | dynamicStaticMethodReturnTypeExtension | extension.neon20-26 |
Mage::getResourceModel() | Mage static class | dynamicStaticMethodReturnTypeExtension | extension.neon20-26 |
Mage::helper() | Mage static class | dynamicStaticMethodReturnTypeExtension | extension.neon20-26 |
$this->helper() | Mage_Core_Block_Abstract instances | dynamicMethodReturnTypeExtension | extension.neon28-33 |
$this->getModel() / $this->getSingleton() | Mage_Core_Model_Abstract instances | dynamicMethodReturnTypeExtension | extension.neon35-40 |
$layout->createBlock() | Mage_Core_Model_Layout instances | dynamicMethodReturnTypeExtension | extension.neon42-47 |
Sources: extension.neon19-47
The plugin understands Varien_Object magic methods like getData(), setData(), hasData(), and their dynamic counterparts.
This is handled by VarienObjectReflectionExtension registered in extension.neon58-63 as a methodsClassReflectionExtension. The extension intercepts method calls matching the pattern get*, set*, has*, and uns* on classes extending Varien_Object or Maho\DataObject.
Diagram: Magic Method Resolution
Sources: extension.neon58-63
The plugin handles .phtml template files where $this refers to a block instance and needs access to protected methods.
In a typical .phtml template:
The BindThisScopeResolverExtension registered in extension.neon66-70 transforms the @var annotation into a special bind-this-scope<Type> generic type that wraps the block's methods and properties as public, allowing template code to access them.
Sources: extension.neon66-70
The plugin validates that factory method aliases resolve to existing classes, catching configuration errors early.
This validation is performed by MageInvalidTypeRule registered in extension.neon50-55 with the phpstan.rules.rule tag. The rule checks every factory method call and reports an error if the alias cannot be resolved to an existing class.
Diagram: Error Detection Flow
Sources: extension.neon50-55
When you run PHPStan with the plugin, you'll see improved type inference in the analysis:
------ ------------------------------------------------
Line app/code/local/Company/Module/Model/Observer.php
------ ------------------------------------------------
42 Cannot call method load() on mixed.
43 Cannot call method getData() on mixed.
44 Cannot call method setData() on mixed.
------ ------------------------------------------------
------ ------------------------------------------------
Line app/code/local/Company/Module/Model/Observer.php
------ ------------------------------------------------
No errors found!
------ ------------------------------------------------
Or if there are actual errors:
------ ------------------------------------------------
Line app/code/local/Company/Module/Model/Observer.php
------ ------------------------------------------------
42 Parameter #1 $id of method Mage_Catalog_Model_Product::load()
expects int, string given.
------ ------------------------------------------------
The plugin eliminates false positives from PHPStan's inability to understand Magento patterns, allowing PHPStan to focus on real type errors.
The plugin provides two optional parameters that can be set in your phpstan.neon:
These parameters are defined in extension.neon1-8 and injected into the respective service classes:
useLocalXml is passed to MageCoreConfig in extension.neon14-17enforceMagicMethodDocBlock is passed to VarienObjectReflectionExtension in extension.neon58-63For most projects, the default values are appropriate.
Sources: extension.neon1-8 extension.neon14-17 extension.neon58-63
This table maps the features demonstrated above to their implementing components:
Diagram: Feature to Component Mapping
Sources: extension.neon14-70
Now that you've seen the plugin in action, you can:
The plugin requires no additional configuration in most cases - it automatically enhances PHPStan's understanding of Maho codebases as soon as it's installed.
Sources: extension.neon1-71 .phpstan.dist.neon1-15
Refresh this wiki