sebastian-meyer
/
php-basics
mirror of https://github.com/opencultureconsulting/php-basics.git
2
0
Fork 0
Code Issues

Update documentation

This commit is contained in:
Sebastian Meyer 2024-03-31 17:41:04 +02:00
parent 1c1c3c49ad
commit 3670945f3e
16 changed files with 533 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
.phpdoc/guide/changelog.rst
View File

@ -21,18 +21,18 @@ v2.0.0
OCC\Basics\InterfaceTraits\IteratorAggregate -> OCC\Basics\Interfaces\IteratorAggregateTrait
OCC\Basics\InterfaceTraits\Iterator -> OCC\Basics\Interfaces\IteratorTrait
* Renamed internal methods for :php:trait:`OCC\Basics\Traits\Getter` and :php:trait:`OCC\Basics\Traits\Setter` to avoid
confusion with regular class methods
* Prefixed internal methods for :php:trait:`OCC\Basics\Traits\Getter` and :php:trait:`OCC\Basics\Traits\Setter` with
`_` to avoid confusion with regular class methods
.. code-block:: php
// old methods
function magicGet{PascalCasePropertyName}(): mixed
function magicSet{PascalCasePropertyName}(mixed $value): void
function magicGet{Property}(): mixed
function magicSet{Property}(mixed $value): void
.. code-block:: php
// new methods
function _magicGet{PascalCasePropertyName}(): mixed
function _magicSet{PascalCasePropertyName}(mixed $value): void
function _magicGet{Property}(): mixed
function _magicSet{Property}(mixed $value): void
**New Features:**

41
.phpdoc/guide/overview/datastructures.rst
View File

@ -20,7 +20,7 @@ Trying to add an item with a data type not on the list of allowed types to a str
All strict datastructures inherit the implementation of the `\ArrayAccess <https://www.php.net/arrayaccess>`_,
`\Countable <https://www.php.net/countable>`_ and `\Serializable <https://www.php.net/serializable>`_ interfaces. All
but `StrictCollection` also implement the `\Traversable <https://www.php.net/traversable>`_ interface.
but `StrictCollection` also implement a `\Traversable <https://www.php.net/traversable>`_ interface.
Examples:
@ -28,56 +28,57 @@ but `StrictCollection` also implement the `\Traversable <https://www.php.net/tra
// create a collection of strings
$stringCollection = new StrictCollection(['string']);
.. code-block:: php
// create a queue of PSR-15 middlewares
$middlewareQueue = new StrictQueue(['Psr\Http\Server\MiddlewareInterface']);
StrictCollection
================
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\DataStructures\StrictCollection`
StrictCollection
================
*A type-sensitive, unsorted collection of items.*
Holds items as key/value pairs where keys identify the items and have to be valid array keys while values can be of any
controlled type. The collection can be accessed like an array, but not traversed because it has no particular order.
.. note::
Internally it holds the items in the `$_data` array, the same as most :php:namespace:`OCC\Basics\Interfaces` and
:php:namespace:`OCC\Basics\Traits` of this package.
StrictArray
================
Internally it holds the items in the `$_data` array, the same as most :doc:`interfaces` and :doc:`traits` of this
package.
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\DataStructures\StrictArray`
StrictArray
================
*A type-sensitive, traversable array of items.*
Holds items as key/value pairs where keys identify the items and have to be valid array keys while values can be of any
controlled type. The array can be accessed and traversed just like any other array.
.. note::
Internally it holds the items in the `$_data` array, the same as most :php:namespace:`OCC\Basics\Interfaces` and
:php:namespace:`OCC\Basics\Traits` of this package.
StrictList
==========
Internally it holds the items in the `$_data` array, the same as most :doc:`interfaces` and :doc:`traits` of this
package.
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\DataStructures\StrictList`
StrictList
==========
*A type-sensitive, taversable list of items.*
Extends `\SplDoublyLinkedList <https://www.php.net/spldoublylinkedlist>`_ with an option to restrict the allowed data
types for list items. The list can be accessed and traversed like an array, but has only consecutive numerical keys.
StrictQueue
===========
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\DataStructures\StrictQueue`
StrictQueue
===========
*A type-sensitive, taversable queue (FIFO) of items.*
Extends `\SplQueue <https://www.php.net/splqueue>`_ with an option to restrict the allowed data types for queue items.
@ -87,12 +88,12 @@ first-in, first-out (FIFO) principle meaning that items are returned in the same
It is recommended to use the `StrictQueue::enqueue()` and `StrictQueue::dequeue()` alias methods when working with a
queue, because those will ensure proper FIFO behavior and remove items while traversing.
StrictStack
===========
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\DataStructures\StrictStack`
StrictStack
===========
*A type-sensitive, taversable stack (LIFO) of items.*
Extends `\SplStack <https://www.php.net/splstack>`_ with an option to restrict the allowed data types for stack items.

34
.phpdoc/guide/overview/errorhandlers.rst
View File

@ -3,25 +3,39 @@
Error and Exception Handlers
############################
.. sidebar:: Table of Contents
.. contents::
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\ErrorHandlers\ThrowErrorException`
ThrowErrorException
===================
Throws internal errors as exceptions.
*Throws internal errors as exceptions.*
If registered as error handler, this converts an internal PHP error into an
`ErrorException`. It respects the `error_reporting` directive.
If registered as error handler, this handles an internal PHP error by converting it into an `\ErrorException
<https://www.php.net/errorexception>`_. It respects the `error_reporting <https://www.php.net/error_reporting>`_
directive by only throwing an exception if the severity of the internal error is the same or higher than the setting.
> Usage: `set_error_handler(new ThrowErrorException());`
Usage:
.. code-block:: php
set_error_handler(new ThrowErrorException());
.. caution::
By design user-defined error handlers can't handle errors of severity `E_ERROR`, `E_PARSE`, `E_CORE_ERROR`,
`E_CORE_WARNING`, `E_COMPILE_ERROR`, `E_COMPILE_WARNING` and most of `E_STRICT`.
.. sidebar:: API Documentation
* :php:class:`OCC\Basics\ErrorHandlers\TriggerExceptionError`
TriggerExceptionError
=====================
Triggers errors for uncaught exceptions.
*Triggers errors for uncaught exceptions.*
If registered as exception handler, this catches an uncaught exception and
converts it into an internal PHP error of severity `E_USER_ERROR`.
If registered as exception handler, this catches an uncaught exception and converts it into an internal PHP error of
severity `E_USER_ERROR`.
> Usage: `set_exception_handler(new TriggerExceptionError());`
Usage:
.. code-block:: php
set_exception_handler(new TriggerExceptionError());

71
.phpdoc/guide/overview/interfaces.rst
View File

@ -6,30 +6,85 @@ Interface Traits
.. sidebar:: Table of Contents
.. contents::
This package contains some traits implementing common interfaces, which can easily be used in any class that internally
uses an array for holding its properties or data. They also share the same internal logic to allow combining multiple
traits within the same class.
.. note::
Internally all interface traits use the `$_data` array, the same as some :doc:`datastructures` and :doc:`traits` of
this package.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Interfaces\ArrayAccessTrait`
ArrayAccessTrait
================
A generic implementation of the ArrayAccess interface.
*A generic implementation of the ArrayAccess interface.*
Internally it accesses the protected `$_data` array.
The `\ArrayAccess <https://www.php.net/arrayaccess>`_ interface allows objects to be accessed like arrays.
Usage:
.. code-block:: php
class Foo implements ArrayAccess
{
use \OCC\Basics\Interfaces\ArrayAccessTrait;
}
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Interfaces\CountableTrait`
CountableTrait
==============
A generic implementation of the Countable interface.
*A generic implementation of the Countable interface.*
Internally it counts the values of the protected `$_data` array.
The `\Countable <https://www.php.net/countable>`_ interface allows objects to be used with the `count()
<https://www.php.net/count>`_ function.
Usage:
.. code-block:: php
class Foo implements Countable
{
use \OCC\Basics\Interfaces\CountableTrait;
}
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Interfaces\IteratorAggregateTrait`
IteratorAggregateTrait
======================
A generic implementation of the IteratorAggregate interface.
*A generic implementation of the IteratorAggregate interface.*
Internally it iterates over the protected `$_data` array.
The `\IteratorAggregate <https://www.php.net/iteratoraggregate>`_ interface creates an external `\ArrayIterator
<https://www.php.net/arrayiterator>`_ for traversing the object's internal data array.
Usage:
.. code-block:: php
class Foo implements IteratorAggregate
{
use \OCC\Basics\Interfaces\IteratorAggregateTrait;
}
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Interfaces\IteratorTrait`
IteratorTrait
=============
A generic implementation of the Iterator interface.
*A generic implementation of the Iterator interface.*
Internally it iterates over the protected `$_data` array.
The `\Iterator <https://www.php.net/iterator>`_ interface creates an internal iterator for traversing the object's data
array.
Usage:
.. code-block:: php
class Foo implements Iterator
{
use \OCC\Basics\Interfaces\IteratorTrait;
}

125
.phpdoc/guide/overview/traits.rst
View File

@ -6,73 +6,108 @@ Traits
.. sidebar:: Table of Contents
.. contents::
This package provides a number of generic traits like different getter and setter methods, an implementation of the
singleton design pattern and some little helpers. Those traits are too small to justify their own packages and most of them
are dependencies of the :doc:`datastructures` and :doc:`interfaces` anyway.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\Getter`
Getter
======
Reads data from inaccessible properties by using magic methods.
*Reads data from inaccessible properties by using magic methods.*
To make a `protected` or `private` property readable, provide a method named
`_magicGet{Property}()` which handles the reading. Replace `{Property}` in
the method's name with the name of the actual property (with an uppercase
first letter).
To make a `protected` or `private` property readable, provide a method named `_magicGet{Property}()` which handles the
reading. Replace `{Property}` in the method's name with the name of the actual property (with an uppercase first
letter).
> Example: If the property is named `$fooBar`, the "magic" method has to be
> `_magicGetFooBar()`. This method is then called when `$fooBar` is read in
> a context where it normally would not be accessible.
Trying to access an undefined property or a property without corresponding "magic" getter method will result in an
`\InvalidArgumentException <https://www.php.net/invalidargumentexception>`_.
OverloadingGetter
=================
Example: If the property is named `$fooBar`, the "magic" method has to be `_magicGetFooBar()`. This method is then
called when `$fooBar` is read in a context where it normally would not be accessible.
Overloads a class with readable magic properties.
Internally it reads the protected `$_data` array whose keys are interpreted
as property names.
> Example: Reading `Foo->bar` will return the value of `$_data['bar']`.
OverloadingSetter
=================
Overloads a class with writable magic properties.
Internally it writes the protected `$_data` array whose keys are interpreted
as property names.
> Example: `Foo->bar = 42;` will set `$_data['bar']` to `42`.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\Setter`
Setter
======
Writes data to inaccessible properties by using magic methods.
*Writes data to inaccessible properties by using magic methods.*
To make a `protected` or `private` property writable, provide a method named
`_magicSet{Property}()` which handles the writing. Replace `{Property}` in
the method's name with the name of the actual property (with an uppercase
first letter).
To make a `protected` or `private` property writable, provide a method named `_magicSet{Property}()` which handles the
writing. Replace `{Property}` in the method's name with the name of the actual property (with an uppercase first
letter).
> Example: If the property is named `$fooBar`, the "magic" method has to be
> `_magicSetFooBar()`. This method is then called when `$fooBar` is written
> to in a context where it normally would not be accessible.
Trying to access an undefined property or a property without corresponding "magic" setter method will result in an
`\InvalidArgumentException <https://www.php.net/invalidargumentexception>`_.
Example: If the property is named `$fooBar`, the "magic" method has to be `_magicSetFooBar()`. This method is then
called when `$fooBar` is written to in a context where it normally would not be accessible.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\OverloadingGetter`
OverloadingGetter
=================
*Overloads a class with readable virtual properties.*
It reads a protected internal array whose keys are interpreted as property names.
Trying to access an undefined virtual property will not issue any warning or error, but return `NULL` instead.
Example: Reading `Foo->bar` will return the value of `Foo::$_data['bar']`.
.. note::
Internally it uses the `$_data` array, the same as some :doc:`datastructures` and all :doc:`interfaces` of this
package.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\OverloadingSetter`
OverloadingSetter
=================
*Overloads a class with writable virtual properties.*
It writes a protected internal array whose keys are interpreted as property names.
Trying to access a previously undefined virtual property will create a new one with the given name.
Example: `Foo->bar = 42;` will set `Foo::$_data['bar']` to `42`.
.. note::
Internally it uses the `$_data` array, the same as some :doc:`datastructures` and all :doc:`interfaces` of this
package.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\Singleton`
Singleton
=========
Allows just a single instance of the class using this trait.
*Allows just a single instance of the class using this trait.*
Get the singleton by calling the static method `getInstance()`.
Get the singleton by calling the static method `getInstance()`. If there is no object yet, the constructor is called
with the same arguments as `getInstance()`. Any later call will just return the already instantiated object
(irrespective of the given arguments).
If there is no object yet, the constructor is called with the same arguments
as `getInstance()`. Any later call will just return the already instantiated
object (irrespective of the given arguments).
.. caution::
In order for this to work as expected, the constructor has to be implemented as `private` to prevent direct
instantiation of the class.
In order for this to work as expected, the constructor has to be implemented
as `private` to prevent direct instantiation of the class.
.. sidebar:: API Documentation
* :php:trait:`OCC\Basics\Traits\TypeChecker`
TypeChecker
===========
A generic data type checker.
*A generic data type checker.*
This allows to set a list of allowed atomic data types and fully qualified
class names. It also provides a method to check if a value's data type matches
at least one of these types.
This allows to set a list of allowed atomic data types and fully qualified class names. It also provides a method to
check if a value's data type matches at least one of these types.
Available atomic types are `array`, `bool`, `callable`, `countable`, `float` / `double`, `int` / `integer` / `long`,
`iterable`, `null`, `numeric`, `object`, `resource`, `scalar` and `string`.

8
doc/files/src/ErrorHandlers/ThrowErrorException.php.txt
View File

@ -52,12 +52,8 @@ class ThrowErrorException
*
* @throws ErrorException if `error_reporting` is set to report the error
*/
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);
}

2
doc/files/src/Traits/Getter.php.txt
View File

@ -65,7 +65,7 @@ trait Getter
} else {
throw new InvalidArgumentException(
sprintf(
'Invalid property or missing getter method for property: %s->%s.',
'Invalid property or missing getter method for property: %s::$%s.',
static::class,
$property
)

2
doc/files/src/Traits/Setter.php.txt
View File

@ -65,7 +65,7 @@ trait Setter
} else {
throw new InvalidArgumentException(
sprintf(
'Invalid property or missing setter method for property: %s->%s.',
'Invalid property or missing setter method for property: %s::$%s.',
static::class,
$property
)

14
doc/guides/changelog.html
View File

@ -193,14 +193,14 @@ OCC\Basics\InterfaceTraits\Countable -&gt; OCC\Basics\Interfaces\Countab
OCC\Basics\InterfaceTraits\IteratorAggregate -&gt; OCC\Basics\Interfaces\IteratorAggregateTrait
OCC\Basics\InterfaceTraits\Iterator -&gt; OCC\Basics\Interfaces\IteratorTrait</code></pre></li>
<li><p>Renamed internal methods for <a href="classes/OCC-Basics-Traits-Getter.html"><abbr title="\OCC\Basics\Traits\Getter">Getter</abbr></a>
<li><p>Prefixed internal methods for <a href="classes/OCC-Basics-Traits-Getter.html"><abbr title="\OCC\Basics\Traits\Getter">Getter</abbr></a>
and <a href="classes/OCC-Basics-Traits-Setter.html"><abbr title="\OCC\Basics\Traits\Setter">Setter</abbr></a>
to avoid
confusion with regular class methods</p><pre><code class="language-php">// old methods
function magicGet{PascalCasePropertyName}(): mixed
function magicSet{PascalCasePropertyName}(mixed $value): void</code></pre><pre><code class="language-php">// new methods
function _magicGet{PascalCasePropertyName}(): mixed
function _magicSet{PascalCasePropertyName}(mixed $value): void</code></pre></li>
with
<code>_</code> to avoid confusion with regular class methods</p><pre><code class="language-php">// old methods
function magicGet{Property}(): mixed
function magicSet{Property}(mixed $value): void</code></pre><pre><code class="language-php">// new methods
function _magicGet{Property}(): mixed
function _magicSet{Property}(mixed $value): void</code></pre></li>
</ul>

68
doc/guides/overview/datastructures.html
View File

@ -188,16 +188,11 @@ class names you want to allow as item types. Available atomic types are <code>ar
.</p>
<p>All strict datastructures inherit the implementation of the <a href="https://www.php.net/arrayaccess">\ArrayAccess</a>,
<a href="https://www.php.net/countable">\Countable</a> and <a href="https://www.php.net/serializable">\Serializable</a> interfaces. All
but <code>StrictCollection</code> also implement the <a href="https://www.php.net/traversable">\Traversable</a> interface.</p>
but <code>StrictCollection</code> also implement a <a href="https://www.php.net/traversable">\Traversable</a> interface.</p>
<blockquote><p>Examples:</p><pre><code class="language-php">// create a collection of strings
$stringCollection = new StrictCollection([&#039;string&#039;]);
// create a queue of PSR-15 middlewares
$stringCollection = new StrictCollection([&#039;string&#039;]);</code></pre><pre><code class="language-php">// create a queue of PSR-15 middlewares
$middlewareQueue = new StrictQueue([&#039;Psr\Http\Server\MiddlewareInterface&#039;]);</code></pre></blockquote>
<div class="section" id="strictcollection">
<h2>StrictCollection</h2>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
@ -211,24 +206,22 @@ $middlewareQueue = new StrictQueue([&#039;Psr\Http\Server\MiddlewareInterface&#0
</div>
</div>
<div class="section" id="strictcollection">
<h2>StrictCollection</h2>
<p><em>A type-sensitive, unsorted collection of items.</em></p>
<p>Holds items as key/value pairs where keys identify the items and have to be valid array keys while values can be of any
controlled type. The collection can be accessed like an array, but not traversed because it has no particular order.</p>
<div class="phpdocumentor-admonition note">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path></svg>
<article>
<p>Internally it holds the items in the <code>$_data</code> array, the same as most <a href="namespaces/occ-basics-interfaces.html"><abbr title="\OCC\Basics\Interfaces">Interfaces</abbr></a>
and
<a href="namespaces/occ-basics-traits.html"><abbr title="\OCC\Basics\Traits">Traits</abbr></a>
of this package.</p>
<p>Internally it holds the items in the <code>$_data</code> array, the same as most <a href="guides/overview/interfaces.html">Interface Traits</a>
and <a href="guides/overview/traits.html">Traits</a>
of this
package.</p>
</article>
</div>
</div>
<div class="section" id="strictarray">
<h2>StrictArray</h2>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
@ -242,24 +235,24 @@ controlled type. The collection can be accessed like an array, but not traversed
</div>
</div>
</div>
<div class="section" id="strictarray">
<h2>StrictArray</h2>
<p><em>A type-sensitive, traversable array of items.</em></p>
<p>Holds items as key/value pairs where keys identify the items and have to be valid array keys while values can be of any
controlled type. The array can be accessed and traversed just like any other array.</p>
<div class="phpdocumentor-admonition note">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path></svg>
<article>
<p>Internally it holds the items in the <code>$_data</code> array, the same as most <a href="namespaces/occ-basics-interfaces.html"><abbr title="\OCC\Basics\Interfaces">Interfaces</abbr></a>
and
<a href="namespaces/occ-basics-traits.html"><abbr title="\OCC\Basics\Traits">Traits</abbr></a>
of this package.</p>
<p>Internally it holds the items in the <code>$_data</code> array, the same as most <a href="guides/overview/interfaces.html">Interface Traits</a>
and <a href="guides/overview/traits.html">Traits</a>
of this
package.</p>
</article>
</div>
</div>
<div class="section" id="strictlist">
<h2>StrictList</h2>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
@ -273,14 +266,14 @@ controlled type. The array can be accessed and traversed just like any other arr
</div>
</div>
</div>
<div class="section" id="strictlist">
<h2>StrictList</h2>
<p><em>A type-sensitive, taversable list of items.</em></p>
<p>Extends <a href="https://www.php.net/spldoublylinkedlist">\SplDoublyLinkedList</a> with an option to restrict the allowed data
types for list items. The list can be accessed and traversed like an array, but has only consecutive numerical keys.</p>
</div>
<div class="section" id="strictqueue">
<h2>StrictQueue</h2>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
@ -294,17 +287,17 @@ types for list items. The list can be accessed and traversed like an array, but
</div>
</div>
</div>
<div class="section" id="strictqueue">
<h2>StrictQueue</h2>
<p><em>A type-sensitive, taversable queue (FIFO) of items.</em></p>
<p>Extends <a href="https://www.php.net/splqueue">\SplQueue</a> with an option to restrict the allowed data types for queue items.
The queue can be accessed and traversed like an array, but has only consecutive numerical keys. Traversal follows the
first-in, first-out (FIFO) principle meaning that items are returned in the same order they were added to the queue.</p>
<p>It is recommended to use the <code>StrictQueue::enqueue()</code> and <code>StrictQueue::dequeue()</code> alias methods when working with a
queue, because those will ensure proper FIFO behavior and remove items while traversing.</p>
</div>
<div class="section" id="strictstack">
<h2>StrictStack</h2>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
@ -318,6 +311,11 @@ queue, because those will ensure proper FIFO behavior and remove items while tra
</div>
</div>
</div>
<div class="section" id="strictstack">
<h2>StrictStack</h2>
<p><em>A type-sensitive, taversable stack (LIFO) of items.</em></p>
<p>Extends <a href="https://www.php.net/splstack">\SplStack</a> with an option to restrict the allowed data types for stack items.
The stack can be accessed and traversed like an array, but has only consecutive numerical keys. Traversal follows the

50
doc/guides/overview/errorhandlers.html
View File

@ -172,27 +172,57 @@
<h1>Error and Exception Handlers</h1>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">Table of Contents</p>
<div class="contents"><ul class="phpdocumentor-list"><li class="toc-item"><a href="guides/overview/errorhandlers.html#throwerrorexception">ThrowErrorException</a></li><li class="toc-item"><a href="guides/overview/errorhandlers.html#triggerexceptionerror">TriggerExceptionError</a></li></ul></div>
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-ErrorHandlers-ThrowErrorException.html"><abbr title="\OCC\Basics\ErrorHandlers\ThrowErrorException">ThrowErrorException</abbr></a>
</li>
</ul>
</div>
</div>
<div class="section" id="throwerrorexception">
<h2>ThrowErrorException</h2>
<p>Throws internal errors as exceptions.</p>
<p>If registered as error handler, this converts an internal PHP error into an
<code>ErrorException</code>. It respects the <code>error_reporting</code> directive.</p>
<p>&gt; Usage: <code>set_error_handler(new ThrowErrorException());</code></p>
<p><em>Throws internal errors as exceptions.</em></p>
<p>If registered as error handler, this handles an internal PHP error by converting it into an <a href="https://www.php.net/errorexception">\ErrorException</a>. It respects the <a href="https://www.php.net/error_reporting">error_reporting</a>
directive by only throwing an exception if the severity of the internal error is the same or higher than the setting.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">set_error_handler(new ThrowErrorException());</code></pre></blockquote>
<div class="phpdocumentor-admonition caution">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path></svg>
<article>
<p>By design user-defined error handlers can&#039;t handle errors of severity <code>E_ERROR</code>, <code>E_PARSE</code>, <code>E_CORE_ERROR</code>,
<code>E_CORE_WARNING</code>, <code>E_COMPILE_ERROR</code>, <code>E_COMPILE_WARNING</code> and most of <code>E_STRICT</code>.</p>
</article>
</div>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-ErrorHandlers-TriggerExceptionError.html"><abbr title="\OCC\Basics\ErrorHandlers\TriggerExceptionError">TriggerExceptionError</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="triggerexceptionerror">
<h2>TriggerExceptionError</h2>
<p>Triggers errors for uncaught exceptions.</p>
<p>If registered as exception handler, this catches an uncaught exception and
converts it into an internal PHP error of severity <code>E_USER_ERROR</code>.</p>
<p>&gt; Usage: <code>set_exception_handler(new TriggerExceptionError());</code></p>
<p><em>Triggers errors for uncaught exceptions.</em></p>
<p>If registered as exception handler, this catches an uncaught exception and converts it into an internal PHP error of
severity <code>E_USER_ERROR</code>.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">set_exception_handler(new TriggerExceptionError());</code></pre></blockquote>
</div>
</div>

4
doc/guides/overview/index.html
View File

@ -216,12 +216,12 @@ other projects.</p>
<li class="toc-item"><a href="guides/overview/traits.html#traits">Traits</a> <ul class="section-level-1">
<li class="toc-item"><a href="guides/overview/traits.html#getter">Getter</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#setter">Setter</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#overloadinggetter">OverloadingGetter</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#overloadingsetter">OverloadingSetter</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#setter">Setter</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#singleton">Singleton</a></li>
<li class="toc-item"><a href="guides/overview/traits.html#typechecker">TypeChecker</a></li>

102
doc/guides/overview/interfaces.html
View File

@ -177,32 +177,118 @@
</div>
</div>
<p>This package contains some traits implementing common interfaces, which can easily be used in any class that internally
uses an array for holding its properties or data. They also share the same internal logic to allow combining multiple
traits within the same class.</p>
<div class="phpdocumentor-admonition note">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path></svg>
<article>
<p>Internally all interface traits use the <code>$_data</code> array, the same as some <a href="guides/overview/datastructures.html">Typed Datastructures</a>
and <a href="guides/overview/traits.html">Traits</a>
of
this package.</p>
</article>
</div>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Interfaces-ArrayAccessTrait.html"><abbr title="\OCC\Basics\Interfaces\ArrayAccessTrait">ArrayAccessTrait</abbr></a>
</li>
</ul>
</div>
</div>
<div class="section" id="arrayaccesstrait">
<h2>ArrayAccessTrait</h2>
<p>A generic implementation of the ArrayAccess interface.</p>
<p>Internally it accesses the protected <code>$_data</code> array.</p>
<p><em>A generic implementation of the ArrayAccess interface.</em></p>
<p>The <a href="https://www.php.net/arrayaccess">\ArrayAccess</a> interface allows objects to be accessed like arrays.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">class Foo implements ArrayAccess
{
use \OCC\Basics\Interfaces\ArrayAccessTrait;
}</code></pre></blockquote>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Interfaces-CountableTrait.html"><abbr title="\OCC\Basics\Interfaces\CountableTrait">CountableTrait</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="countabletrait">
<h2>CountableTrait</h2>
<p>A generic implementation of the Countable interface.</p>
<p>Internally it counts the values of the protected <code>$_data</code> array.</p>
<p><em>A generic implementation of the Countable interface.</em></p>
<p>The <a href="https://www.php.net/countable">\Countable</a> interface allows objects to be used with the <a href="https://www.php.net/count">count()</a> function.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">class Foo implements Countable
{
use \OCC\Basics\Interfaces\CountableTrait;
}</code></pre></blockquote>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Interfaces-IteratorAggregateTrait.html"><abbr title="\OCC\Basics\Interfaces\IteratorAggregateTrait">IteratorAggregateTrait</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="iteratoraggregatetrait">
<h2>IteratorAggregateTrait</h2>
<p>A generic implementation of the IteratorAggregate interface.</p>
<p>Internally it iterates over the protected <code>$_data</code> array.</p>
<p><em>A generic implementation of the IteratorAggregate interface.</em></p>
<p>The <a href="https://www.php.net/iteratoraggregate">\IteratorAggregate</a> interface creates an external <a href="https://www.php.net/arrayiterator">\ArrayIterator</a> for traversing the object&#039;s internal data array.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">class Foo implements IteratorAggregate
{
use \OCC\Basics\Interfaces\IteratorAggregateTrait;
}</code></pre></blockquote>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Interfaces-IteratorTrait.html"><abbr title="\OCC\Basics\Interfaces\IteratorTrait">IteratorTrait</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="iteratortrait">
<h2>IteratorTrait</h2>
<p>A generic implementation of the Iterator interface.</p>
<p>Internally it iterates over the protected <code>$_data</code> array.</p>
<p><em>A generic implementation of the Iterator interface.</em></p>
<p>The <a href="https://www.php.net/iterator">\Iterator</a> interface creates an internal iterator for traversing the object&#039;s data
array.</p>
<blockquote><p>Usage:</p><pre><code class="language-php">class Foo implements Iterator
{
use \OCC\Basics\Interfaces\IteratorTrait;
}</code></pre></blockquote>
</div>
</div>

201
doc/guides/overview/traits.html
View File

@ -173,73 +173,186 @@
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">Table of Contents</p>
<div class="contents"><ul class="phpdocumentor-list"><li class="toc-item"><a href="guides/overview/traits.html#getter">Getter</a></li><li class="toc-item"><a href="guides/overview/traits.html#overloadinggetter">OverloadingGetter</a></li><li class="toc-item"><a href="guides/overview/traits.html#overloadingsetter">OverloadingSetter</a></li><li class="toc-item"><a href="guides/overview/traits.html#setter">Setter</a></li><li class="toc-item"><a href="guides/overview/traits.html#singleton">Singleton</a></li><li class="toc-item"><a href="guides/overview/traits.html#typechecker">TypeChecker</a></li></ul></div>
<div class="contents"><ul class="phpdocumentor-list"><li class="toc-item"><a href="guides/overview/traits.html#getter">Getter</a></li><li class="toc-item"><a href="guides/overview/traits.html#setter">Setter</a></li><li class="toc-item"><a href="guides/overview/traits.html#overloadinggetter">OverloadingGetter</a></li><li class="toc-item"><a href="guides/overview/traits.html#overloadingsetter">OverloadingSetter</a></li><li class="toc-item"><a href="guides/overview/traits.html#singleton">Singleton</a></li><li class="toc-item"><a href="guides/overview/traits.html#typechecker">TypeChecker</a></li></ul></div>
</div>
</div>
<p>This package provides a number of generic traits like different getter and setter methods, an implementation of the
singleton design pattern and some little helpers. Those traits are too small to justify their own packages and most of them
are dependencies of the <a href="guides/overview/datastructures.html">Typed Datastructures</a>
and <a href="guides/overview/interfaces.html">Interface Traits</a>
anyway.</p>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-Getter.html"><abbr title="\OCC\Basics\Traits\Getter">Getter</abbr></a>
</li>
</ul>
</div>
</div>
<div class="section" id="getter">
<h2>Getter</h2>
<p>Reads data from inaccessible properties by using magic methods.</p>
<p>To make a <code>protected</code> or <code>private</code> property readable, provide a method named
<code>_magicGet{Property}()</code> which handles the reading. Replace <code>{Property}</code> in
the method&#039;s name with the name of the actual property (with an uppercase
first letter).</p>
<p>&gt; Example: If the property is named <code>$fooBar</code>, the &quot;magic&quot; method has to be
&gt; <code>_magicGetFooBar()</code>. This method is then called when <code>$fooBar</code> is read in
&gt; a context where it normally would not be accessible.</p>
<p><em>Reads data from inaccessible properties by using magic methods.</em></p>
<p>To make a <code>protected</code> or <code>private</code> property readable, provide a method named <code>_magicGet{Property}()</code> which handles the
reading. Replace <code>{Property}</code> in the method&#039;s name with the name of the actual property (with an uppercase first
letter).</p>
<p>Trying to access an undefined property or a property without corresponding &quot;magic&quot; getter method will result in an
<a href="https://www.php.net/invalidargumentexception">\InvalidArgumentException</a>.</p>
<blockquote><p>Example: If the property is named <code>$fooBar</code>, the &quot;magic&quot; method has to be <code>_magicGetFooBar()</code>. This method is then
called when <code>$fooBar</code> is read in a context where it normally would not be accessible.</p></blockquote>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-Setter.html"><abbr title="\OCC\Basics\Traits\Setter">Setter</abbr></a>
</li>
</ul>
</div>
</div>
<div class="section" id="overloadinggetter">
<h2>OverloadingGetter</h2>
<p>Overloads a class with readable magic properties.</p>
<p>Internally it reads the protected <code>$_data</code> array whose keys are interpreted
as property names.</p>
<p>&gt; Example: Reading <code>Foo-&gt;bar</code> will return the value of <code>$_data[&#039;bar&#039;]</code>.</p>
</div>
<div class="section" id="overloadingsetter">
<h2>OverloadingSetter</h2>
<p>Overloads a class with writable magic properties.</p>
<p>Internally it writes the protected <code>$_data</code> array whose keys are interpreted
as property names.</p>
<p>&gt; Example: <code>Foo-&gt;bar = 42;</code> will set <code>$_data[&#039;bar&#039;]</code> to <code>42</code>.</p>
</div>
<div class="section" id="setter">
<h2>Setter</h2>
<p>Writes data to inaccessible properties by using magic methods.</p>
<p>To make a <code>protected</code> or <code>private</code> property writable, provide a method named
<code>_magicSet{Property}()</code> which handles the writing. Replace <code>{Property}</code> in
the method&#039;s name with the name of the actual property (with an uppercase
first letter).</p>
<p>&gt; Example: If the property is named <code>$fooBar</code>, the &quot;magic&quot; method has to be
&gt; <code>_magicSetFooBar()</code>. This method is then called when <code>$fooBar</code> is written
&gt; to in a context where it normally would not be accessible.</p>
<p><em>Writes data to inaccessible properties by using magic methods.</em></p>
<p>To make a <code>protected</code> or <code>private</code> property writable, provide a method named <code>_magicSet{Property}()</code> which handles the
writing. Replace <code>{Property}</code> in the method&#039;s name with the name of the actual property (with an uppercase first
letter).</p>
<p>Trying to access an undefined property or a property without corresponding &quot;magic&quot; setter method will result in an
<a href="https://www.php.net/invalidargumentexception">\InvalidArgumentException</a>.</p>
<blockquote><p>Example: If the property is named <code>$fooBar</code>, the &quot;magic&quot; method has to be <code>_magicSetFooBar()</code>. This method is then
called when <code>$fooBar</code> is written to in a context where it normally would not be accessible.</p></blockquote>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-OverloadingGetter.html"><abbr title="\OCC\Basics\Traits\OverloadingGetter">OverloadingGetter</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="overloadinggetter">
<h2>OverloadingGetter</h2>
<p><em>Overloads a class with readable virtual properties.</em></p>
<p>It reads a protected internal array whose keys are interpreted as property names.</p>
<p>Trying to access an undefined virtual property will not issue any warning or error, but return <code>NULL</code> instead.</p>
<blockquote><p>Example: Reading <code>Foo-&gt;bar</code> will return the value of <code>Foo::$_data[&#039;bar&#039;]</code>.</p></blockquote>
<div class="phpdocumentor-admonition note">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path></svg>
<article>
<p>Internally it uses the <code>$_data</code> array, the same as some <a href="guides/overview/datastructures.html">Typed Datastructures</a>
and all <a href="guides/overview/interfaces.html">Interface Traits</a>
of this
package.</p>
</article>
</div>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-OverloadingSetter.html"><abbr title="\OCC\Basics\Traits\OverloadingSetter">OverloadingSetter</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="overloadingsetter">
<h2>OverloadingSetter</h2>
<p><em>Overloads a class with writable virtual properties.</em></p>
<p>It writes a protected internal array whose keys are interpreted as property names.</p>
<p>Trying to access a previously undefined virtual property will create a new one with the given name.</p>
<blockquote><p>Example: <code>Foo-&gt;bar = 42;</code> will set <code>Foo::$_data[&#039;bar&#039;]</code> to <code>42</code>.</p></blockquote>
<div class="phpdocumentor-admonition note">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path></svg>
<article>
<p>Internally it uses the <code>$_data</code> array, the same as some <a href="guides/overview/datastructures.html">Typed Datastructures</a>
and all <a href="guides/overview/interfaces.html">Interface Traits</a>
of this
package.</p>
</article>
</div>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-Singleton.html"><abbr title="\OCC\Basics\Traits\Singleton">Singleton</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="singleton">
<h2>Singleton</h2>
<p>Allows just a single instance of the class using this trait.</p>
<p>Get the singleton by calling the static method <code>getInstance()</code>.</p>
<p>If there is no object yet, the constructor is called with the same arguments
as <code>getInstance()</code>. Any later call will just return the already instantiated
object (irrespective of the given arguments).</p>
<p>In order for this to work as expected, the constructor has to be implemented
as <code>private</code> to prevent direct instantiation of the class.</p>
<p><em>Allows just a single instance of the class using this trait.</em></p>
<p>Get the singleton by calling the static method <code>getInstance()</code>. If there is no object yet, the constructor is called
with the same arguments as <code>getInstance()</code>. Any later call will just return the already instantiated object
(irrespective of the given arguments).</p>
<div class="phpdocumentor-admonition caution">
<svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path></svg>
<article>
<p>In order for this to work as expected, the constructor has to be implemented as <code>private</code> to prevent direct
instantiation of the class.</p>
</article>
</div>
<div class="admonition-wrapper">
<div class="admonition admonition-sidebar"><p class="sidebar-title">API Documentation</p>
<ul>
<li><a href="classes/OCC-Basics-Traits-TypeChecker.html"><abbr title="\OCC\Basics\Traits\TypeChecker">TypeChecker</abbr></a>
</li>
</ul>
</div>
</div>
</div>
<div class="section" id="typechecker">
<h2>TypeChecker</h2>
<p>A generic data type checker.</p>
<p>This allows to set a list of allowed atomic data types and fully qualified
class names. It also provides a method to check if a value&#039;s data type matches
at least one of these types.</p>
<p><em>A generic data type checker.</em></p>
<p>This allows to set a list of allowed atomic data types and fully qualified class names. It also provides a method to
check if a value&#039;s data type matches at least one of these types.</p>
<p>Available atomic types are <code>array</code>, <code>bool</code>, <code>callable</code>, <code>countable</code>, <code>float</code> / <code>double</code>, <code>int</code> / <code>integer</code> / <code>long</code>,
<code>iterable</code>, <code>null</code>, <code>numeric</code>, <code>object</code>, <code>resource</code>, <code>scalar</code> and <code>string</code>.</p>
</div>
</div>

2
src/Traits/Getter.php
View File

@ -65,7 +65,7 @@ trait Getter
} else {
throw new InvalidArgumentException(
sprintf(
'Invalid property or missing getter method for property: %s->%s.',
'Invalid property or missing getter method for property: %s::$%s.',
static::class,
$property
)

2
src/Traits/Setter.php
View File

@ -65,7 +65,7 @@ trait Setter
} else {
throw new InvalidArgumentException(
sprintf(
'Invalid property or missing setter method for property: %s->%s.',
'Invalid property or missing setter method for property: %s::$%s.',
static::class,
$property
)