diff --git a/.phpdoc/template/base.html.twig b/.phpdoc/template/base.html.twig index 926c30b..6d84720 100644 --- a/.phpdoc/template/base.html.twig +++ b/.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"} diff --git a/.phpdoc/template/components/sidebar.html.twig b/.phpdoc/template/components/sidebar.html.twig new file mode 100644 index 0000000..1e60bee --- /dev/null +++ b/.phpdoc/template/components/sidebar.html.twig @@ -0,0 +1,31 @@ + + + diff --git a/phpdoc.dist.xml b/phpdoc.dist.xml index d0807e9..b40c56a 100644 --- a/phpdoc.dist.xml +++ b/phpdoc.dist.xml @@ -26,14 +26,14 @@ psalm-suppress - + /.phpdoc/guide guides - + diff --git a/psalm.xml b/psalm.xml index 4e9d307..606f492 100644 --- a/psalm.xml +++ b/psalm.xml @@ -6,7 +6,8 @@ errorLevel="1" resolveFromConfigFile="true" findUnusedBaselineEntry="true" - findUnusedCode="false" + findUnusedCode="true" + findUnusedVariablesAndParams="true" > diff --git a/src/DataStructures/StrictList.php b/src/DataStructures/StrictList.php index 3e9c29f..c3d19f0 100644 --- a/src/DataStructures/StrictList.php +++ b/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). - */ - 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. + * The allowed data types for list 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(); - } - - /** - * Get current list value. - * - * @return AllowedType The current value - * - * @api - */ - public function current(): mixed - { - return parent::current(); + return $this->allowedTypes; } /** @@ -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; - } - - /** - * 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); + return $this->getAllowedTypes(); } /** @@ -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. * diff --git a/src/DataStructures/StrictQueue.php b/src/DataStructures/StrictQueue.php index 5671087..a4758cf 100644 --- a/src/DataStructures/StrictQueue.php +++ b/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 { diff --git a/src/DataStructures/StrictStack.php b/src/DataStructures/StrictStack.php index 1ec41f0..afaf3b5 100644 --- a/src/DataStructures/StrictStack.php +++ b/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 { diff --git a/src/InterfaceTraits/ArrayAccessTrait.php b/src/InterfaceTraits/ArrayAccessTrait.php index c7010d9..ee4434b 100644 --- a/src/InterfaceTraits/ArrayAccessTrait.php +++ b/src/InterfaceTraits/ArrayAccessTrait.php @@ -33,6 +33,7 @@ use ArrayAccess; * * @template TKey of int|string * @template TValue of mixed + * @template TData of array * @implements ArrayAccess * @phpstan-require-implements ArrayAccess */ @@ -41,7 +42,7 @@ trait ArrayAccessTrait /** * Holds the array-accessible data. * - * @var array + * @var TData */ protected array $data = []; diff --git a/src/InterfaceTraits/CountableTrait.php b/src/InterfaceTraits/CountableTrait.php index 1e30352..b879aba 100644 --- a/src/InterfaceTraits/CountableTrait.php +++ b/src/InterfaceTraits/CountableTrait.php @@ -33,6 +33,7 @@ use Countable; * * @template TKey of int|string * @template TValue of mixed + * @template TData of array * @implements Countable * @phpstan-require-implements Countable */ @@ -41,7 +42,7 @@ trait CountableTrait /** * Holds the countable data. * - * @var array + * @var TData */ protected array $data = []; diff --git a/src/InterfaceTraits/IteratorAggregateTrait.php b/src/InterfaceTraits/IteratorAggregateTrait.php index 7a7ed58..dc97252 100644 --- a/src/InterfaceTraits/IteratorAggregateTrait.php +++ b/src/InterfaceTraits/IteratorAggregateTrait.php @@ -34,6 +34,7 @@ use IteratorAggregate; * * @template TKey of int|string * @template TValue of mixed + * @template TData of array * @implements IteratorAggregate * @phpstan-require-implements IteratorAggregate */ @@ -42,7 +43,7 @@ trait IteratorAggregateTrait /** * Holds the iterable data. * - * @var array + * @var TData */ protected array $data = []; diff --git a/src/InterfaceTraits/IteratorTrait.php b/src/InterfaceTraits/IteratorTrait.php index d93099d..52bbd9e 100644 --- a/src/InterfaceTraits/IteratorTrait.php +++ b/src/InterfaceTraits/IteratorTrait.php @@ -33,6 +33,7 @@ use Iterator; * * @template TKey of int|string * @template TValue of mixed + * @template TData of array * @implements Iterator * @phpstan-require-implements Iterator */ @@ -41,7 +42,7 @@ trait IteratorTrait /** * Holds the iterable data. * - * @var array + * @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. * diff --git a/src/Traits/Singleton.php b/src/Traits/Singleton.php index c6358d5..80b5abe 100644 --- a/src/Traits/Singleton.php +++ b/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 + * + * @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); - } catch (Exception $exception) { - throw $exception; - } + static::$singleton[static::class] = new static(...$args); } 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