From 3670945f3ecbb617edbb2075230ac0a66473becd Mon Sep 17 00:00:00 2001 From: Sebastian Meyer Date: Sun, 31 Mar 2024 17:41:04 +0200 Subject: [PATCH] Update documentation --- .phpdoc/guide/changelog.rst | 12 +- .phpdoc/guide/overview/datastructures.rst | 41 ++-- .phpdoc/guide/overview/errorhandlers.rst | 34 ++- .phpdoc/guide/overview/interfaces.rst | 71 ++++++- .phpdoc/guide/overview/traits.rst | 125 +++++++---- .../ErrorHandlers/ThrowErrorException.php.txt | 8 +- doc/files/src/Traits/Getter.php.txt | 2 +- doc/files/src/Traits/Setter.php.txt | 2 +- doc/guides/changelog.html | 14 +- doc/guides/overview/datastructures.html | 68 +++--- doc/guides/overview/errorhandlers.html | 50 ++++- doc/guides/overview/index.html | 4 +- doc/guides/overview/interfaces.html | 102 ++++++++- doc/guides/overview/traits.html | 201 ++++++++++++++---- src/Traits/Getter.php | 2 +- src/Traits/Setter.php | 2 +- 16 files changed, 533 insertions(+), 205 deletions(-) diff --git a/.phpdoc/guide/changelog.rst b/.phpdoc/guide/changelog.rst index ed048a3..699c974 100644 --- a/.phpdoc/guide/changelog.rst +++ b/.phpdoc/guide/changelog.rst @@ -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:** diff --git a/.phpdoc/guide/overview/datastructures.rst b/.phpdoc/guide/overview/datastructures.rst index 666c1e9..f79683f 100644 --- a/.phpdoc/guide/overview/datastructures.rst +++ b/.phpdoc/guide/overview/datastructures.rst @@ -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 `_, `\Countable `_ and `\Serializable `_ interfaces. All -but `StrictCollection` also implement the `\Traversable `_ interface. +but `StrictCollection` also implement a `\Traversable `_ interface. Examples: @@ -28,56 +28,57 @@ but `StrictCollection` also implement the `\Traversable `_ 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 `_ 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 `_ with an option to restrict the allowed data types for stack items. diff --git a/.phpdoc/guide/overview/errorhandlers.rst b/.phpdoc/guide/overview/errorhandlers.rst index eb82d53..844e20d 100644 --- a/.phpdoc/guide/overview/errorhandlers.rst +++ b/.phpdoc/guide/overview/errorhandlers.rst @@ -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 +`_. It respects the `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()); diff --git a/.phpdoc/guide/overview/interfaces.rst b/.phpdoc/guide/overview/interfaces.rst index dcd8357..cfcedb2 100644 --- a/.phpdoc/guide/overview/interfaces.rst +++ b/.phpdoc/guide/overview/interfaces.rst @@ -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 `_ 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 `_ interface allows objects to be used with the `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 `_ interface creates an external `\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 `_ 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; + } diff --git a/.phpdoc/guide/overview/traits.rst b/.phpdoc/guide/overview/traits.rst index 462083d..1ed6924 100644 --- a/.phpdoc/guide/overview/traits.rst +++ b/.phpdoc/guide/overview/traits.rst @@ -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 `_. -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 `_. + + 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`. diff --git a/doc/files/src/ErrorHandlers/ThrowErrorException.php.txt b/doc/files/src/ErrorHandlers/ThrowErrorException.php.txt index f0ccd93..f9ff9af 100644 --- a/doc/files/src/ErrorHandlers/ThrowErrorException.php.txt +++ b/doc/files/src/ErrorHandlers/ThrowErrorException.php.txt @@ -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); } diff --git a/doc/files/src/Traits/Getter.php.txt b/doc/files/src/Traits/Getter.php.txt index 5fb7559..6a213ec 100644 --- a/doc/files/src/Traits/Getter.php.txt +++ b/doc/files/src/Traits/Getter.php.txt @@ -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 ) diff --git a/doc/files/src/Traits/Setter.php.txt b/doc/files/src/Traits/Setter.php.txt index 6580164..e1208a7 100644 --- a/doc/files/src/Traits/Setter.php.txt +++ b/doc/files/src/Traits/Setter.php.txt @@ -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 ) diff --git a/doc/guides/changelog.html b/doc/guides/changelog.html index b4dbdbb..e08dfdc 100644 --- a/doc/guides/changelog.html +++ b/doc/guides/changelog.html @@ -193,14 +193,14 @@ OCC\Basics\InterfaceTraits\Countable -> OCC\Basics\Interfaces\Countab OCC\Basics\InterfaceTraits\IteratorAggregate -> OCC\Basics\Interfaces\IteratorAggregateTrait OCC\Basics\InterfaceTraits\Iterator -> OCC\Basics\Interfaces\IteratorTrait -

  • Renamed internal methods for Getter +

  • Prefixed internal methods for Getter and Setter - to avoid -confusion with regular class methods

    // old methods
-function magicGet{PascalCasePropertyName}(): mixed
-function magicSet{PascalCasePropertyName}(mixed $value): void
    // new methods
-function _magicGet{PascalCasePropertyName}(): mixed
-function _magicSet{PascalCasePropertyName}(mixed $value): void
    • + with +_ to avoid confusion with regular class methods

    // old methods
+function magicGet{Property}(): mixed
+function magicSet{Property}(mixed $value): void
    // new methods
+function _magicGet{Property}(): mixed
+function _magicSet{Property}(mixed $value): void
    diff --git a/doc/guides/overview/datastructures.html b/doc/guides/overview/datastructures.html index 1875c14..e42953c 100644 --- a/doc/guides/overview/datastructures.html +++ b/doc/guides/overview/datastructures.html @@ -188,16 +188,11 @@ class names you want to allow as item types. Available atomic types are ar .

    All strict datastructures inherit the implementation of the \ArrayAccess, \Countable and \Serializable interfaces. All -but StrictCollection also implement the \Traversable interface.

    +but StrictCollection also implement a \Traversable interface.

    Examples:

    // create a collection of strings
-$stringCollection = new StrictCollection(['string']);
-
-// create a queue of PSR-15 middlewares
+$stringCollection = new StrictCollection(['string']);
    // create a queue of PSR-15 middlewares
 $middlewareQueue = new StrictQueue(['Psr\Http\Server\MiddlewareInterface']);
    -
    -

    StrictCollection

    -

    API Documentation

    @@ -211,24 +206,22 @@ $middlewareQueue = new StrictQueue(['Psr\Http\Server\MiddlewareInterface�
    +
    +

    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.

    -

    Internally it holds the items in the $_data array, the same as most Interfaces - and -Traits - of this package.

    +

    Internally it holds the items in the $_data array, the same as most Interface Traits + and Traits + of this +package.

    -
    - -
    -

    StrictArray

    -

    API Documentation

    @@ -242,24 +235,24 @@ controlled type. The collection can be accessed like an array, but not traversed
    +
    + +
    +

    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.

    -

    Internally it holds the items in the $_data array, the same as most Interfaces - and -Traits - of this package.

    +

    Internally it holds the items in the $_data array, the same as most Interface Traits + and Traits + of this +package.

    -
    - -
    -

    StrictList

    -

    API Documentation

    @@ -273,14 +266,14 @@ controlled type. The array can be accessed and traversed just like any other arr
    +
    + +
    +

    StrictList

    +

    A type-sensitive, taversable list of items.

    Extends \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

    -

    API Documentation

    @@ -294,17 +287,17 @@ types for list items. The list can be accessed and traversed like an array, but
    +
    + +
    +

    StrictQueue

    +

    A type-sensitive, taversable queue (FIFO) of items.

    Extends \SplQueue 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.

    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

    -

    API Documentation

    @@ -318,6 +311,11 @@ queue, because those will ensure proper FIFO behavior and remove items while tra
    +
    + +
    +

    StrictStack

    +

    A type-sensitive, taversable stack (LIFO) of items.

    Extends \SplStack 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 diff --git a/doc/guides/overview/errorhandlers.html b/doc/guides/overview/errorhandlers.html index c1aa4b3..92a8642 100644 --- a/doc/guides/overview/errorhandlers.html +++ b/doc/guides/overview/errorhandlers.html @@ -172,27 +172,57 @@

    Error and Exception Handlers

    -

    Table of Contents

    -
    +

    API Documentation

    + + + +

    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());

    +

    Throws internal errors as exceptions.

    +

    If registered as error handler, this handles an internal PHP error by converting it into an \ErrorException. It respects the 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());
    + +
    + +
    +

    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.

    +
    +
    + +
    +

    API Documentation

    + + + + +
    +
    +

    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());

    +

    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());
    +
    diff --git a/doc/guides/overview/index.html b/doc/guides/overview/index.html index d84d476..e861b9f 100644 --- a/doc/guides/overview/index.html +++ b/doc/guides/overview/index.html @@ -216,12 +216,12 @@ other projects.

  • Traits
    • +

    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.

    +
    + +
    +

    Internally all interface traits use the $_data array, the same as some Typed Datastructures + and Traits + of +this package.

    +
    +
    + +
    +

    API Documentation

    + + + + +
    +
    +

    ArrayAccessTrait

    -

    A generic implementation of the ArrayAccess interface.

    -

    Internally it accesses the protected $_data array.

    +

    A generic implementation of the ArrayAccess interface.

    +

    The \ArrayAccess interface allows objects to be accessed like arrays.

    +

    Usage:

    class Foo implements ArrayAccess
+{
+    use \OCC\Basics\Interfaces\ArrayAccessTrait;
+}
    + +
    +

    API Documentation

    + + + + +
    +
    +

    CountableTrait

    -

    A generic implementation of the Countable interface.

    -

    Internally it counts the values of the protected $_data array.

    +

    A generic implementation of the Countable interface.

    +

    The \Countable interface allows objects to be used with the count() function.

    +

    Usage:

    class Foo implements Countable
+{
+    use \OCC\Basics\Interfaces\CountableTrait;
+}
    + +
    +

    API Documentation

    + + + + +
    +
    +

    IteratorAggregateTrait

    -

    A generic implementation of the IteratorAggregate interface.

    -

    Internally it iterates over the protected $_data array.

    +

    A generic implementation of the IteratorAggregate interface.

    +

    The \IteratorAggregate interface creates an external \ArrayIterator for traversing the object's internal data array.

    +

    Usage:

    class Foo implements IteratorAggregate
+{
+    use \OCC\Basics\Interfaces\IteratorAggregateTrait;
+}
    + +
    +

    API Documentation

    + + + + +
    +
    +

    IteratorTrait

    -

    A generic implementation of the Iterator interface.

    -

    Internally it iterates over the protected $_data array.

    +

    A generic implementation of the Iterator interface.

    +

    The \Iterator interface creates an internal iterator for traversing the object's data +array.

    +

    Usage:

    class Foo implements Iterator
+{
+    use \OCC\Basics\Interfaces\IteratorTrait;
+}
    +
    diff --git a/doc/guides/overview/traits.html b/doc/guides/overview/traits.html index 0d1e5d8..41edee3 100644 --- a/doc/guides/overview/traits.html +++ b/doc/guides/overview/traits.html @@ -173,73 +173,186 @@

    Table of 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 Typed Datastructures + and Interface Traits + anyway.

    +
    +

    API Documentation

    + + + +

    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.

    +

    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).

    +

    Trying to access an undefined property or a property without corresponding "magic" getter method will result in an +\InvalidArgumentException.

    +

    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.

    + +
    +

    API Documentation

    + + + +
    +
    -
    -

    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.

    +

    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).

    +

    Trying to access an undefined property or a property without corresponding "magic" setter method will result in an +\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.

    + +
    +

    API Documentation

    + + + + +
    +
    + +
    + +
    +

    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'].

    + +
    + + +
    + +
    +

    API Documentation

    + + + + +
    +
    + +
    + +
    +

    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.

    + +
    + + +
    + +
    +

    API Documentation

    + + + + +
    +
    +

    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.

    +

    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.

    +
    +
    + +
    +

    API Documentation

    + + + + +
    +
    +

    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.

    +

    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.

    +

    Available atomic types are array, bool, callable, countable, float / double, int / integer / long, +iterable, null, numeric, object, resource, scalar and string.

    diff --git a/src/Traits/Getter.php b/src/Traits/Getter.php index 5fb7559..6a213ec 100644 --- a/src/Traits/Getter.php +++ b/src/Traits/Getter.php @@ -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 ) diff --git a/src/Traits/Setter.php b/src/Traits/Setter.php index 6580164..e1208a7 100644 --- a/src/Traits/Setter.php +++ b/src/Traits/Setter.php @@ -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 )