diff --git a/README.md b/README.md index aca020a..18cfe81 100644 --- a/README.md +++ b/README.md @@ -397,6 +397,80 @@ final class SearchComponent
+### LiveResponseMustBeReturnedByLiveActionRule + +Enforces that a `LiveResponse` (introduced in `symfony/ux-live-component` 3.5) is only returned by a `#[LiveAction]` or a `#[LiveListener]` method: +- The default action (`__invoke()`, or the method set in `#[AsLiveComponent(defaultAction: '...')]`) must not return a `LiveResponse`, since it runs on every re-render and Symfony UX throws a `LogicException` at runtime +- A public method returning a `LiveResponse` must have the `#[LiveAction]` or `#[LiveListener]` attribute, otherwise the browser cannot call it as an action + +Private and protected methods are ignored, so they can build a `LiveResponse` for an action. + +```yaml +rules: + - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LiveResponseMustBeReturnedByLiveActionRule +``` + +```php +// src/Twig/Components/Notification.php +namespace App\Twig\Components; + +use Symfony\UX\LiveComponent\Attribute\AsLiveComponent; +use Symfony\UX\LiveComponent\LiveResponse; + +#[AsLiveComponent] +final class Notification +{ + // Error: the default action must not return a LiveResponse + public function __invoke(): LiveResponse + { + return LiveResponse::remove(); + } + + // Error: the method is not a LiveAction + public function export(): LiveResponse + { + return LiveResponse::downloadUrl('/notifications/export.csv'); + } +} +``` + +:x: + +
+ +```php +// src/Twig/Components/Notification.php +namespace App\Twig\Components; + +use Symfony\UX\LiveComponent\Attribute\AsLiveComponent; +use Symfony\UX\LiveComponent\Attribute\LiveAction; +use Symfony\UX\LiveComponent\Attribute\LiveListener; +use Symfony\UX\LiveComponent\DefaultActionTrait; +use Symfony\UX\LiveComponent\LiveResponse; + +#[AsLiveComponent] +final class Notification +{ + use DefaultActionTrait; + + #[LiveAction] + public function export(): LiveResponse + { + return LiveResponse::downloadUrl('/notifications/export.csv'); + } + + #[LiveListener('notification:read')] + public function dismiss(): LiveResponse + { + return LiveResponse::remove(); + } +} +``` + +:+1: + +
+ ## TwigComponent Rules > [!NOTE] diff --git a/rules.neon b/rules.neon index c7f8ee3..b897905 100644 --- a/rules.neon +++ b/rules.neon @@ -3,6 +3,7 @@ rules: - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LiveListenerMethodsVisibilityRule - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LivePropHydrationMethodsRule - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LivePropModifierMethodRule + - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LiveResponseMustBeReturnedByLiveActionRule - Kocal\PHPStanSymfonyUX\Rules\TwigComponent\ClassMustBeFinalRule - Kocal\PHPStanSymfonyUX\Rules\TwigComponent\ClassNameMustNotEndWithComponentRule - Kocal\PHPStanSymfonyUX\Rules\TwigComponent\ExposePublicPropsMustBeFalseRule diff --git a/src/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule.php b/src/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule.php new file mode 100644 index 0000000..f5f5fb9 --- /dev/null +++ b/src/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule.php @@ -0,0 +1,101 @@ + + */ +final class LiveResponseMustBeReturnedByLiveActionRule implements Rule +{ + public function __construct( + private ReflectionProvider $reflectionProvider, + ) { + } + + public function getNodeType(): string + { + return Class_::class; + } + + public function processNode(Node $node, Scope $scope): array + { + if (! $attribute = AttributeFinder::findAttribute($node, AsLiveComponent::class)) { + return []; + } + + if ($node->namespacedName === null) { + return []; + } + + $errors = []; + $reflClass = $this->reflectionProvider->getClass($node->namespacedName->toString()); + $defaultAction = $this->getDefaultAction($attribute); + + foreach ($node->getMethods() as $method) { + $methodName = $method->name->toString(); + $returnType = TypeCombinator::removeNull($reflClass->getNativeMethod($methodName)->getOnlyVariant()->getReturnType()); + + if (! in_array(LiveResponse::class, $returnType->getObjectClassNames(), true)) { + continue; + } + + if ($defaultAction !== null && strcasecmp($methodName, $defaultAction) === 0) { + $errors[] = RuleErrorBuilder::message( + sprintf('Default action "%s()" must not return a LiveResponse.', $methodName) + ) + ->identifier('symfonyUX.liveComponent.liveResponseInDefaultAction') + ->line($method->getLine()) + ->tip('The default action runs on every re-render, return the LiveResponse from a #[LiveAction] or #[LiveListener] method instead.') + ->build(); + + continue; + } + + if ($method->isPublic() && ! AttributeFinder::findAnyAttribute($method, [LiveAction::class, LiveListener::class])) { + $errors[] = RuleErrorBuilder::message( + sprintf('Method "%s()" returning a LiveResponse must be a LiveAction or a LiveListener.', $methodName) + ) + ->identifier('symfonyUX.liveComponent.liveResponseMustBeReturnedByLiveAction') + ->line($method->getLine()) + ->tip(sprintf('Add the #[LiveAction] attribute to "%s()", or make it private if it only builds the LiveResponse for another action.', $methodName)) + ->build(); + } + } + + return $errors; + } + + /** + * Returns null when the "defaultAction" argument cannot be resolved statically. + */ + private function getDefaultAction(Node\Attribute $attribute): ?string + { + foreach ($attribute->args as $index => $arg) { + $isDefaultActionArg = $arg->name === null + ? $index === 2 + : $arg->name->toString() === 'defaultAction'; + + if ($isDefaultActionArg) { + return $arg->value instanceof String_ ? trim($arg->value->value, '()') : null; + } + } + + return '__invoke'; + } +} diff --git a/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidCustomDefaultAction.php b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidCustomDefaultAction.php new file mode 100644 index 0000000..25ff4e1 --- /dev/null +++ b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidCustomDefaultAction.php @@ -0,0 +1,19 @@ +dismissed ? LiveResponse::remove() : null; + } +} diff --git a/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidDefaultAction.php b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidDefaultAction.php new file mode 100644 index 0000000..b272138 --- /dev/null +++ b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/InvalidDefaultAction.php @@ -0,0 +1,17 @@ +dismissed ? LiveResponse::remove() : null; + } +} diff --git a/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/NotAComponent.php b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/NotAComponent.php new file mode 100644 index 0000000..df08bb1 --- /dev/null +++ b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/Fixture/NotAComponent.php @@ -0,0 +1,15 @@ +download(); + } + + #[LiveListener('notification.read')] + public function dismiss(): LiveResponse + { + return LiveResponse::remove(); + } + + private function download(): LiveResponse + { + return LiveResponse::downloadUrl('/export.csv'); + } +} diff --git a/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/LiveResponseMustBeReturnedByLiveActionRuleTest.php b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/LiveResponseMustBeReturnedByLiveActionRuleTest.php new file mode 100644 index 0000000..69aafc9 --- /dev/null +++ b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/LiveResponseMustBeReturnedByLiveActionRuleTest.php @@ -0,0 +1,84 @@ + + */ +final class LiveResponseMustBeReturnedByLiveActionRuleTest extends RuleTestCase +{ + public function testDefaultActionReturningLiveResponse(): void + { + $this->analyse( + [__DIR__ . '/Fixture/InvalidDefaultAction.php'], + [ + [ + 'Default action "__invoke()" must not return a LiveResponse.', + 13, + 'The default action runs on every re-render, return the LiveResponse from a #[LiveAction] or #[LiveListener] method instead.', + ], + ] + ); + } + + public function testCustomDefaultActionReturningLiveResponse(): void + { + $this->analyse( + [__DIR__ . '/Fixture/InvalidCustomDefaultAction.php'], + [ + [ + 'Default action "refresh()" must not return a LiveResponse.', + 15, + 'The default action runs on every re-render, return the LiveResponse from a #[LiveAction] or #[LiveListener] method instead.', + ], + ] + ); + + $this->analyse( + [__DIR__ . '/Fixture/InvalidPositionalDefaultAction.php'], + [ + [ + 'Default action "refresh()" must not return a LiveResponse.', + 15, + 'The default action runs on every re-render, return the LiveResponse from a #[LiveAction] or #[LiveListener] method instead.', + ], + ] + ); + } + + public function testPublicMethodReturningLiveResponseWithoutLiveAction(): void + { + $this->analyse( + [__DIR__ . '/Fixture/InvalidNotALiveAction.php'], + [ + [ + 'Method "export()" returning a LiveResponse must be a LiveAction or a LiveListener.', + 13, + 'Add the #[LiveAction] attribute to "export()", or make it private if it only builds the LiveResponse for another action.', + ], + ] + ); + } + + public function testNoViolations(): void + { + $this->analyse([__DIR__ . '/Fixture/NotAComponent.php'], []); + $this->analyse([__DIR__ . '/Fixture/ValidLiveComponent.php'], []); + } + + public static function getAdditionalConfigFiles(): array + { + return [__DIR__ . '/config/configured_rule.neon']; + } + + protected function getRule(): Rule + { + return self::getContainer()->getByType(LiveResponseMustBeReturnedByLiveActionRule::class); + } +} diff --git a/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/config/configured_rule.neon b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/config/configured_rule.neon new file mode 100644 index 0000000..892eda6 --- /dev/null +++ b/tests/Rules/LiveComponent/LiveResponseMustBeReturnedByLiveActionRule/config/configured_rule.neon @@ -0,0 +1,9 @@ +includes: + - ../../../../test-extension.neon + +parameters: + scanFiles: + - ../../../../stubs/LiveResponse.php + +rules: + - Kocal\PHPStanSymfonyUX\Rules\LiveComponent\LiveResponseMustBeReturnedByLiveActionRule diff --git a/tests/stubs/LiveResponse.php b/tests/stubs/LiveResponse.php new file mode 100644 index 0000000..1f1bfe3 --- /dev/null +++ b/tests/stubs/LiveResponse.php @@ -0,0 +1,19 @@ +