Update PHPDocs

This commit is contained in:
Sebastian Meyer 2024-01-23 17:58:33 +01:00
parent 9832946b35
commit ca19810a56
12 changed files with 105 additions and 65 deletions

View File

@ -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`

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
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 <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\DataStructures
*
* @property-read string[] $allowedTypes
*
* @template AllowedType
* @template AllowedType of mixed
* @extends SplDoublyLinkedList<AllowedType>
*/
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
{

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -28,11 +29,11 @@ use RuntimeException;
* A type-sensitive, taversable First In, First Out Queue (FIFO).
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\DataStructures
*
* @property-read string[] $allowedTypes
*
* @template AllowedType
* @template AllowedType of mixed
* @extends StrictList<AllowedType>
*/
class StrictQueue extends StrictList

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -28,11 +29,11 @@ use RuntimeException;
* A type-sensitive, taversable Last In, First Out Stack (LIFO).
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\DataStructures
*
* @property-read string[] $allowedTypes
*
* @template AllowedType
* @template AllowedType of mixed
* @extends StrictList<AllowedType>
*/
class StrictStack extends StrictList

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -30,7 +31,7 @@ use ErrorException;
* Usage: set_error_handler(new ThrowErrorException());
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @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);
}

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits;
* A generic implementation of the ArrayAccess interface.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\InterfaceTraits
*
* @phpstan-require-implements \ArrayAccess
*/

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits;
* A generic implementation of the Countable interface.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\InterfaceTraits
*
* @phpstan-require-implements \Countable
*/

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -26,7 +27,7 @@ namespace OCC\Basics\InterfaceTraits;
* A generic implementation of the Iterator interface.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\InterfaceTraits
*
* @phpstan-require-implements \Iterator
*/

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -28,7 +29,7 @@ use ArrayIterator;
* A generic implementation of the IteratorAggregate interface.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\InterfaceTraits
*
* @phpstan-require-implements \IteratorAggregate
*/

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -28,7 +29,7 @@ use InvalidArgumentException;
* Reads data from inaccessible properties by using magic methods.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @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
{

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -28,7 +29,7 @@ use InvalidArgumentException;
* Writes data to inaccessible properties by using magic methods.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @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
{

View File

@ -1,8 +1,9 @@
<?php
/**
* Useful PHP Basics
* Copyright (C) 2023 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* PHP Basics
*
* Copyright (C) 2024 Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
*
* 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 <http://www.gnu.org/licenses/>.
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
declare(strict_types=1);
@ -29,12 +30,12 @@ use LogicException;
* Allows just a single instance of the class using this trait.
*
* @author Sebastian Meyer <sebastian.meyer@opencultureconsulting.com>
* @package opencultureconsulting/basics
* @package Basics\Traits
*/
trait Singleton
{
/**
* Holds the singleton instances.
* Holds the singleton instance.
*
* @var array<static>
*/
@ -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
{