Merge pull request #53 from tlueder/SiteDynamicReturnTypeExtension

Make attributes of Site Api configurable

Author: tlueder

README.md

@@ -8,7 +8,7 @@ TYPO3 CMS class reflection extension for PHPStan & framework-specific rules
 
 To use this extension, require it in [Composer](https://getcomposer.org/):
 
-```
+```Shell
 composer require --dev saschaegerer/phpstan-typo3
 ```
 
@@ -19,25 +19,26 @@ If you also install [phpstan/extension-installer](https://github.com/phpstan/ext
 
 If you don't want to use `phpstan/extension-installer`, put this into your phpstan.neon config:
 
-```
+```NEON
 includes:
     - vendor/saschaegerer/phpstan-typo3/extension.neon
 ```
+
 </details>
 
 ### 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
 
-```
+```NEON
 parameters:
     typo3:
         contextApiGetAspectMapping:
             myCustomAspect: FlowdGmbh\MyProject\Context\MyCustomAspect
 ```
 
-```
+```PHP
 // PHPStan will now know that $myCustomAspect is of type FlowdGmbh\MyProject\Context\MyCustomAspect
 $myCustomAspect = GeneralUtility::makeInstance(Context::class)->getAspect('myCustomAspect');
 ```
@@ -47,15 +48,42 @@ $myCustomAspect = GeneralUtility::makeInstance(Context::class)->getAspect('myCus
 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()
 
-```
+```NEON
 parameters:
     typo3:
         requestGetAttributeMapping:
             myAttribute: FlowdGmbh\MyProject\Http\MyAttribute
             myNullableAttribute: FlowdGmbh\MyProject\Http\MyAttribute|null
 ```
 
-```
+```PHP
 // 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
+
+```NEON
+parameters:
+    typo3:
+        siteGetAttributeMapping:
+            myArrayAttribute: array
+            myIntAttribute: int
+            myStringAttribute: string
+```
+
+```PHP
+$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');
+```

extension.neon

@@ -45,6 +45,12 @@ services:
             requestGetAttributeMapping: %typo3.requestGetAttributeMapping%
         tags:
             - phpstan.rules.rule
+    -
+        class: SaschaEgerer\PhpstanTypo3\Rule\SiteAttributeValidationRule
+        arguments:
+            siteGetAttributeMapping: %typo3.siteGetAttributeMapping%
+        tags:
+            - phpstan.rules.rule
     -
         class: SaschaEgerer\PhpstanTypo3\Type\RepositoryQueryDynamicReturnTypeExtension
         tags:
@@ -59,6 +65,12 @@ services:
             requestGetAttributeMapping: %typo3.requestGetAttributeMapping%
         tags:
             - phpstan.broker.dynamicMethodReturnTypeExtension
+    -
+        class: SaschaEgerer\PhpstanTypo3\Type\SiteDynamicReturnTypeExtension
+        arguments:
+            siteGetAttributeMapping: %typo3.siteGetAttributeMapping%
+        tags:
+            - phpstan.broker.dynamicMethodReturnTypeExtension
 parameters:
     bootstrapFiles:
         - phpstan.bootstrap.php
@@ -81,6 +93,14 @@ parameters:
             site: TYPO3\CMS\Core\Site\Entity\Site
             applicationType: TYPO3\CMS\Core\Core\SystemEnvironmentBuilder::REQUESTTYPE_*
             routing: TYPO3\CMS\Core\Routing\SiteRouteResult|TYPO3\CMS\Core\Routing\PageArguments
+        siteGetAttributeMapping:
+            base: string
+            baseVariants: list
+            errorHandling: list
+            languages: list
+            rootPageId: int
+            routeEnhancers: array
+            websiteTitle: string
     stubFiles:
         - stubs/DomainObjectInterface.stub
         - stubs/GeneralUtility.stub
@@ -135,4 +155,5 @@ parametersSchema:
     typo3: structure([
         contextApiGetAspectMapping: arrayOf(string())
         requestGetAttributeMapping: arrayOf(string())
+        siteGetAttributeMapping: arrayOf(string())
     ])

phpstan.neon

@@ -3,6 +3,7 @@ includes:
     - extension.neon
     - tests/Unit/Type/data/context-get-aspect-return-types.neon
     - tests/Unit/Type/data/request-get-attribute-return-types.neon
+    - tests/Unit/Type/data/site-get-attribute-return-types.neon
 
 parameters:
     level: 8

src/Rule/SiteAttributeValidationRule.php

@@ -0,0 +1,69 @@
+<?php declare(strict_types = 1);
+
+namespace SaschaEgerer\PhpstanTypo3\Rule;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\RuleErrorBuilder;
+use TYPO3\CMS\Core\Site\Entity\Site;
+
+/**
+ * @implements \PHPStan\Rules\Rule<\PhpParser\Node\Expr\MethodCall>
+ */
+class SiteAttributeValidationRule implements \PHPStan\Rules\Rule
+{
+
+	/** @var array<string, string> */
+	private $siteGetAttributeMapping;
+
+	/**
+	 * @param array<string, string> $siteGetAttributeMapping
+	 */
+	public function __construct(array $siteGetAttributeMapping)
+	{
+		$this->siteGetAttributeMapping = $siteGetAttributeMapping;
+	}
+
+	public function getNodeType(): string
+	{
+		return Node\Expr\MethodCall::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if (!$node->name instanceof Node\Identifier) {
+			return [];
+		}
+
+		$methodReflection = $scope->getMethodReflection($scope->getType($node->var), $node->name->toString());
+		if ($methodReflection === null || $methodReflection->getName() !== 'getAttribute') {
+			return [];
+		}
+
+		$declaringClass = $methodReflection->getDeclaringClass();
+
+		if (!$declaringClass->implementsInterface(Site::class) && $declaringClass->getName() !== Site::class) {
+			return [];
+		}
+
+		$argument = $node->getArgs()[0] ?? null;
+
+		if (!($argument instanceof Node\Arg) || !($argument->value instanceof Node\Scalar\String_)) {
+			return [];
+		}
+
+		if (isset($this->siteGetAttributeMapping[$argument->value->value])) {
+			return [];
+		}
+
+		$ruleError = RuleErrorBuilder::message(sprintf(
+			'There is no site attribute "%s" configured so we can\'t figure out the exact type to return when calling %s::%s',
+			$argument->value->value,
+			$declaringClass->getDisplayName(),
+			$methodReflection->getName()
+		))->tip('You should add custom site attribute to the typo3.siteGetAttributeMapping setting.')->build();
+
+		return [$ruleError];
+	}
+
+}

src/Type/SiteDynamicReturnTypeExtension.php

@@ -0,0 +1,62 @@
+<?php declare(strict_types = 1);
+
+namespace SaschaEgerer\PhpstanTypo3\Type;
+
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\PhpDoc\TypeStringResolver;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\Type;
+
+class SiteDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+
+	/** @var array<string, string> */
+	private $siteGetAttributeMapping;
+
+	/** @var TypeStringResolver */
+	private $typeStringResolver;
+
+	/**
+	 * @param array<string, string> $siteGetAttributeMapping
+	 */
+	public function __construct(array $siteGetAttributeMapping, TypeStringResolver $typeStringResolver)
+	{
+		$this->siteGetAttributeMapping = $siteGetAttributeMapping;
+		$this->typeStringResolver = $typeStringResolver;
+	}
+
+	public function getClass(): string
+	{
+		return \TYPO3\CMS\Core\Site\Entity\Site::class;
+	}
+
+	public function getTypeFromMethodCall(
+		MethodReflection $methodReflection,
+		MethodCall $methodCall,
+		Scope $scope
+	): Type
+	{
+		$argument = $methodCall->getArgs()[0] ?? null;
+
+		if ($argument === null || !($argument->value instanceof \PhpParser\Node\Scalar\String_)) {
+			return ParametersAcceptorSelector::selectSingle($methodReflection->getVariants())->getReturnType();
+		}
+
+		if (isset($this->siteGetAttributeMapping[$argument->value->value])) {
+			return $this->typeStringResolver->resolve($this->siteGetAttributeMapping[$argument->value->value]);
+		}
+
+		return ParametersAcceptorSelector::selectSingle($methodReflection->getVariants())->getReturnType();
+	}
+
+	public function isMethodSupported(
+		MethodReflection $methodReflection
+	): bool
+	{
+		return $methodReflection->getName() === 'getAttribute';
+	}
+
+}

tests/Unit/Type/SiteGetAttributeDynamicReturnTypeExtensionTest.php

@@ -0,0 +1,42 @@
+<?php declare(strict_types = 1);
+
+namespace SaschaEgerer\PhpstanTypo3\Tests\Unit\Type;
+
+use PHPStan\Testing\TypeInferenceTestCase;
+
+class SiteGetAttributeDynamicReturnTypeExtensionTest extends TypeInferenceTestCase
+{
+
+	/**
+	 * @return iterable<mixed>
+	 */
+	public function dataFileAsserts(): iterable
+	{
+		// path to a file with actual asserts of expected types:
+		yield from $this->gatherAssertTypes(__DIR__ . '/data/site-get-attribute-return-types.php');
+	}
+
+	/**
+	 * @dataProvider dataFileAsserts
+	 * @param string $assertType
+	 * @param string $file
+	 * @param mixed ...$args
+	 */
+	public function testFileAsserts(
+		string $assertType,
+		string $file,
+		...$args
+	): void
+	{
+		$this->assertFileAsserts($assertType, $file, ...$args);
+	}
+
+	public static function getAdditionalConfigFiles(): array
+	{
+		return [
+			__DIR__ . '/../../../extension.neon',
+			__DIR__ . '/data/site-get-attribute-return-types.neon',
+		];
+	}
+
+}

tests/Unit/Type/data/site-get-attribute-return-types.neon

@@ -0,0 +1,5 @@
+parameters:
+    typo3:
+        siteGetAttributeMapping:
+            myCustomIntAttribute: int
+            myCustomStringAttribute: string

tests/Unit/Type/data/site-get-attribute-return-types.php

@@ -0,0 +1,26 @@
+<?php declare(strict_types = 1);
+
+namespace SiteGetAttributeReturnTypes;
+
+use TYPO3\CMS\Core\Site\Entity\Site;
+
+use function PHPStan\Testing\assertType;
+
+// phpcs:ignore Squiz.Classes.ClassFileName.NoMatch
+class MySite
+{
+
+	public function getAttributeTests(Site $site): void
+	{
+		assertType('string', $site->getAttribute('base'));
+		assertType('array<int, mixed>', $site->getAttribute('baseVariants'));
+		assertType('array<int, mixed>', $site->getAttribute('errorHandling'));
+		assertType('array<int, mixed>', $site->getAttribute('languages'));
+		assertType('int', $site->getAttribute('rootPageId'));
+		assertType('array', $site->getAttribute('routeEnhancers'));
+		assertType('string', $site->getAttribute('websiteTitle'));
+		assertType('int', $site->getAttribute('myCustomIntAttribute'));
+		assertType('string', $site->getAttribute('myCustomStringAttribute'));
+	}
+
+}