Improve Stimulus phpdoc

symfony · Jul 13, 2022 · 14644e4 · 14644e4
1 parent 6478066
commit 14644e4
Show file tree

Hide file tree

Showing 6 changed files with 109 additions and 94 deletions.
diff --git a/phpstan-baseline.neon b/phpstan-baseline.neon
@@ -15,6 +15,46 @@ parameters:
 			count: 1
 			path: src/DependencyInjection/Configuration.php
 
+		-
+			message: "#^Function twig_escape_filter not found\\.$#"
+			count: 1
+			path: src/Dto/AbstractStimulusDto.php
+
+		-
+			message: "#^Call to function is_string\\(\\) with 0 will always evaluate to false\\.$#"
+			count: 1
+			path: src/Dto/StimulusActionsDto.php
+
+		-
+			message: "#^Call to function is_string\\(\\) with array\\{non\\-empty\\-array\\<0\\|string, string\\|null\\>\\} will always evaluate to false\\.$#"
+			count: 1
+			path: src/Dto/StimulusActionsDto.php
+
+		-
+			message: "#^Call to function is_string\\(\\) with non\\-empty\\-array\\<0\\|string, string\\|null\\> will always evaluate to false\\.$#"
+			count: 2
+			path: src/Dto/StimulusActionsDto.php
+
+		-
+			message: "#^Else branch is unreachable because previous condition is always true\\.$#"
+			count: 1
+			path: src/Dto/StimulusActionsDto.php
+
+		-
+			message: "#^Result of && is always false\\.$#"
+			count: 1
+			path: src/Dto/StimulusActionsDto.php
+
+		-
+			message: "#^Else branch is unreachable because previous condition is always true\\.$#"
+			count: 1
+			path: src/Dto/StimulusControllersDto.php
+
+		-
+			message: "#^Else branch is unreachable because previous condition is always true\\.$#"
+			count: 1
+			path: src/Dto/StimulusTargetsDto.php
+
 		-
 			message: "#^Call to method withAttribute\\(\\) on an unknown class Fig\\\\Link\\\\Link\\.$#"
 			count: 2
@@ -50,8 +90,3 @@ parameters:
 			count: 1
 			path: src/EventListener/PreLoadAssetsEventListener.php
 
-		-
-			message: "#^Function twig_escape_filter not found\\.$#"
-			count: 1
-			path: src/Dto/AbstractStimulusDto.php
-
diff --git a/psalm.baseline.xml b/psalm.baseline.xml
@@ -1,10 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="4.8.1@f73f2299dbc59a3e6c4d66cff4605176e728ee69">
-  <file src="src/CacheWarmer/EntrypointCacheWarmer.php">
-    <TooManyArguments occurrences="1">
-      <code>parent::__construct($phpArrayFile, $fallbackPool)</code>
-    </TooManyArguments>
-  </file>
+<files psalm-version="4.24.0@06dd975cb55d36af80f242561738f16c5f58264f">
   <file src="src/DependencyInjection/Configuration.php">
     <RedundantCondition occurrences="1">
       <code>method_exists($treeBuilder, 'getRootNode')</code>
@@ -13,6 +8,23 @@
       <code>root</code>
     </UndefinedMethod>
   </file>
+  <file src="src/Dto/AbstractStimulusDto.php">
+    <UndefinedFunction occurrences="1">
+      <code>twig_escape_filter($this-&gt;env, $value, 'html_attr')</code>
+    </UndefinedFunction>
+  </file>
+  <file src="src/Dto/StimulusActionsDto.php">
+    <InvalidArrayOffset occurrences="1">
+      <code>[$possibleEventName =&gt; $controllerAction]</code>
+    </InvalidArrayOffset>
+    <TypeDoesNotContainType occurrences="5">
+      <code>\is_string($controllerAction)</code>
+      <code>\is_string($controllerAction)</code>
+      <code>\is_string($controllerActions)</code>
+      <code>\is_string($possibleEventName)</code>
+      <code>\is_string($possibleEventName) &amp;&amp; \is_string($controllerAction)</code>
+    </TypeDoesNotContainType>
+  </file>
   <file src="src/EventListener/PreLoadAssetsEventListener.php">
     <RedundantCondition occurrences="1">
       <code>method_exists($event, 'isMainRequest')</code>
@@ -30,9 +42,4 @@
       <code>Link|FigLink</code>
     </UndefinedDocblockClass>
   </file>
-  <file src="src/Dto/AbstractStimulusDto.php">
-    <UndefinedFunction occurrences="1">
-      <code>twig_escape_filter($this->env, $value, 'html_attr')</code>
-    </UndefinedFunction>
-  </file>
 </files>
diff --git a/src/Dto/StimulusActionsDto.php b/src/Dto/StimulusActionsDto.php
@@ -17,26 +17,23 @@ final class StimulusActionsDto extends AbstractStimulusDto
     private $parameters = [];
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "actions" and "events".
-     *                                           Or this can be a string controller name and
-     *                                           action and event are passed as the 2nd and 3rd arguments.
-     * @param string|null  $actionName           The action to trigger if a string is passed to the 1st argument. Optional.
-     * @param string|null  $eventName            The event to listen to trigger if a string is passed to the 1st argument. Optional.
-     * @param array        $parameters           Parameters to pass to the action if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string      $actionName     the action to trigger
+     * @param string|null $eventName      The event to listen to trigger. Optional.
+     * @param array       $parameters     Parameters to pass to the action. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function addAction($dataOrControllerName, string $actionName = null, string $eventName = null, array $parameters = []): void
+    public function addAction($controllerName, string $actionName = null, string $eventName = null, array $parameters = []): void
     {
-        if (\is_string($dataOrControllerName)) {
-            $data = [$dataOrControllerName => null === $eventName ? [[$actionName]] : [[$eventName => $actionName]]];
+        if (\is_string($controllerName)) {
+            $data = [$controllerName => null === $eventName ? [[$actionName]] : [[$eventName => $actionName]]];
         } else {
             if ($actionName || $eventName || $parameters) {
                 throw new \InvalidArgumentException('You cannot pass a string to the second or third argument nor an array to the fourth argument while passing an array to the first argument of stimulus_action(): check the documentation.');
             }
 
-            $data = $dataOrControllerName;
+            $data = $controllerName;
 
             if (!$data) {
                 return;

diff --git a/src/Dto/StimulusControllersDto.php b/src/Dto/StimulusControllersDto.php
@@ -17,24 +17,21 @@ final class StimulusControllersDto extends AbstractStimulusDto
     private $values = [];
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "values". Or this
-     *                                           can be a string controller name and data
-     *                                           is passed as the 2nd argument.
-     * @param array        $controllerValues     array of data if a string is passed to the 1st argument
+     * @param string $controllerName   the Stimulus controller name
+     * @param array  $controllerValues array of data if a string is passed to the 1st argument
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function addController($dataOrControllerName, array $controllerValues = []): void
+    public function addController($controllerName, array $controllerValues = []): void
     {
-        if (\is_string($dataOrControllerName)) {
-            $data = [$dataOrControllerName => $controllerValues];
+        if (\is_string($controllerName)) {
+            $data = [$controllerName => $controllerValues];
         } else {
             if ($controllerValues) {
                 throw new \InvalidArgumentException('You cannot pass an array to the first and second argument of stimulus_controller(): check the documentation.');
             }
 
-            $data = $dataOrControllerName;
+            $data = $controllerName;
 
             if (!$data) {
                 return;

diff --git a/src/Dto/StimulusTargetsDto.php b/src/Dto/StimulusTargetsDto.php
@@ -16,24 +16,21 @@ final class StimulusTargetsDto extends AbstractStimulusDto
     private $targets = [];
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "targets". Or this can
-     *                                           be a string controller name and targets are
-     *                                           passed as the 2nd argument.
-     * @param string|null  $targetNames          The space-separated list of target names if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string|null $targetNames    The space-separated list of target names if a string is passed to the 1st argument. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function addTarget($dataOrControllerName, string $targetNames = null): void
+    public function addTarget($controllerName, string $targetNames = null): void
     {
-        if (\is_string($dataOrControllerName)) {
-            $data = [$dataOrControllerName => $targetNames];
+        if (\is_string($controllerName)) {
+            $data = [$controllerName => $targetNames];
         } else {
             if ($targetNames) {
                 throw new \InvalidArgumentException('You cannot pass a string to the second argument while passing an array to the first argument of stimulus_target(): check the documentation.');
             }
 
-            $data = $dataOrControllerName;
+            $data = $controllerName;
 
             if (!$data) {
                 return;

diff --git a/src/Twig/StimulusTwigExtension.php b/src/Twig/StimulusTwigExtension.php
@@ -38,128 +38,110 @@ public function getFilters(): array
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "values". Or this
-     *                                           can be a string controller name and data
-     *                                           is passed as the 2nd argument.
-     * @param array        $controllerValues     array of data if a string is passed to the 1st argument
+     * @param string $controllerName   the Stimulus controller name
+     * @param array  $controllerValues array of data if a string is passed to the 1st argument
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function renderStimulusController(Environment $env, $dataOrControllerName, array $controllerValues = []): StimulusControllersDto
+    public function renderStimulusController(Environment $env, $controllerName, array $controllerValues = []): StimulusControllersDto
     {
         if (!\is_string($dataOrControllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_controller() is deprecated.');
         }
 
         $dto = new StimulusControllersDto($env);
-        $dto->addController($dataOrControllerName, $controllerValues);
+        $dto->addController($controllerName, $controllerValues);
 
         return $dto;
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "values". Or this
-     *                                           can be a string controller name and data
-     *                                           is passed as the 2nd argument.
-     * @param array        $controllerValues     array of data if a string is passed to the 1st argument
+     * @param string $controllerName   the Stimulus controller name
+     * @param array  $controllerValues array of data if a string is passed to the 1st argument
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function appendStimulusController(StimulusControllersDto $dto, $dataOrControllerName, array $controllerValues = []): StimulusControllersDto
+    public function appendStimulusController(StimulusControllersDto $dto, $controllerName, array $controllerValues = []): StimulusControllersDto
     {
-        if (!\is_string($dataOrControllerName)) {
+        if (!\is_string($controllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_controller() is deprecated.');
         }
 
-        $dto->addController($dataOrControllerName, $controllerValues);
+        $dto->addController($controllerName, $controllerValues);
 
         return $dto;
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "actions" and "events".
-     *                                           Or this can be a string controller name and
-     *                                           action and event are passed as the 2nd and 3rd arguments.
-     * @param string|null  $actionName           The action to trigger if a string is passed to the 1st argument. Optional.
-     * @param string|null  $eventName            The event to listen to trigger if a string is passed to the 1st argument. Optional.
-     * @param array        $parameters           Parameters to pass to the action if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string      $actionName     the action to trigger
+     * @param string|null $eventName      The event to listen to trigger. Optional.
+     * @param array       $parameters     Parameters to pass to the action. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function renderStimulusAction(Environment $env, $dataOrControllerName, string $actionName = null, string $eventName = null, array $parameters = []): StimulusActionsDto
+    public function renderStimulusAction(Environment $env, $controllerName, string $actionName = null, string $eventName = null, array $parameters = []): StimulusActionsDto
     {
         if (!\is_string($dataOrControllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_action() is deprecated.');
         }
 
         $dto = new StimulusActionsDto($env);
-        $dto->addAction($dataOrControllerName, $actionName, $eventName, $parameters);
+        $dto->addAction($controllerName, $actionName, $eventName, $parameters);
 
         return $dto;
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "actions" and "events".
-     *                                           Or this can be a string controller name and
-     *                                           action and event are passed as the 2nd and 3rd arguments.
-     * @param string|null  $actionName           The action to trigger if a string is passed to the 1st argument. Optional.
-     * @param string|null  $eventName            The event to listen to trigger if a string is passed to the 1st argument. Optional.
-     * @param array        $parameters           Parameters to pass to the action if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string      $actionName     the action to trigger
+     * @param string|null $eventName      The event to listen to trigger. Optional.
+     * @param array       $parameters     Parameters to pass to the action. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function appendStimulusAction(StimulusActionsDto $dto, $dataOrControllerName, string $actionName = null, string $eventName = null, array $parameters = []): StimulusActionsDto
+    public function appendStimulusAction(StimulusActionsDto $dto, $controllerName, string $actionName = null, string $eventName = null, array $parameters = []): StimulusActionsDto
     {
-        if (!\is_string($dataOrControllerName)) {
+        if (!\is_string($controllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_action() is deprecated.');
         }
 
-        $dto->addAction($dataOrControllerName, $actionName, $eventName, $parameters);
+        $dto->addAction($controllerName, $actionName, $eventName, $parameters);
 
         return $dto;
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "targets". Or this can
-     *                                           be a string controller name and targets are
-     *                                           passed as the 2nd argument.
-     * @param string|null  $targetNames          The space-separated list of target names if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string|null $targetNames    The space-separated list of target names if a string is passed to the 1st argument. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function renderStimulusTarget(Environment $env, $dataOrControllerName, string $targetNames = null): StimulusTargetsDto
+    public function renderStimulusTarget(Environment $env, $controllerName, string $targetNames = null): StimulusTargetsDto
     {
         if (!\is_string($dataOrControllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_target() is deprecated.');
         }
 
         $dto = new StimulusTargetsDto($env);
-        $dto->addTarget($dataOrControllerName, $targetNames);
+        $dto->addTarget($controllerName, $targetNames);
 
         return $dto;
     }
 
     /**
-     * @param string|array $dataOrControllerName This can either be a map of controller names
-     *                                           as keys set to their "targets". Or this can
-     *                                           be a string controller name and targets are
-     *                                           passed as the 2nd argument.
-     * @param string|null  $targetNames          The space-separated list of target names if a string is passed to the 1st argument. Optional.
+     * @param string      $controllerName the Stimulus controller name
+     * @param string|null $targetNames    The space-separated list of target names if a string is passed to the 1st argument. Optional.
      *
      * @throws \Twig\Error\RuntimeError
      */
-    public function appendStimulusTarget(StimulusTargetsDto $dto, $dataOrControllerName, string $targetNames = null): StimulusTargetsDto
+    public function appendStimulusTarget(StimulusTargetsDto $dto, $controllerName, string $targetNames = null): StimulusTargetsDto
     {
-        if (!\is_string($dataOrControllerName)) {
+        if (!\is_string($controllerName)) {
             trigger_deprecation('symfony/webpack-encore-bundle', 'v1.15.0', 'Passing an array as first argument of stimulus_target() is deprecated.');
         }
 
-        $dto->addTarget($dataOrControllerName, $targetNames);
+        $dto->addTarget($controllerName, $targetNames);
 
         return $dto;
     }