update DocBlock

mimmi20 · Dec 18, 2023 · cc7a324 · cc7a324
1 parent 5672e45
commit cc7a324
Show file tree

Hide file tree

Showing 17 changed files with 85 additions and 117 deletions.
diff --git a/phpstan.neon b/phpstan.neon
@@ -102,4 +102,5 @@ parameters:
     - '~Parameter #1 \$pages of method Mimmi20\\Mezzio\\Navigation\\(Navigation|Page\\(Route|Uri))::addPages\(\) expects iterable<Mimmi20\\Mezzio\\Navigation\\Page\\PageInterface>, array<int, string> given~'
     - '~Access to private property Mimmi20\\Mezzio\\Navigation\\Page\\(Route|Uri)::\$target~'
     - '~Access to an undefined property Mimmi20\\Mezzio\\Navigation\\Page\\(Route|Uri)::~'
-    - '~Offset .uri. does not exist on array<int, mixed>~'
+    - '~::preparePages\(\) expects array<array<array<string>\|string>>, array<string> given~'
+    - '~will always evaluate to false~'
diff --git a/src/Config/NavigationConfig.php b/src/Config/NavigationConfig.php
@@ -29,7 +29,7 @@ final class NavigationConfig implements NavigationConfigInterface
     private ServerRequestInterface | null $request       = null;
     private AuthorizationInterface | null $authorization = null;
 
-    /** @var array<int|string, array<string>>|null */
+    /** @var array<array<string>>|null */
     private array | null $pages = null;
 
     /** @throws void */
@@ -93,7 +93,7 @@ public function setAuthorization(AuthorizationInterface | null $authorization =
     }
 
     /**
-     * @return array<int|string, array<string, array<array<string>|string>>>|null
+     * @return array<array<string>>|null
      *
      * @throws void
      */
@@ -103,7 +103,7 @@ public function getPages(): array | null
     }
 
     /**
-     * @param array<int|string, array<string>> $pages
+     * @param array<array<string>> $pages
      *
      * @throws void
      */

diff --git a/src/Config/NavigationConfigInterface.php b/src/Config/NavigationConfigInterface.php
@@ -54,14 +54,14 @@ public function getAuthorization(): AuthorizationInterface | null;
     public function setAuthorization(AuthorizationInterface | null $authorization = null): void;
 
     /**
-     * @return array<int|string, array<string, array<array<string>|string>>>|null
+     * @return array<array<string>>|null
      *
      * @throws void
      */
     public function getPages(): array | null;
 
     /**
-     * @param array<int|string, array<string>> $pages
+     * @param array<array<string>> $pages
      *
      * @throws void
      */

diff --git a/src/ContainerInterface.php b/src/ContainerInterface.php
@@ -20,7 +20,8 @@
 /**
  * ContainerInterface class for Mimmi20\Mezzio\Navigation\Navigation classes.
  *
- * @extends RecursiveIterator<string, PageInterface>
+ * @template TPage of PageInterface
+ * @extends RecursiveIterator<string, TPage>
  */
 interface ContainerInterface extends Countable, RecursiveIterator
 {
@@ -139,7 +140,7 @@ public function findAllBy(string $property, mixed $value): array;
     /**
      * Returns an array representation of all pages in container
      *
-     * @return array<int<0, max>, array<int, mixed>>
+     * @return array<mixed>
      *
      * @throws void
      */

diff --git a/src/ContainerTrait.php b/src/ContainerTrait.php
@@ -371,7 +371,7 @@ final public function findAllBy(string $property, mixed $value): array
     /**
      * Returns an array representation of all pages in container
      *
-     * @return array<int<0, max>, array<int, mixed>>
+     * @return array<mixed>
      *
      * @throws void
      */

diff --git a/src/Exception/ExceptionInterface.php b/src/Exception/ExceptionInterface.php
@@ -12,9 +12,11 @@
 
 namespace Mimmi20\Mezzio\Navigation\Exception;
 
+use Throwable;
+
 /**
  * Navigation exception
  */
-interface ExceptionInterface
+interface ExceptionInterface extends Throwable
 {
 }
diff --git a/src/Navigation.php b/src/Navigation.php
@@ -12,8 +12,12 @@
 
 namespace Mimmi20\Mezzio\Navigation;
 
+use Mimmi20\Mezzio\Navigation\Page\PageInterface;
+
 /**
  * A simple container class for {@link \Mimmi20\Mezzio\Navigation\Navigation} pages
+ *
+ * @implements ContainerInterface<PageInterface>
  */
 final class Navigation implements ContainerInterface
 {

diff --git a/src/Page/PageInterface.php b/src/Page/PageInterface.php
@@ -14,10 +14,11 @@
 
 use Mimmi20\Mezzio\Navigation\ContainerInterface;
 use Mimmi20\Mezzio\Navigation\Exception;
-use Traversable;
 
 /**
  * Interface for Mimmi20\Mezzio\Navigation\Page pages
+ *
+ * @extends ContainerInterface<PageInterface>
  */
 interface PageInterface extends ContainerInterface
 {
@@ -29,7 +30,7 @@ interface PageInterface extends ContainerInterface
      * corresponds to setTarget(), and the option 'reset_params' corresponds to
      * the method setResetParams().
      *
-     * @param iterable<string> $options associative array of options to set
+     * @param iterable<string, array<string>|bool|string> $options associative array of options to set
      *
      * @throws Exception\InvalidArgumentException if invalid options are given
      */
@@ -174,7 +175,7 @@ public function getTarget(): string | null;
      * prev, next, help, etc), and the value is a mixed value that could somehow
      * be considered a page.
      *
-     * @param iterable<int|string, ContainerInterface|iterable<string, string>|PageInterface|string>|null $relations [optional] an associative array of
+     * @param iterable<ContainerInterface<PageInterface>|iterable<string>|PageInterface|string>|null $relations [optional] an associative array of
      *                                                                                                                            forward links to other pages
      *
      * @throws void
@@ -192,7 +193,7 @@ public function setRel(iterable | null $relations = null): void;
      * @param string|null $relation [optional] name of relation to return. If not
      *                              given, all relations will be returned.
      *
-     * @return ContainerInterface|iterable<int|string, ContainerInterface|iterable<string, string>|PageInterface|string>|PageInterface|string|null an array of relations. If $relation is not
+     * @return ContainerInterface<PageInterface>|iterable<ContainerInterface<PageInterface>|iterable<string>|PageInterface|string>|PageInterface|string|null an array of relations. If $relation is not
      *                           specified, all relations will be returned in
      *                           an associative array.
      *
@@ -208,7 +209,7 @@ public function getRel(string | null $relation = null): iterable | ContainerInte
      * prev, next, help, etc), and the value is a mixed value that could somehow
      * be considered a page.
      *
-     * @param iterable<int|string, ContainerInterface|iterable<string, string>|PageInterface|string>|null $relations [optional] an associative array of
+     * @param iterable<ContainerInterface<PageInterface>|iterable<string>|PageInterface|string>|null $relations [optional] an associative array of
      *                                                                                                                            reverse links to other pages
      *
      * @throws void
@@ -226,7 +227,7 @@ public function setRev(iterable | null $relations = null): void;
      * @param string|null $relation [optional] name of relation to return. If not
      *                              given, all relations will be returned.
      *
-     * @return ContainerInterface|iterable<int|string, ContainerInterface|iterable<string, string>|PageInterface|string>|PageInterface|string|null an array of relations. If $relation is not
+     * @return ContainerInterface<PageInterface>|iterable<ContainerInterface<PageInterface>|iterable<string>|PageInterface|string>|PageInterface|string|null an array of relations. If $relation is not
      *                           specified, all relations will be returned in
      *                           an associative array.
      *
@@ -241,7 +242,6 @@ public function getRev(string | null $relation = null): iterable | ContainerInte
      *                               Default is null, which sets no
      *                               specific order.
      *
-     * @throws Exception\InvalidArgumentException if order is not integer or null
      * @throws void
      */
     public function setOrder(int | float | string | null $order = null): void;
@@ -263,7 +263,6 @@ public function getOrder(): int | null;
      *                         sets no resource.
      *
      * @throws Exception\InvalidArgumentException if $resource is invalid
-     * @throws void
      */
     public function setResource(string $resource): void;
 
@@ -412,7 +411,7 @@ public function getVisible(bool $recursive = false): bool;
     /**
      * Sets parent container
      *
-     * @param ContainerInterface|null $parent [optional] new parent to set.
+     * @param ContainerInterface<PageInterface>|null $parent [optional] new parent to set.
      *                                        Default is null which will set no parent.
      *
      * @throws Exception\InvalidArgumentException
@@ -422,7 +421,7 @@ public function setParent(ContainerInterface | null $parent = null): void;
     /**
      * Returns parent container
      *
-     * @return ContainerInterface|null parent container or null
+     * @return ContainerInterface<PageInterface>|null parent container or null
      *
      * @throws void
      */
@@ -434,8 +433,8 @@ public function getParent(): ContainerInterface | null;
      * If the given property is native (id, class, title, etc), the matching
      * set method will be used. Otherwise, it will be set as a custom property.
      *
-     * @param string                                              $property property name
-     * @param bool|float|int|iterable<string, string>|string|null $value    value to set
+     * @param string                                                                                                              $property property name
+     * @param bool|ContainerInterface<PageInterface>|float|int|iterable<string, (array<string>|string)>|PageInterface|string|null $value    value to set
      *
      * @throws Exception\InvalidArgumentException if property name is invalid
      */
@@ -450,7 +449,7 @@ public function set(string $property, bool | float | int | iterable | string | n
      *
      * @param string $property property name
      *
-     * @return bool|float|int|iterable<string, string>|string|null the property's value or null
+     * @return bool|ContainerInterface<PageInterface>|float|int|iterable<string, (array<string>|string)>|PageInterface|string|null the property's value or null
      *
      * @throws Exception\InvalidArgumentException if property name is invalid
      */
@@ -459,24 +458,22 @@ public function get(string $property): bool | float | int | iterable | string |
     /**
      * Adds a forward relation to the page
      *
-     * @param string                                                                    $relation relation name (e.g. alternate, glossary,
-     *                                                                                            canonical, etc)
-     * @param array<string, string>|ContainerInterface|PageInterface|string|Traversable $value    value to set for relation
+     * @param string                                                                  $relation relation name (e.g. alternate, glossary, canonical, etc)
+     * @param ContainerInterface<PageInterface>|iterable<string>|PageInterface|string $value    value to set for relation
      *
      * @throws void
      */
-    public function addRel(string $relation, array | ContainerInterface | self | string | Traversable $value): void;
+    public function addRel(string $relation, iterable | ContainerInterface | self | string $value): void;
 
     /**
      * Adds a reverse relation to the page
      *
-     * @param string                                                                    $relation relation name (e.g. alternate, glossary,
-     *                                                                                            canonical, etc)
-     * @param array<string, string>|ContainerInterface|PageInterface|string|Traversable $value    value to set for relation
+     * @param string                                                                  $relation relation name (e.g. alternate, glossary, canonical, etc)
+     * @param ContainerInterface<PageInterface>|iterable<string>|PageInterface|string $value    value to set for relation
      *
      * @throws void
      */
-    public function addRev(string $relation, array | ContainerInterface | self | string | Traversable $value): void;
+    public function addRev(string $relation, iterable | ContainerInterface | self | string $value): void;
 
     /**
      * Removes a forward relation from the page
@@ -499,7 +496,7 @@ public function removeRev(string $relation): void;
     /**
      * Returns an array containing the defined forward relations
      *
-     * @return array<string> defined forward relations
+     * @return array<int, (int|string)> defined forward relations
      *
      * @throws void
      */
@@ -508,7 +505,7 @@ public function getDefinedRel(): array;
     /**
      * Returns an array containing the defined reverse relations
      *
-     * @return array<string> defined reverse relations
+     * @return array<int, (int|string)> defined reverse relations
      *
      * @throws void
      */
@@ -517,7 +514,7 @@ public function getDefinedRev(): array;
     /**
      * Returns custom properties as an array
      *
-     * @return array<string, array<string, string>|bool|float|int|iterable|string|null> an array containing custom properties
+     * @return array<string, bool|ContainerInterface<PageInterface>|float|int|iterable<string, (array<string>|string)>|PageInterface|string|null> an array containing custom properties
      *
      * @throws void
      */