Update phpDoc

.phpdoc/template/base.html.twig

@@ -3,9 +3,9 @@
 {%
 set topMenu = {
     "menu": [
-        { "name": "Packagist", "url": "https://packagist.org/packages/opencultureconsulting/basics"}
     ],
     "social": [
+        { "iconClass": "fab fa-php", "url": "https://packagist.org/packages/opencultureconsulting/basics"},
         { "iconClass": "fab fa-github", "url": "https://github.com/opencultureconsulting/php-basics"},
         { "iconClass": "fab fa-mastodon", "url": "https://openbiblio.social/@occ"},
         { "iconClass": "fas fa-envelope-open-text", "url": "mailto:office@opencultureconsulting.com"}

.phpdoc/template/components/sidebar.html.twig

@@ -0,0 +1,31 @@
+<input class="phpdocumentor-sidebar__menu-button" type="checkbox" id="sidebar-button" name="sidebar-button" />
+<label class="phpdocumentor-sidebar__menu-icon" for="sidebar-button">
+    Menu
+</label>
+<aside class="phpdocumentor-column -three phpdocumentor-sidebar">
+    {% for version in project.versions %}
+        {% for toc in version.tableOfContents %}
+        <section class="phpdocumentor-sidebar__category">
+            <h2 class="phpdocumentor-sidebar__category-header">{{ toc.name|capitalize }}</h2>
+                {% for root in toc.roots %}
+                    {{ toc(root, 'components/menu.html.twig', 1) }}
+                {% endfor %}
+        </section>
+        {% endfor %}
+    {% endfor %}
+
+    <section class="phpdocumentor-sidebar__category">
+        <h2 class="phpdocumentor-sidebar__category-header">Reports</h2>
+        {% if project.settings.custom['graphs.enabled'] %}
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="graphs/classes.html">Class Diagram</a></h3>
+        {% endif %}
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/deprecated.html">Deprecated</a></h3>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/errors.html">Errors</a></h3>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="reports/markers.html">Markers</a></h3>
+    </section>
+
+    <section class="phpdocumentor-sidebar__category">
+        <h2 class="phpdocumentor-sidebar__category-header">Indices</h2>
+        <h3 class="phpdocumentor-sidebar__root-package"><a href="indices/files.html">Files</a></h3>
+    </section>
+</aside>

phpdoc.dist.xml

@@ -26,14 +26,14 @@
                 <ignore-tag>psalm-suppress</ignore-tag>
             </ignore-tags>
         </api>
-        <guide>
+        <guide format="rst">
             <source dsn=".">
                 <path>/.phpdoc/guide</path>
             </source>
             <output>guides</output>
         </guide>
     </version>
-    <setting name="graphs.enabled" value="true"/>
+    <setting name="graphs.enabled" value="false"/>
     <setting name="guides.enabled" value="true"/>
     <setting name="template.color" value="orange"/>
 </phpdocumentor>

psalm.xml

@@ -6,7 +6,8 @@
     errorLevel="1"
     resolveFromConfigFile="true"
     findUnusedBaselineEntry="true"
-    findUnusedCode="false"
+    findUnusedCode="true"
+    findUnusedVariablesAndParams="true"
 >
     <issueHandlers>
         <RedundantCastGivenDocblockType errorLevel="suppress"/>

src/DataStructures/StrictList.php

@@ -27,7 +27,6 @@ use ArrayAccess;
 use Countable;
 use InvalidArgumentException;
 use Iterator;
-use OutOfRangeException;
 use RuntimeException;
 use SplDoublyLinkedList;
 use OCC\Basics\Traits\Getter;
@@ -56,27 +55,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     use Getter;
 
     /**
-     * Queue style iterator mode (First In, First Out).
+     * The allowed data types for list values.
-     */
-    public const IT_MODE_FIFO = 0;
-
-    /**
-     * Stack style iterator mode (Last In, First Out).
-     */
-    public const IT_MODE_LIFO = 2;
-
-    /**
-     * Destructive iterator mode (delete values after iteration).
-     */
-    public const IT_MODE_DELETE = 1;
-
-    /**
-     * Preserving iterator mode (keep values after iteration).
-     */
-    public const IT_MODE_KEEP = 0;
-
-    /**
-     * The allowed data types for values.
      *
      * @var string[]
      *
@@ -153,27 +132,15 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
     }
 
     /**
-     * Count the number of values on the list.
+     * Get allowed data types for list values.
      *
-     * @return int The current number of values
+     * @return string[] The list of allowed data types
      *
      * @api
      */
-    public function count(): int
+    public function getAllowedTypes(): array
     {
-        return parent::count();
+        return $this->allowedTypes;
-    }
-
-    /**
-     * Get current list value.
-     *
-     * @return AllowedType The current value
-     *
-     * @api
-     */
-    public function current(): mixed
-    {
-        return parent::current();
     }
 
     /**
@@ -216,30 +183,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         return false;
     }
 
-    /**
-     * Check if the list is empty.
-     *
-     * @return bool Whether the list is empty
-     *
-     * @api
-     */
-    public function isEmpty(): bool
-    {
-        return parent::isEmpty();
-    }
-
-    /**
-     * Get the current value's offset.
-     *
-     * @return int The current offset
-     *
-     * @api
-     */
-    public function key(): int
-    {
-        return parent::key();
-    }
-
     /**
      * Magic getter method for $this->allowedTypes.
      *
@@ -249,49 +192,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      */
     protected function magicGetAllowedTypes(): array
     {
-        return $this->allowedTypes;
+        return $this->getAllowedTypes();
-    }
-
-    /**
-     * Move cursor to the next value on the list.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function next(): void
-    {
-        parent::next();
-    }
-
-    /**
-     * Check if the specified offset exists.
-     *
-     * @param int $offset The offset being checked
-     *
-     * @return bool Whether the offset exists
-     *
-     * @api
-     */
-    public function offsetExists(mixed $offset): bool
-    {
-        return parent::offsetExists($offset);
-    }
-
-    /**
-     * Get the value at the specified offset.
-     *
-     * @param int $offset The offset to get
-     *
-     * @return ?AllowedType The value at the offset or NULL
-     *
-     * @throws OutOfRangeException
-     *
-     * @api
-     */
-    public function offsetGet(mixed $offset): mixed
-    {
-        return parent::offsetGet($offset);
     }
 
     /**
@@ -304,7 +205,7 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      *
      * @throws InvalidArgumentException
      *
-     * @api
+     * @internal
      */
     public function offsetSet(mixed $offset, mixed $value): void
     {
@@ -320,22 +221,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         parent::offsetSet($offset, $value);
     }
 
-    /**
-     * Unset the specified offset.
-     *
-     * @param int $offset The offset to unset
-     *
-     * @return void
-     *
-     * @throws OutOfRangeException
-     *
-     * @api
-     */
-    public function offsetUnset(mixed $offset): void
-    {
-        parent::offsetUnset($offset);
-    }
-
     /**
      * Pops an value from the end of the list.
      *
@@ -379,18 +264,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         }
     }
 
-    /**
-     * Move cursor to the previous value on the list.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function prev(): void
-    {
-        parent::prev();
-    }
-
     /**
      * Push an value at the end of the list.
      *
@@ -415,18 +288,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         parent::push($value);
     }
 
-    /**
-     * Move cursor back to the start of the list.
-     *
-     * @return void
-     *
-     * @api
-     */
-    public function rewind(): void
-    {
-        parent::rewind();
-    }
-
     /**
      * Get string representation of $this.
      *
@@ -447,8 +308,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
      * @return void
      *
      * @throws InvalidArgumentException
-     *
-     * @internal
      */
     protected function setAllowedTypes(array $allowedTypes = []): void
     {
@@ -554,18 +413,6 @@ class StrictList extends SplDoublyLinkedList implements ArrayAccess, Countable,
         parent::unshift($value);
     }
 
-    /**
-     * Check if the list contains any more values.
-     *
-     * @return bool Whether the list contains more values
-     *
-     * @api
-     */
-    public function valid(): bool
-    {
-        return parent::valid();
-    }
-
     /**
      * Create a type-sensitive, traversable list of values.
      *

src/DataStructures/StrictQueue.php

@@ -51,6 +51,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      * Dequeue an item from the queue.
      *
      * @return AllowedType The dequeued item
+     *
+     * @api
      */
     public function dequeue(): mixed
     {
@@ -65,6 +67,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      * @return void
      *
      * @throws \InvalidArgumentException
+     *
+     * @api
      */
     public function enqueue(mixed $item): void
     {
@@ -90,6 +94,8 @@ class StrictQueue extends StrictList implements ArrayAccess, Countable, Iterator
      * @return int The set of flags and modes of iteration
      *
      * @throws RuntimeException
+     *
+     * @api
      */
     final public function setIteratorMode(int $mode): int
     {

src/DataStructures/StrictStack.php

@@ -55,6 +55,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      * @return void
      *
      * @throws \InvalidArgumentException
+     *
+     * @api
      */
     public function stack(mixed $item): void
     {
@@ -65,6 +67,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      * Unstack an item from the stack.
      *
      * @return AllowedType The unstacked item
+     *
+     * @api
      */
     public function unstack(): mixed
     {
@@ -90,6 +94,8 @@ class StrictStack extends StrictList implements ArrayAccess, Countable, Iterator
      * @return int The set of flags and modes of iteration
      *
      * @throws RuntimeException
+     *
+     * @api
      */
     final public function setIteratorMode(int $mode): int
     {

src/InterfaceTraits/ArrayAccessTrait.php

@@ -33,6 +33,7 @@ use ArrayAccess;
  *
  * @template TKey of int|string
  * @template TValue of mixed
+ * @template TData of array<TKey, TValue>
  * @implements ArrayAccess<TKey, TValue>
  * @phpstan-require-implements ArrayAccess
  */
@@ -41,7 +42,7 @@ trait ArrayAccessTrait
     /**
      * Holds the array-accessible data.
      *
-     * @var array<TKey, TValue>
+     * @var TData
      */
     protected array $data = [];
 

src/InterfaceTraits/CountableTrait.php

@@ -33,6 +33,7 @@ use Countable;
  *
  * @template TKey of int|string
  * @template TValue of mixed
+ * @template TData of array<TKey, TValue>
  * @implements Countable<TValue>
  * @phpstan-require-implements Countable
  */
@@ -41,7 +42,7 @@ trait CountableTrait
     /**
      * Holds the countable data.
      *
-     * @var array<TKey, TValue>
+     * @var TData
      */
     protected array $data = [];
 

src/InterfaceTraits/IteratorAggregateTrait.php

@@ -34,6 +34,7 @@ use IteratorAggregate;
  *
  * @template TKey of int|string
  * @template TValue of mixed
+ * @template TData of array<TKey, TValue>
  * @implements IteratorAggregate<TKey, TValue>
  * @phpstan-require-implements IteratorAggregate
  */
@@ -42,7 +43,7 @@ trait IteratorAggregateTrait
     /**
      * Holds the iterable data.
      *
-     * @var array<TKey, TValue>
+     * @var TData
      */
     protected array $data = [];
 

src/InterfaceTraits/IteratorTrait.php

@@ -33,6 +33,7 @@ use Iterator;
  *
  * @template TKey of int|string
  * @template TValue of mixed
+ * @template TData of array<TKey, TValue>
  * @implements Iterator<TKey, TValue>
  * @phpstan-require-implements Iterator
  */
@@ -41,7 +42,7 @@ trait IteratorTrait
     /**
      * Holds the iterable data.
      *
-     * @var array<TKey, TValue>
+     * @var TData
      */
     protected array $data = [];
 
@@ -75,6 +76,16 @@ trait IteratorTrait
         next($this->data);
     }
 
+    /**
+     * Move back to previous item.
+     *
+     * @return void
+     */
+    public function prev(): void
+    {
+        prev($this->data);
+    }
+
     /**
      * Rewind the iterator to the first item.
      *

src/Traits/Singleton.php

@@ -23,7 +23,6 @@ declare(strict_types=1);
 
 namespace OCC\Basics\Traits;
 
-use Exception;
 use LogicException;
 
 /**
@@ -38,6 +37,8 @@ trait Singleton
      * Holds the singleton instance.
      *
      * @var array<string, static>
+     *
+     * @internal
      */
     private static array $singleton = [];
 
@@ -48,16 +49,12 @@ trait Singleton
      *
      * @return static The singleton instance
      *
-     * @throws Exception
+     * @api
      */
     final public static function getInstance(mixed ...$args): static
     {
         if (!isset(static::$singleton[static::class])) {
-            try {
+            static::$singleton[static::class] = new static(...$args);
-                static::$singleton[static::class] = new static(...$args);
-            } catch (Exception $exception) {
-                throw $exception;
-            }
         }
         return static::$singleton[static::class];
     }
@@ -66,12 +63,16 @@ trait Singleton
      * This is a singleton class, thus the constructor is private.
      *
      * Usage: Get an instance of this class by calling static::getInstance()
+     *
+     * @return void
      */
     abstract private function __construct();
 
     /**
      * This is a singleton class, thus cloning is prohibited.
      *
+     * @return void
+     *
      * @throws LogicException
      *
      * @internal