Update documentation

.phpdoc/guide/changelog.rst

@@ -3,7 +3,8 @@
 Changelog
 #########
 
-.. contents::
+.. sidebar:: Table of Contents
+  .. contents::
 
 v2.0.0
 ======
@@ -39,7 +40,9 @@ v2.0.0
 * Added new error handler :php:class:`OCC\Basics\ErrorHandlers\TriggerExceptionError`
 * Added new trait :php:trait:`OCC\Basics\Traits\OverloadingGetter`
 * Added new trait :php:trait:`OCC\Basics\Traits\OverloadingSetter`
-* Extended API for all datastructures
+* Added new trait :php:trait:`OCC\Basics\Traits\TypeChecker`
+* Extended API for all datastructures (see :php:trait:`OCC\Basics\DataStructures\Traits\StrictSplDatastructureTrait`)
+* Introduced :php:class:`OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException` for strict datastructures
 * Extended `documentation <https://opencultureconsulting.github.io/php-basics/>`_
 
 v1.1.0

.phpdoc/guide/index.rst

@@ -3,11 +3,8 @@
 Documentation
 #############
 
-.. meta::
-  :layout: landingpage
-
 .. toctree::
-  :hidden:
+  :maxdepth: 2
 
   overview/index
   usage/index

.phpdoc/guide/overview/datastructures.rst

@@ -0,0 +1,79 @@
+.. title:: Datastructures
+
+Typed Datastructures
+####################
+
+.. sidebar:: Table of Contents
+  .. contents::
+
+All datastructures in this package have in common that you can control the types of items they can hold.
+
+To restrict allowed data types for items, provide the constructor with an array of atomic types or fully qualified
+class names you want to allow as item types. Available atomic types are `array`, `bool`, `callable`, `countable`,
+`float` / `double`, `int` / `integer` / `long`, `iterable`, `null`, `numeric`, `object`, `resource`, `scalar` and
+`string`.
+
+Trying to add an item with a data type not on the list of allowed types to a strict datastructure will result in an
+:php:class:`OCC\Basics\DataStructures\Exceptions\InvalidDataTypeException`.
+
+  Examples:
+
+  .. code-block:: php
+    // create a collection of strings
+    $stringCollection = new StrictCollection(['string']);
+
+    // create a queue of PSR-15 middlewares
+    $middlewareQueue = new StrictQueue(['Psr\Http\Server\MiddlewareInterface']);
+
+StrictCollection
+================
+
+.. sidebar:: API Documentation
+  :php:class:`OCC\Basics\DataStructures\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.
+
+A `StrictCollection` can be accessed like an array, but not traversed because it has no particular order. Technically
+speaking, `StrictCollection` implements `\ArrayAccess <https://www.php.net/arrayaccess>`_, `\Countable
+<https://www.php.net/countable>`_ and `\Serializable <https://www.php.net/serializable>`_, but no `\Traversable
+<https://www.php.net/traversable>`_ interface.
+
+.. 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
+==========
+
+.. sidebar:: API Documentation
+  :php:class:`OCC\Basics\DataStructures\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.
+
+StrictQueue
+===========
+
+.. sidebar:: API Documentation
+  :php:class:`OCC\Basics\DataStructures\StrictQueue`
+
+*A type-sensitive, taversable queue (FIFO) of items.*
+
+Extends `\SplDoublyLinkedList <https://www.php.net/spldoublylinkedlist>`_ with an option to restrict the allowed data
+types for list items.
+
+StrictStack
+===========
+
+.. sidebar:: API Documentation
+  :php:class:`OCC\Basics\DataStructures\StrictStack`
+
+*A type-sensitive, taversable stack (LIFO) of items.*
+
+Extends `\SplDoublyLinkedList <https://www.php.net/spldoublylinkedlist>`_ with an option to restrict the allowed data
+types for list items.

.phpdoc/guide/overview/errorhandlers.rst

@@ -0,0 +1,27 @@
+.. title:: Error Handlers
+
+Error and Exception Handlers
+############################
+
+.. sidebar:: Table of Contents
+  .. contents::
+
+ThrowErrorException
+===================
+
+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.
+
+> Usage: `set_error_handler(new ThrowErrorException());`
+
+TriggerExceptionError
+=====================
+
+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`.
+
+> Usage: `set_exception_handler(new TriggerExceptionError());`

.phpdoc/guide/overview/index.rst

@@ -2,3 +2,17 @@
 
 Overview
 ########
+
+The package currently contains classes for :doc:`datastructures`, :doc:`errorhandlers`, multiple :doc:`interfaces`, and
+more generic :doc:`traits` for common use cases. They share the same design principles like property and method naming
+schema, the highest coding standards of `PHPStan <https://phpstan.org/>`_ and `Psalm <https://psalm.dev/>`_, and full
+`PSR-12 <https://www.php-fig.org/psr/psr-12/>`_ compliance to make sure they can be combined and easily re-used in
+other projects.
+
+.. toctree::
+  :maxdepth: 2
+
+  datastructures
+  errorhandlers
+  interfaces
+  traits

.phpdoc/guide/overview/interfaces.rst

@@ -0,0 +1,35 @@
+.. title:: Interfaces
+
+Interface Traits
+################
+
+.. sidebar:: Table of Contents
+  .. contents::
+
+ArrayAccessTrait
+================
+
+A generic implementation of the ArrayAccess interface.
+
+Internally it accesses the protected `$_data` array.
+
+CountableTrait
+==============
+
+A generic implementation of the Countable interface.
+
+Internally it counts the values of the protected `$_data` array.
+
+IteratorAggregateTrait
+======================
+
+A generic implementation of the IteratorAggregate interface.
+
+Internally it iterates over the protected `$_data` array.
+
+IteratorTrait
+=============
+
+A generic implementation of the Iterator interface.
+
+Internally it iterates over the protected `$_data` array.

.phpdoc/guide/overview/traits.rst

@@ -0,0 +1,78 @@
+.. title:: Traits
+
+Traits
+######
+
+.. sidebar:: Table of Contents
+  .. contents::
+
+Getter
+======
+
+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).
+
+> 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.
+
+OverloadingGetter
+=================
+
+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`.
+
+Setter
+======
+
+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).
+
+> 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.
+
+Singleton
+=========
+
+Allows just a single instance of the class using this trait.
+
+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).
+
+In order for this to work as expected, the constructor has to be implemented
+as `private` to prevent direct instantiation of the class.
+
+TypeChecker
+===========
+
+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.

.phpdoc/guide/usage/index.rst

@@ -3,8 +3,12 @@
 User Guide
 ##########
 
+The *PHP Basics* are a library package, not a stand-alone application. The following documentation of requirements and
+installation procedures describes how to make use of the classes and traits within your own application. For a detailed
+description of the package's contents have a look at the :doc:`../overview/index` page.
+
 .. toctree::
-    :maxdepth: 2
+  :maxdepth: 2
 
-    requirements
-    installation
+  requirements
+  installation

.phpdoc/guide/usage/installation.rst

@@ -3,6 +3,9 @@
 Installation
 ############
 
+.. sidebar:: Table of Contents
+  .. contents::
+
 Composer
 ========
 

.phpdoc/template/css/custom.css.twig

@@ -40,6 +40,8 @@ aside.phpdocumentor-sidebar
     padding: 0 var(--spacing-md) !important;
 }
 
+p > code,
+li > code,
 code.prettyprint
 {
     background-color: var(--code-background-color);
@@ -50,6 +52,38 @@ code.prettyprint
     padding: var(--spacing-xxxs);
 }
 
+@media (max-width: 999px) {
+div.admonition-wrapper
+{
+    display: none;
+}
+}
+
+@media (min-width: 1000px) {
+div.admonition-wrapper
+{
+    display: block;
+    float: right;
+    padding: var(--spacing-md);
+    margin: 0 0 var(--spacing-md) var(--spacing-md);
+    width: auto;
+    font-size: var(--text-sm);
+    border: 1px solid var(--primary-color-lighten);
+}
+}
+
+div.admonition-wrapper
+    p.sidebar-title
+{
+    font-weight: bold;
+}
+
+div.contents
+    ul.phpdocumentor-list
+{
+    margin-bottom: 0;
+}
+
 div.phpdocumentor-content
     div.section
         ul

.phpdoc/template/index.html.twig

@@ -10,10 +10,10 @@
 
     <p class="phpdocumentor-summary">A collection of generic classes and useful traits for PHP projects.</p>
 
-    <p>The package currently contains classes for <a href="packages/Basics-DataStructures.html">type-sensitive
-    data structures</a>, <a href="packages/Basics-ErrorHandlers.html">error and exception handlers</a>, multiple
-    <a href="packages/Basics-Interfaces.html">traits implementing standard interfaces</a>, and more generic
-    <a href="packages/Basics-Traits.html">traits for common use cases</a>. They share the same design principles
+    <p>The package currently contains classes for <a href="guides/overview/datastructures.html">type-sensitive
+    data structures</a>, <a href="guides/overview/errorhandlers.html">error and exception handlers</a>, multiple
+    <a href="guides/overview/interfaces.html">traits implementing standard interfaces</a>, and more generic
+    <a href="guides/overview/traits.html">traits for common use cases</a>. They share the same design principles
     like property and method naming schema, highest coding standards of <a href="https://phpstan.org/">PHPStan</a>
     and <a href="https://psalm.dev/">Psalm</a>, and full <a href="https://www.php-fig.org/psr/psr-12/">PSR-12</a>
     compliance to make sure they can be combined and easily re-used in other projects.</p>