From 9cb46b493564d2ea19ba9b3fd055d10ba7aab15b Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Mon, 6 Nov 2023 17:54:14 +0100 Subject: [PATCH] Move project to php-basics --- README.md | 4 +- composer.json | 14 ++--- src/{Traits => DataStructures}/Queue.php | 80 ++++++++++++++---------- src/Traits/Getter.php | 14 +++-- src/Traits/Setter.php | 16 ++--- src/Traits/Singleton.php | 10 +-- 6 files changed, 79 insertions(+), 59 deletions(-) rename src/{Traits => DataStructures}/Queue.php (74%) diff --git a/README.md b/README.md index 27de232..cfe77cc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,3 @@ -# Useful PHP Traits +# Useful PHP Basics -This is a collection of useful [Traits](https://www.php.net/manual/en/language.oop5.traits.php) for your PHP projects. +This is a collection of generic [Classes](https://www.php.net/manual/en/language.oop5.php) and useful [Traits](https://www.php.net/manual/en/language.oop5.traits.php) for your PHP projects. diff --git a/composer.json b/composer.json index 8cd77a6..da9a9a5 100644 --- a/composer.json +++ b/composer.json @@ -1,6 +1,6 @@ { - "name": "opencultureconsulting/traits", - "description": "This is a collection of useful traits for PHP projects.", + "name": "opencultureconsulting/basics", + "description": "This is a collection of generic Classes and useful Traits for PHP projects.", "type": "library", "keywords": [ "trait", @@ -9,7 +9,7 @@ "singleton", "queue" ], - "homepage": "https://github.com/opencultureconsulting/php-traits", + "homepage": "https://github.com/opencultureconsulting/php-basics", "readme": "README.md", "license": "GPL-3.0-or-later", "authors": [ @@ -21,16 +21,16 @@ } ], "support": { - "issues": "https://github.com/opencultureconsulting/php-traits/issues", - "source": "https://github.com/opencultureconsulting/php-traits", - "docs": "https://github.com/opencultureconsulting/php-traits/blob/main/README.md" + "issues": "https://github.com/opencultureconsulting/php-basics/issues", + "source": "https://github.com/opencultureconsulting/php-basics", + "docs": "https://github.com/opencultureconsulting/php-basics/blob/main/README.md" }, "require": { "php": "^8.0" }, "autoload": { "psr-4": { - "OCC\\Traits\\": "src/Traits/" + "OCC\\Basics\\": "src/" } } } diff --git a/src/Traits/Queue.php b/src/DataStructures/Queue.php similarity index 74% rename from src/Traits/Queue.php rename to src/DataStructures/Queue.php index beecc5b..bc98916 100644 --- a/src/Traits/Queue.php +++ b/src/DataStructures/Queue.php @@ -1,7 +1,7 @@ * * This program is free software: you can redistribute it and/or modify @@ -20,18 +20,26 @@ declare(strict_types=1); -namespace OCC\Traits; +namespace OCC\Basics\DataStructures; + +use ArrayAccess; +use Countable; +use InvalidArgumentException; +use OCC\Basics\Traits\Getter; +use OutOfBoundsException; +use OutOfRangeException; +use SeekableIterator; /** - * Handles a queue of items - optionally type-sensitive. + * Handles an ordered queue of items - optionally type-sensitive. * * @author Sebastian Meyer - * @package opencultureconsulting/traits - * @implements \ArrayAccess - * @implements \Countable - * @implements \SeekableIterator + * @package opencultureconsulting/basics + * @implements ArrayAccess + * @implements Countable + * @implements SeekableIterator */ -trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ +class Queue implements ArrayAccess, Countable, SeekableIterator { use Getter; @@ -95,12 +103,12 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Checks if a given index is in the range of valid indexes. * - * @param int $offset The index to check + * @param mixed $offset The index to check * @param bool $allowAppend Should the next free index be valid as well? * * @return bool Whether the given index is in valid range */ - protected function isIndexInRange(int $offset, bool $allowAppend = false): bool + protected function isIndexInRange(mixed $offset, bool $allowAppend = false): bool { $options = [ 'options' => [ @@ -113,7 +121,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Check if a given index exists on the queue. - * @see \ArrayAccess::offsetExists + * @see ArrayAccess::offsetExists * * @param int $offset The queue's index to check * @@ -126,7 +134,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Get the element with given index from the queue. - * @see \ArrayAccess::offsetGet + * @see ArrayAccess::offsetGet * * @param int $offset The queue's index to get * @@ -139,33 +147,34 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Set the element at given index in the queue. - * @see \ArrayAccess::offsetSet + * @see ArrayAccess::offsetSet * * @param ?int $offset The queue's index to set or NULL to append - * Must be between 0 and the length of the queue + * Must be between 0 and the length of the queue. * @param mixed $value The element to set at the given index + * Must be of an allowed type if applicable. * * @return void * - * @throws \InvalidArgumentException - * @throws \OutOfRangeException + * @throws InvalidArgumentException + * @throws OutOfRangeException */ public function offsetSet(mixed $offset, mixed $value): void { if (is_null($offset)) { $offset = count($this->queue); } elseif (!$this->isIndexInRange($offset, true)) { - throw new \OutOfRangeException('Invalid index to set: ' . $offset); + throw new OutOfRangeException('Index must be an integer between 0 and the length of the queue (' . count($this->queue) . ') or NULL to append: ' . get_debug_type($offset) . (is_int($offset) ? ' ' . (string) $offset : '') . ' given.'); } if (!$this->isAllowedType($value)) { - throw new \InvalidArgumentException('Invalid type of value: ' . gettype($value)); + throw new InvalidArgumentException('Value must be one of ' . implode(', ', $this->allowedTypes) . ': ' . get_debug_type($value) . ' given.'); } - $this->queue[$offset] = $value; + $this->queue[(int) $offset] = $value; } /** * Remove the element with given index from the queue. - * @see \ArrayAccess::offsetUnset + * @see ArrayAccess::offsetUnset * * @param int $offset The queue's index to unset * @@ -174,8 +183,8 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ public function offsetUnset(mixed $offset): void { if ($this->isIndexInRange($offset)) { - array_splice($this->queue, $offset, 1, []); - if ($offset <= $this->index) { + array_splice($this->queue, (int) $offset, 1); + if ((int) $offset <= $this->index) { --$this->index; } } @@ -183,7 +192,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Get the number of elements in the queue. - * @see \Countable::count + * @see Countable::count * * @return int The number of items in the queue */ @@ -194,7 +203,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Get the current element from the queue. - * @see \Iterator::current + * @see Iterator::current * * @return mixed|null The queue's current element or NULL */ @@ -205,7 +214,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Get the current index from the queue. - * @see \Iterator::key + * @see Iterator::key * * @return int The queue's current index */ @@ -216,7 +225,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Move the index to next element of the queue. - * @see \Iterator::next + * @see Iterator::next * * @return void */ @@ -227,7 +236,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Reset the index to the first element of the queue. - * @see \Iterator::rewind + * @see Iterator::rewind * * @return void */ @@ -238,7 +247,7 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Check if the queue's current index is valid. - * @see \Iterator::valid + * @see Iterator::valid * * @return bool Whether the queue's current index is valid */ @@ -249,25 +258,25 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Sets the queue's current index. - * @see \SeekableIterator::seek + * @see SeekableIterator::seek * * @param int $offset The queue's new index * * @return void * - * @throws \OutOfBoundsException + * @throws OutOfBoundsException */ public function seek(int $offset): void { if (!$this->isIndexInRange($offset)) { - throw new \OutOfBoundsException('Invalid index to seek: ' . $offset); + throw new OutOfBoundsException('Index must be an integer between 0 and the length of the queue (' . count($this->queue) . '): ' . (string) $offset . ' given.'); } $this->index = $offset; } /** * Magic getter method for $this->allowedTypes. - * @see \OCC\Traits\Getter + * @see OCC\Traits\Getter * * @return array The list of the queue's allowed element types */ @@ -278,12 +287,17 @@ trait Queue /* implements \ArrayAccess, \Countable, \SeekableIterator */ /** * Create a (type-sensitive) queue of elements. - * @see \OCC\Traits\Queue::allowedTypes + * @see OCC\Helper\Queue::allowedTypes * * @param string[] $allowedTypes Allowed types of queue's elements + * + * @throws InvalidArgumentException */ public function __construct(array $allowedTypes = []) { + if (array_sum(array_map('is_string', $allowedTypes)) !== count($allowedTypes)) { + throw new InvalidArgumentException('Parameter 1 must be array of strings or empty array.'); + } $this->allowedTypes = $allowedTypes; } } diff --git a/src/Traits/Getter.php b/src/Traits/Getter.php index 961a1d8..184d568 100644 --- a/src/Traits/Getter.php +++ b/src/Traits/Getter.php @@ -1,7 +1,7 @@ * * This program is free software: you can redistribute it and/or modify @@ -20,13 +20,15 @@ declare(strict_types=1); -namespace OCC\Traits; +namespace OCC\Basics\Traits; + +use InvalidArgumentException; /** * Reads data from inaccessible properties by using magic methods. * * @author Sebastian Meyer - * @package opencultureconsulting/traits + * @package opencultureconsulting/basics */ trait Getter { @@ -37,7 +39,7 @@ trait Getter * * @return mixed The class property's current value * - * @throws \InvalidArgumentException + * @throws InvalidArgumentException */ public function __get(string $property): mixed { @@ -48,7 +50,7 @@ trait Getter ) { return $this->$method(); } else { - throw new \InvalidArgumentException('Invalid property or missing getter method for property "' . get_called_class() . '->' . $property . '".'); + throw new InvalidArgumentException('Invalid property or missing getter method for property: ' . get_called_class() . '->' . $property . '.'); } } @@ -63,7 +65,7 @@ trait Getter { try { $value = $this->__get($property); - } catch (\InvalidArgumentException) { + } catch (InvalidArgumentException) { $value = null; } finally { return !empty($value); diff --git a/src/Traits/Setter.php b/src/Traits/Setter.php index 1d24284..a1d8734 100644 --- a/src/Traits/Setter.php +++ b/src/Traits/Setter.php @@ -1,7 +1,7 @@ * * This program is free software: you can redistribute it and/or modify @@ -20,13 +20,15 @@ declare(strict_types=1); -namespace OCC\Traits; +namespace OCC\Basics\Traits; + +use InvalidArgumentException; /** * Writes data to inaccessible properties by using magic methods. * * @author Sebastian Meyer - * @package opencultureconsulting/traits + * @package opencultureconsulting/basics */ trait Setter { @@ -38,7 +40,7 @@ trait Setter * * @return void * - * @throws \InvalidArgumentException + * @throws InvalidArgumentException */ public function __set(string $property, mixed $value): void { @@ -49,7 +51,7 @@ trait Setter ) { $this->$method($value); } else { - throw new \InvalidArgumentException('Invalid property or missing setter method for property "' . get_called_class() . '->' . $property . '".'); + throw new InvalidArgumentException('Invalid property or missing setter method for property: ' . get_called_class() . '->' . $property . '.'); } } @@ -60,12 +62,12 @@ trait Setter * * @return void * - * @throws \InvalidArgumentException + * @throws InvalidArgumentException */ public function __unset(string $property): void { try { $this->__set($property, null); - } catch (\InvalidArgumentException) {} + } catch (InvalidArgumentException) {} } } diff --git a/src/Traits/Singleton.php b/src/Traits/Singleton.php index 709edd5..8946263 100644 --- a/src/Traits/Singleton.php +++ b/src/Traits/Singleton.php @@ -1,7 +1,7 @@ * * This program is free software: you can redistribute it and/or modify @@ -20,13 +20,15 @@ declare(strict_types=1); -namespace OCC\Traits; +namespace OCC\Basics\Traits; + +use ReflectionClass; /** * Allows just a single instance of the class using this trait. * * @author Sebastian Meyer - * @package opencultureconsulting/traits + * @package opencultureconsulting/basics */ trait Singleton { @@ -41,7 +43,7 @@ trait Singleton public static function getInstance(): self { if (!isset(static::$singleton)) { - $reflectionClass = new \ReflectionClass(get_called_class()); + $reflectionClass = new ReflectionClass(get_called_class()); static::$singleton = $reflectionClass->newInstanceArgs(func_get_args()); } return static::$singleton;