Adding .phpstorm.meta.php support to PHPStan

This code provides two extensions for PHPStan that can help it understand PHPStorm’s .phpstorm.meta.php metadata.

I needed this when I was migrating a Magento 1.x project to PHP 8.1 (don’t ask), since it didn’t exist, I figured I should share what I ended up with.

Installation

There is no published Packagist package for this repo. To install it, add the repository to your composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/DCoderLT/phpstan-phpstorm-meta"
    }
  ]
}

And require it via composer:

composer require --dev dcoderlt/phpstan-phpstorm-meta=dev-main

Configuration

Use the configuration from examples/phpstan.neon.example as a starting point:

• define the paths to your .phpstorm.meta.php files (I load them from a separate .php config file using __DIR__, to avoid relative path resolution)
• define the phpstan extension services that should leverage the metadata from those files

PHPStan extension services

Because PHPStan’s extension API does not allow one extension to resolve return types for multiple classes, you need to register a separate service for each class that has overrides in the meta files. You also need to specify which method names you want these services to resolve.

If the metadata describes a static method, you need to register a service based on PhpStormMetaStan\Service\StaticMethodReturnTypeResolver that is tagged with phpstan.broker.dynamicStaticMethodReturnTypeExtension:

services:
    -
        class: PhpStormMetaStan\Service\StaticMethodReturnTypeResolver
        tags:
            - phpstan.broker.dynamicStaticMethodReturnTypeExtension
        arguments:
            className: Mage
            methodNames:
                - helper
                - getModel
                - getResourceModel
                - getResourceHelper
                - getResourceSingleton
                - getBlockSingleton
                - getSingleton

If the metadata describes a non-static method, you need to register a service based on PhpStormMetaStan\Service\NonStaticMethodReturnTypeResolver that is tagged with phpstan.broker.dynamicMethodReturnTypeExtension:

services:
    -
        class: PhpStormMetaStan\Service\NonStaticMethodReturnTypeResolver
        tags:
            - phpstan.broker.dynamicMethodReturnTypeExtension
        arguments:
            className: Mage_Core_Block_Abstract
            methodNames:
                - helper

Usage

The meta files will be parsed the first time PHPStan asks these extensions to resolve a type. For larger meta files, this can take a bit of time. For my Magento 1.x project where phpstorm meta files are autogenerated and contain about 90k lines, the parsing process takes about 10 seconds.

TODO

• This only parses the most common metadata type - when a method’s return type depends on a string passed as a method argument. There are other metadata types supported by PHPStorm that are not supported here.
• Caching the parsed metadata would probably help performance a lot :)
• Each metadata file has to be listed in the config explicitly - it could be nice to add Symfony’s Finder to support directories.