From ca19810a56d5a3e9405cf894e0c448f53b8b1cf1 Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Tue, 23 Jan 2024 17:58:33 +0100 Subject: [PATCH] Update PHPDocs --- README.md | 8 +++++-- src/DataStructures/StrictList.php | 26 +++++++++++++++++------ src/DataStructures/StrictQueue.php | 13 ++++++------ src/DataStructures/StrictStack.php | 13 ++++++------ src/ErrorHandlers/ThrowErrorException.php | 19 +++++++++++------ src/InterfaceTraits/ArrayAccess.php | 11 +++++----- src/InterfaceTraits/Countable.php | 11 +++++----- src/InterfaceTraits/Iterator.php | 11 +++++----- src/InterfaceTraits/IteratorAggregate.php | 11 +++++----- src/Traits/Getter.php | 15 ++++++++----- src/Traits/Setter.php | 15 ++++++++----- src/Traits/Singleton.php | 17 +++++++++------ 12 files changed, 105 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 344f125..994df32 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ -# Useful PHP Basics +# PHP Basics + +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. [![PHPStan](https://github.com/opencultureconsulting/php-basics/actions/workflows/phpstan.yml/badge.svg)](https://github.com/opencultureconsulting/php-basics/actions/workflows/phpstan.yml) [![PHPMD](https://github.com/opencultureconsulting/php-basics/actions/workflows/phpmd.yml/badge.svg)](https://github.com/opencultureconsulting/php-basics/actions/workflows/phpmd.yml) -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. +## Usage + +The most convenient way to use the PHP Basics classes and traits in your own project is `composer require opencultureconsulting/basics` diff --git a/src/DataStructures/StrictList.php b/src/DataStructures/StrictList.php index a700a13..d954ae6 100644 --- a/src/DataStructures/StrictList.php +++ b/src/DataStructures/StrictList.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -27,14 +28,17 @@ use SplDoublyLinkedList; use OCC\Basics\Traits\Getter; /** - * A type-sensitive, taversable List. + * A type-sensitive, taversable list. + * + * Extends [\SplDoublyLinkedList](https://www.php.net/spldoublylinkedlist) with + * an option to specify the allowed data types for list items. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\DataStructures * * @property-read string[] $allowedTypes * - * @template AllowedType + * @template AllowedType of mixed * @extends SplDoublyLinkedList */ class StrictList extends SplDoublyLinkedList @@ -147,6 +151,8 @@ class StrictList extends SplDoublyLinkedList * @see Getter * * @return string[] The list of allowed item types + * + * @internal */ protected function magicGetAllowedTypes(): array { @@ -297,6 +303,8 @@ class StrictList extends SplDoublyLinkedList * Get debug information for $this. * * @return mixed[] Array of debug information + * + * @internal */ public function __debugInfo(): array { @@ -307,6 +315,8 @@ class StrictList extends SplDoublyLinkedList * Get array representation of $this. * * @return mixed[] Array representation + * + * @internal */ public function __serialize(): array { @@ -323,6 +333,8 @@ class StrictList extends SplDoublyLinkedList * @param mixed[] $data Array representation * * @return void + * + * @internal */ public function __unserialize(array $data): void { diff --git a/src/DataStructures/StrictQueue.php b/src/DataStructures/StrictQueue.php index 7e668c7..187f987 100644 --- a/src/DataStructures/StrictQueue.php +++ b/src/DataStructures/StrictQueue.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -28,11 +29,11 @@ use RuntimeException; * A type-sensitive, taversable First In, First Out Queue (FIFO). * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\DataStructures * * @property-read string[] $allowedTypes * - * @template AllowedType + * @template AllowedType of mixed * @extends StrictList */ class StrictQueue extends StrictList diff --git a/src/DataStructures/StrictStack.php b/src/DataStructures/StrictStack.php index aab6dd0..75be95b 100644 --- a/src/DataStructures/StrictStack.php +++ b/src/DataStructures/StrictStack.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -28,11 +29,11 @@ use RuntimeException; * A type-sensitive, taversable Last In, First Out Stack (LIFO). * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\DataStructures * * @property-read string[] $allowedTypes * - * @template AllowedType + * @template AllowedType of mixed * @extends StrictList */ class StrictStack extends StrictList diff --git a/src/ErrorHandlers/ThrowErrorException.php b/src/ErrorHandlers/ThrowErrorException.php index 381ac3f..04bd338 100644 --- a/src/ErrorHandlers/ThrowErrorException.php +++ b/src/ErrorHandlers/ThrowErrorException.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -30,7 +31,7 @@ use ErrorException; * Usage: set_error_handler(new ThrowErrorException()); * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\ErrorHandlers */ class ThrowErrorException { @@ -46,8 +47,12 @@ class ThrowErrorException * * @throws ErrorException */ - public function __invoke(int $errno = E_USER_ERROR, string $errstr = '', ?string $errfile = null, ?int $errline = null): bool - { + public function __invoke( + int $errno = E_USER_ERROR, + string $errstr = '', + ?string $errfile = null, + ?int $errline = null + ): bool { if ((error_reporting() & $errno) > 0) { throw new ErrorException($errstr, 0, $errno, $errfile, $errline); } diff --git a/src/InterfaceTraits/ArrayAccess.php b/src/InterfaceTraits/ArrayAccess.php index 4dc26f0..02a60dc 100644 --- a/src/InterfaceTraits/ArrayAccess.php +++ b/src/InterfaceTraits/ArrayAccess.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits; * A generic implementation of the ArrayAccess interface. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\InterfaceTraits * * @phpstan-require-implements \ArrayAccess */ diff --git a/src/InterfaceTraits/Countable.php b/src/InterfaceTraits/Countable.php index ce7e2c3..fdfc231 100644 --- a/src/InterfaceTraits/Countable.php +++ b/src/InterfaceTraits/Countable.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits; * A generic implementation of the Countable interface. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\InterfaceTraits * * @phpstan-require-implements \Countable */ diff --git a/src/InterfaceTraits/Iterator.php b/src/InterfaceTraits/Iterator.php index 20519bd..665c478 100644 --- a/src/InterfaceTraits/Iterator.php +++ b/src/InterfaceTraits/Iterator.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits; * A generic implementation of the Iterator interface. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\InterfaceTraits * * @phpstan-require-implements \Iterator */ diff --git a/src/InterfaceTraits/IteratorAggregate.php b/src/InterfaceTraits/IteratorAggregate.php index 8064ba4..9578a6b 100644 --- a/src/InterfaceTraits/IteratorAggregate.php +++ b/src/InterfaceTraits/IteratorAggregate.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -28,7 +29,7 @@ use ArrayIterator; * A generic implementation of the IteratorAggregate interface. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\InterfaceTraits * * @phpstan-require-implements \IteratorAggregate */ diff --git a/src/Traits/Getter.php b/src/Traits/Getter.php index e4df8a1..d44013c 100644 --- a/src/Traits/Getter.php +++ b/src/Traits/Getter.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -28,7 +29,7 @@ use InvalidArgumentException; * Reads data from inaccessible properties by using magic methods. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\Traits */ trait Getter { @@ -40,6 +41,8 @@ trait Getter * @return mixed The class property's current value * * @throws InvalidArgumentException + * + * @internal */ public function __get(string $property): mixed { @@ -66,6 +69,8 @@ trait Getter * @param string $property The class property to check * * @return bool Whether the class property is set and not empty + * + * @internal */ public function __isset(string $property): bool { diff --git a/src/Traits/Setter.php b/src/Traits/Setter.php index 933fc31..a44cd5e 100644 --- a/src/Traits/Setter.php +++ b/src/Traits/Setter.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -28,7 +29,7 @@ use InvalidArgumentException; * Writes data to inaccessible properties by using magic methods. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\Traits */ trait Setter { @@ -41,6 +42,8 @@ trait Setter * @return void * * @throws InvalidArgumentException + * + * @internal */ public function __set(string $property, mixed $value): void { @@ -69,6 +72,8 @@ trait Setter * @return void * * @throws InvalidArgumentException + * + * @internal */ public function __unset(string $property): void { diff --git a/src/Traits/Singleton.php b/src/Traits/Singleton.php index 1157a32..9ce5b30 100644 --- a/src/Traits/Singleton.php +++ b/src/Traits/Singleton.php @@ -1,8 +1,9 @@ + * PHP Basics + * + * Copyright (C) 2024 Sebastian Meyer * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -11,11 +12,11 @@ * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License - * along with this program. If not, see . + * along with this program. If not, see . */ declare(strict_types=1); @@ -29,12 +30,12 @@ use LogicException; * Allows just a single instance of the class using this trait. * * @author Sebastian Meyer - * @package opencultureconsulting/basics + * @package Basics\Traits */ trait Singleton { /** - * Holds the singleton instances. + * Holds the singleton instance. * * @var array */ @@ -64,7 +65,7 @@ trait Singleton /** * This is a singleton class, thus the constructor is private. * - * Usage: Get an instance of this class by calling getInstance() + * Usage: Get an instance of this class by calling static::getInstance() */ abstract private function __construct(); @@ -72,6 +73,8 @@ trait Singleton * This is a singleton class, thus cloning is prohibited. * * @throws LogicException + * + * @internal */ final public function __clone(): void {