/phpstan-typo3

TYPO3 CMS class reflection extension for PHPStan & framework-specific rules

Primary LanguagePHPMIT LicenseMIT

PHPStan TYPO3 extensions and rules

TYPO3 CMS class reflection extension for PHPStan & framework-specific rules.

Build

This extension provides the following features (!!! not an exhaustive list !!!):

Dynamic Return Type Extensions

  • Provides correct return type for \TYPO3\CMS\Core\Context\Context->getAspect().
  • Provides correct return type for \TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance().
  • Provides correct return type for \TYPO3\CMS\Extbase\Object\ObjectManagerInterface->get().
  • Provides correct return type for \TYPO3\CMS\Extbase\Object\ObjectManager->get().
  • Provides correct return type for \TYPO3\CMS\Extbase\Property\PropertyMapper->convert().
  • Provides correct return type for \TYPO3\CMS\Core\Utility\MathUtility methods like isIntegerInRange.
  • Provides correct return type for \TYPO3\CMS\Extbase\Persistence\Generic\Query->execute().
  • Provides correct return type for \TYPO3\CMS\Extbase\Persistence\QueryInterface->execute().
  • Provides correct return type for \TYPO3\CMS\Core\Site\Entity\Site->getAttribute().
  • Provides correct return type for \Psr\Http\Message\ServerRequestInterface->getAttribute().
  • Uses under the hood bnf/phpstan-psr-container

All these dynamic return type extensions are necessary to teach PHPStan what type will be returned by the specific method call.

Show me a practical use case. For example PHPStan cannot know innately what type will be returned if you call `\TYPO3\CMS\Core\Utility\MathUtility->forceIntegerInRange(1000, 1, 10)`. It will be an int<10>. With the help of this library PHPStan also knows what´s going up.

Imagine the following situation in your code:

use TYPO3\CMS\Core\Utility\MathUtility;

$integer = MathUtility::forceIntegerInRange(100, 1, 10);

if($integer > 10) {
    throw new \UnexpectedValueException('The integer is too big')
}

PHPStan will tell you that the if condition is superfluous, because the variable $integer will never be higher than 10. Right?

Framework specific rules

  • Provides rule for \TYPO3\CMS\Core\Context\Context->getAspect().
  • Provides rule for \Psr\Http\Message\ServerRequestInterface->getAttribute().
  • Provides rule for \TYPO3\CMS\Core\Site\Entity\Site->getAttribute().
  • Provides rule for \TYPO3\CMS\Extbase\Validation\ValidatorResolver->createValidator().
Show me a practical use case.

For example PHPStan cannot know innately that calling ValidatorResolver->createValidator(RegularExpressionValidator::class) is invalid, because we miss to pass the required option regularExpression. With the help of this library PHPStan now complaints that we have missed to pass the required option. So go ahead and find bugs in your code without running it.

Installation & Configuration

To use this extension, require it in Composer:

composer require --dev saschaegerer/phpstan-typo3

If you also install phpstan/extension-installer then you're all set!

Manual installation

If you don't want to use phpstan/extension-installer, put this into your phpstan.neon config:

includes:
    - vendor/saschaegerer/phpstan-typo3/extension.neon

Custom Context API Aspects

If you use custom aspects for the TYPO3 Context API you can add a mapping so PHPStan knows what type of aspect class is returned by the context API

parameters:
    typo3:
        contextApiGetAspectMapping:
            myCustomAspect: FlowdGmbh\MyProject\Context\MyCustomAspect
// PHPStan will now know that $myCustomAspect is of type FlowdGmbh\MyProject\Context\MyCustomAspect
$myCustomAspect = GeneralUtility::makeInstance(Context::class)->getAspect('myCustomAspect');

Custom Request Attribute

If you use custom PSR-7 request attribute you can add a mapping so PHPStan knows what type of class is returned by Request::getAttribute()

parameters:
    typo3:
        requestGetAttributeMapping:
            myAttribute: FlowdGmbh\MyProject\Http\MyAttribute
            myNullableAttribute: FlowdGmbh\MyProject\Http\MyAttribute|null
// PHPStan will now know that $myAttribute is of type FlowdGmbh\MyProject\Http\MyAttribute
$myAttribute = $request->getAttribute('myAttribute');

Custom Site Attribute

If you use custom attributes for the TYPO3 Site API you can add a mapping so PHPStan knows what type is returned by the site API

parameters:
    typo3:
        siteGetAttributeMapping:
            myArrayAttribute: array
            myIntAttribute: int
            myStringAttribute: string
$site = $this->request->getAttribute('site');

// PHPStan will now know that $myArrayAttribute is of type array<mixed, mixed>
$myArrayAttribute = $site->getAttribute('myArrayAttribute');

// PHPStan will now know that $myIntAttribute is of type int
$myIntAttribute = $site->getAttribute('myIntAttribute');

// PHPStan will now know that $myStringAttribute is of type string
$myStringAttribute = $site->getAttribute('myStringAttribute');