From 28a2de4cfeb5c7f1193621aa94ef74459a694ca6 Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 20:10:53 +0100 Subject: [PATCH 1/6] Updated phpDocs for Entry class methods --- src/Setup/Entry.php | 46 +++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/src/Setup/Entry.php b/src/Setup/Entry.php index f6f52de..692a37b 100644 --- a/src/Setup/Entry.php +++ b/src/Setup/Entry.php @@ -17,8 +17,8 @@ /** - * Write-only proxy with helper methods to instantiate and - * set Record implementations for given Container name id. + * Write-only proxy with helper methods to instantiate and set + * Record implementations for given Container name identifier. */ class Entry { @@ -32,7 +32,7 @@ public function __construct(string $name, Collection $records) } /** - * Pushes given Record instance directly into Container's records + * Adds given Record instance directly into container records * using this instance's name property. * * @param Record $record @@ -45,7 +45,7 @@ public function record(Record $record): void } /** - * Pushes ValueRecord with given value into Container's records. + * Adds ValueRecord with given value into container records. * * @see ValueRecord * @@ -59,12 +59,12 @@ public function value($value): void } /** - * Pushes CallbackRecord with given callable into Container's records. + * Adds CallbackRecord with given callable into container records. * Callback receives ContainerInterface instance as parameter. * * @see CallbackRecord * - * @param callable $callback + * @param callable $callback function (ContainerInterface): mixed * * @throws Exception\InvalidIdException */ @@ -74,15 +74,15 @@ public function callback(callable $callback): void } /** - * Pushes ComposeRecord with given className and its constructor - * parameters given as Container id names. Each dependency has - * to be defined within collection (otherwise circular references - * cannot be avoided). + * Adds ComposeRecord to container records with given className + * and its constructor parameters given as Container id names. + * Each dependency has to be defined within collection (otherwise + * circular references cannot be avoided). * - * When dependency id equals this instance name it is not overwritten and - * circular dependency is not created - it is decorated instead. - * Now every class depending on decorated object will take product of this - * record as its dependency. Objects can be decorated multiple times. + * When dependency id equals this instance name it is not overwritten + * and circular dependency is not created - it is decorated instead. + * Now every class depending on decorated object will take product of + * this record as its dependency. Objects can be wrapped multiple times. * * @see ComposeRecord * @@ -102,22 +102,32 @@ public function compose(string $className, string ...$dependencies): void } /** - * Pushes CreateMethodRecord with given method of container identified - * factory and its parameter values as container identifiers. + * Adds CreateMethodRecord to container records with given container + * identifier of factory class, factory method name and container + * identifiers of its parameters. * * @see CreateMethodRecord * * @param string $factoryId * @param string $method - * @param string ...$arguments Container identifiers of stored arguments + * @param string ...$arguments * - * @throws Exception\InvalidIdException | Exception\RecordNotFoundException + * @throws Exception\InvalidIdException */ public function create(string $factoryId, string $method, string ...$arguments): void { $this->record(new Record\CreateMethodRecord($factoryId, $method, ...$arguments)); } + /** + * Adds ContainerInterface instance as sub-container that may + * be accessed with current entry name prefix (entry name + * cannot contain prefix separator). + * + * @param ContainerInterface $container + * + * @throws Exception\InvalidIdException + */ public function container(ContainerInterface $container) { $this->records->addContainer($this->name, $container); From 2724e9c216cc06100e7e6e36ae5502fb23131aef Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 20:53:36 +0100 Subject: [PATCH 2/6] Updated phpDocs for Setup class methods --- src/Setup.php | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/src/Setup.php b/src/Setup.php index bacfef4..228e63c 100644 --- a/src/Setup.php +++ b/src/Setup.php @@ -23,12 +23,27 @@ public function __construct(Setup\Collection $collection = null) $this->collection = $collection ?: new Setup\Collection(); } + /** + * Creates Setup with validated collection. + * + * Added entries will be validated for identifier conflicts and + * created container will be monitored for circular references. + * + * @return self + */ public static function secure(): self { return new self(new Setup\ValidatedCollection()); } /** + * Creates Setup with predefined configuration. + * + * If `true` is passed as $validate param secure version of Setup + * will be created and predefined configuration will be validated. + * + * @see Setup::secure() + * * @param Records\Record[] $records * @param ContainerInterface[] $containers * @param bool $validate @@ -44,14 +59,11 @@ public static function withData(array $records = [], array $containers = [], boo } /** - * Returns Container instance with provided records. - * - * Adding new entries to container is still possible, but only - * using this instance's entry() method. + * Returns immutable Container instance with provided data. * - * Strict immutability can be ensured only when this instance is - * encapsulated and not passed to uncontrolled parts of application - * (including container itself). + * Adding new entries to this setup is still possible, but created + * container will not be affected and this method will create new + * container instance with those added entries. * * @return ContainerInterface */ @@ -61,8 +73,8 @@ public function container(): ContainerInterface } /** - * Returns Entry object able to configure Container's - * data slot for given name id. + * Returns Entry object able to add new data to container configuration + * for given identifier. * * @param string $name * @@ -74,7 +86,7 @@ public function entry(string $name): Setup\Entry } /** - * Stores Records instantiated directly in container. + * Adds Record instances directly to container configuration. * * @param Records\Record[] $records Flat associative array of Record instances * From e16dc539514e300b228fbb89a52a66d13c9a1dce Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 22:00:34 +0100 Subject: [PATCH 3/6] Updated phpDocs for ConfigContainer class --- src/ConfigContainer.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/ConfigContainer.php b/src/ConfigContainer.php index c5f8847..b4593e4 100644 --- a/src/ConfigContainer.php +++ b/src/ConfigContainer.php @@ -16,7 +16,8 @@ /** * Container with multidimensional array values accessed using path notation identifiers. - * Example: $config['key']['sub-key']['id'] is accessed with $instance->get('key.sub-key.id'). + * + * @example $instance->get('key.sub-key.id') === $config['key']['sub-key']['id'] */ class ConfigContainer implements ContainerInterface { @@ -25,8 +26,8 @@ class ConfigContainer implements ContainerInterface private $config; /** - * $config keys MUST NOT contain path separator, because values - * stored under these keys will not be accessible. + * $config keys MUST NOT contain path separator on any level, + * because values stored under these keys will not be accessible. * * @param array $config Associative (multidimensional) array of config values */ From 78d0ea598d8082808cdb4b407d6f8f73eb8b4f60 Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 22:05:58 +0100 Subject: [PATCH 4/6] Updated phpDocs for TrackedRecords class --- src/Records/TrackedRecords.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/Records/TrackedRecords.php b/src/Records/TrackedRecords.php index 33e006a..e2e862e 100644 --- a/src/Records/TrackedRecords.php +++ b/src/Records/TrackedRecords.php @@ -16,6 +16,11 @@ use Psr\Container\ContainerInterface; +/** + * Instance of Records with nested call tracking, detecting + * circular calls to passed ContainerInterface and appending + * call stack paths to exception messages. + */ class TrackedRecords extends Records { private $callStack = []; From 96dda299ad8d889ce32f768ea8640956d7eca1f4 Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 22:19:00 +0100 Subject: [PATCH 5/6] Updated phpDocs for Record ind its mplementations --- src/Records/Record.php | 4 ++-- src/Records/Record/CallbackRecord.php | 6 +++--- src/Records/Record/ComposeRecord.php | 7 +++---- src/Records/Record/CreateMethodRecord.php | 13 +++++++------ src/Records/Record/ValueRecord.php | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/src/Records/Record.php b/src/Records/Record.php index 7178bb2..826080b 100644 --- a/src/Records/Record.php +++ b/src/Records/Record.php @@ -23,11 +23,11 @@ interface Record * Unwraps value requested from container. * * Container instance is passed as parameter because value - * may derive from other Container entries. + * may need other container entries to be created. * * @param ContainerInterface $container * - * @return mixed unwrapped record value + * @return mixed */ public function value(ContainerInterface $container); } diff --git a/src/Records/Record/CallbackRecord.php b/src/Records/Record/CallbackRecord.php index 60daa0c..dcefa70 100644 --- a/src/Records/Record/CallbackRecord.php +++ b/src/Records/Record/CallbackRecord.php @@ -16,10 +16,10 @@ /** - * Record that returns value invoked from callable property. + * Record that returns value invoked from given callback, called with + * ContainerInterface instance as parameter. * - * Returned value is cached and returned directly when - * value() method is called again. + * Returned value is cached and returned directly on subsequent calls. */ class CallbackRecord implements Record { diff --git a/src/Records/Record/ComposeRecord.php b/src/Records/Record/ComposeRecord.php index 2136b70..04fc661 100644 --- a/src/Records/Record/ComposeRecord.php +++ b/src/Records/Record/ComposeRecord.php @@ -19,8 +19,7 @@ * Record that creates and returns object of given class name * created with Container entries as its constructor parameters. * - * Returned object is cached and returned directly when - * value() method is called again. + * Returned value is cached and returned directly on subsequent calls. */ class ComposeRecord implements Record { @@ -31,8 +30,8 @@ class ComposeRecord implements Record private $object; /** - * @param string $className - * @param string[] $dependencies ContainerInterface ids to get constructor values from + * @param string $className class to instantiate + * @param string ...$dependencies container identifiers for class constructor parameters */ public function __construct(string $className, string ...$dependencies) { diff --git a/src/Records/Record/CreateMethodRecord.php b/src/Records/Record/CreateMethodRecord.php index c5d074e..e6027f4 100644 --- a/src/Records/Record/CreateMethodRecord.php +++ b/src/Records/Record/CreateMethodRecord.php @@ -16,10 +16,11 @@ /** - * Record that creates its value by calling a method on (factory) object. + * Record that creates returned value by calling method name + * and container entries both as method's parameters and factory + * object the call is made on. * - * Returned value is cached and returned directly when - * value() method is called again. + * Returned value is cached and returned directly on subsequent calls. */ class CreateMethodRecord implements Record { @@ -31,9 +32,9 @@ class CreateMethodRecord implements Record private $product; /** - * @param string $method - * @param string $factoryId - * @param string ...$arguments + * @param string $factoryId container identifier for factory object + * @param string $method factory method name + * @param string ...$arguments container identifiers for method parameters */ public function __construct(string $factoryId, string $method, string ...$arguments) { diff --git a/src/Records/Record/ValueRecord.php b/src/Records/Record/ValueRecord.php index c8f18ce..d3c9304 100644 --- a/src/Records/Record/ValueRecord.php +++ b/src/Records/Record/ValueRecord.php @@ -16,7 +16,7 @@ /** - * Record that returns its property value directly. + * Record that directly returns its property value. */ class ValueRecord implements Record { From 5ea71e6928087e5ca9cd59545e1f155ec250c38c Mon Sep 17 00:00:00 2001 From: Shudd3r Date: Thu, 14 Nov 2019 23:08:09 +0100 Subject: [PATCH 6/6] Updated phpDocs for record-based containers --- src/CompositeContainer.php | 8 ++++++++ src/RecordContainer.php | 4 ++++ src/Records.php | 10 ++++++++-- 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/src/CompositeContainer.php b/src/CompositeContainer.php index f446a29..657fcb2 100644 --- a/src/CompositeContainer.php +++ b/src/CompositeContainer.php @@ -14,6 +14,10 @@ use Psr\Container\ContainerInterface; +/** + * RecordContainer merged with additional sub-containers accessed + * with separated prefix identifier. + */ class CompositeContainer implements ContainerInterface { public const SEPARATOR = '.'; @@ -22,6 +26,10 @@ class CompositeContainer implements ContainerInterface private $containers; /** + * Container identifiers cannot contain separator. + * Records will not be called when existing container + * identifier is used (as prefix). + * * @param Records $records * @param ContainerInterface[] $containers */ diff --git a/src/RecordContainer.php b/src/RecordContainer.php index 3a383a7..05587d3 100644 --- a/src/RecordContainer.php +++ b/src/RecordContainer.php @@ -14,6 +14,10 @@ use Psr\Container\ContainerInterface; +/** + * ContainerInterface implementation using Records instance + * with various strategies to deliver values. + */ class RecordContainer implements ContainerInterface { protected $records; diff --git a/src/Records.php b/src/Records.php index 9eaf9a2..5a74cf5 100644 --- a/src/Records.php +++ b/src/Records.php @@ -14,6 +14,9 @@ use Psr\Container\ContainerInterface; +/** + * Container of Record strategies to produce container values. + */ class Records { private $records; @@ -27,7 +30,8 @@ public function __construct(array $records = []) } /** - * Checks if Record is stored at given identifier. + * Checks if Record is stored at given identifier without + * calling for its value. * * @param string $id * @@ -39,7 +43,9 @@ public function has(string $id): bool } /** - * Returns Record stored at given identifier. + * Returns Record value stored at given identifier. + * ContainerInterface is given for possibility of producing + * Record's value using another container entries. * * @param string $id * @param ContainerInterface $container