Trait RegistryTrait

Allows for private values to be declared at runtime, and maintain scope with specific traits or classes, despite inheritance.

Provides a set of methods to abstract complex, scoped private values into a simple dot separated naming convention. Works with both arrays as well as objects, respecting visibility.

Array or object nesting is represented as a dot separated string notation, consistent with other languages namespacing such as javascript or MySQL. This allows for broader universalization of schema represenation without as much one-off parsing logic as PHP's internal schema normally allows without additional abstraction.

Public facing api's in this system honor standard notation. As such, this trait does not provide public methods, and you will have to expose them manually if used for interactive containerization.

oroboros\core\traits\patterns\behavioral\RegistryTrait uses oroboros\core\traits\utilities\logic\BackreferenceTrait

Direct Known Users

oroboros\core\traits\libraries\container\ContainerTrait, oroboros\core\traits\patterns\creational\PrototyperTrait

Namespace: oroboros\core\traits\patterns\behavioral
Package: oroboros\core\patterns
Category: traits
License: The MIT License (MIT)
Author: Brian Dayhoff mopsyd@me.com
Version: 0.2.4-alpha
Since: 0.1.1
Link: bitbucket.org/oroborosframework/oroboros-core/wiki/development/api/contract_interface.md
Planned: This trait is set up to eventually also support tree search algorithms, though that is not yet implemented.
Planned:

The indexing functionality will eventually be separated from the container functionality into it's own trait, which will be used by this one. This should not change the protected or public api when this occurs.

Traits provide extended method support to classes without requiring a direct, linear chain of inheritance. This allows functions to inherit subsets of related methods without declaring a parent class.

In Oroboros core, ALL methods are granted to classes via traits, and the classes themselves are just containers that correlate their methods to an interface they are expected to honor. This approach maximizes interoperability, by entirely removing class inheritance as a requirement for extension of any class in this system.

3rd parties using this package are not expected to follow this approach,

but ALL of our internal class and logic structure does.

Located at core/traits/patterns/behavioral/RegistryTrait.php

Methods summary

`protected boolean`	# `_getRegistryValue( scalar $key = null , boolean $safe,… )` Returns the requested value, defined by dot separated depth notation (works with both arrays and objects, so they can be treated interchangably with by higher logic without mutating their state). Returns the requested value, defined by dot separated depth notation (works with both arrays and objects, so they can be treated interchangably with by higher logic without mutating their state). Implementing classes are expected to know their key structure on request, and to not ask for invalid keys. Operation will break with an exception if invalid keys are requested. This is a control structure, so if you need to handle ambiguity, either handle that locally, or containerize it within a scope that tolerates ambiguity internally before registering it). Parameters `$key` The name of the registry key, typically a string. May follow dot separated notation to declare depth. `$safe`,… (optional) Prevents overwrites if true. Default false. Returns boolean True if the value was set, false if the old value was retained Throws `oroboros\core\utilities\exception\InvalidArgumentException` if passed a non-scalar key Version 0.2.4-alpha Since 0.2.4-alpha Example 'classname.dependencies' resolves to $this->_registry_values['\namespace\of\local\scope\ClassOrTrait']['classname']['dependencies']
`protected`	# `_resetRegistry( )` Sets the localized registry back to an empty state. Sets the localized registry back to an empty state.
`protected array`	# `_fetchRegistry( )` Returns the entire localized registry. Returns the entire localized registry. Returns array
`protected integer\|boolean`	# `_countRegistryKeys( scalar $key = null )` Returns a count of the registry keys by dot separated scope. If $key is null, returns the entire localized scope. Returns a count of the registry keys by dot separated scope. If $key is null, returns the entire localized scope. Parameters `$key` a dot separated key to check the registry for Returns integer\|boolean returns false if $key is not an array or does not exist, otherwise returns the count of values. Throws `oroboros\core\utilities\exception\InvalidArgumentException` if a non-scalar key is passed and $key is not null
`protected boolean &`	# `_getRegistryValueReference( scalar $key = null , boolean $safe,… )` Returns the specified value from the registry, but returns a reference to the original instead of a copy. Otherwise this method works identically to _getRegistryValue Returns the specified value from the registry, but returns a reference to the original instead of a copy. Otherwise this method works identically to _getRegistryValue This method honors dot separated notation (the dot separator is overrideable) Parameters `$key` The name of the registry key, typically a string. May follow dot separated notation to declare depth. `$safe`,… (optional) Prevents overwrites if true. Default false. Returns boolean True if the value was set, false if the old value was retained Throws `oroboros\core\utilities\exception\InvalidArgumentException` if passed a non-scalar key Version 0.2.4-alpha Since 0.2.4-alpha Example 'classname.dependencies' resolves to $this->_registry_values['\namespace\of\local\scope\ClassOrTrait']['classname']['dependencies']
`final protected boolean`	# `_checkRegistryValue( scalar $key )` Returns a boolean determination as to whether a specified dot separated key exists in the registry for the current scope. Returns a boolean determination as to whether a specified dot separated key exists in the registry for the current scope. Parameters `$key` Returns boolean Throws `oroboros\core\utilities\exception\InvalidArgumentException`
`final protected boolean`	# `_setRegistryValue( scalar $key, boolean $value = array(), $safe = false )` Creates a new key in the registry index with an empty container as a value. Creates a new key in the registry index with an empty container as a value. Honors dot separated notation, and will create all non-existent parent keys leading up to the leaf-node key also if they do not exist. If $safe is true, it will not overwrite an existing one of the same key. The default behavior is to overwrite, just like any other variable being directly manipulated. Parameters `$key` The name of the registry key, typically a string. May follow dot separated notation to declare depth. `$value` $safe (optional) Prevents overwrites if true. Default false. `$safe` Returns boolean True if the value was set, false if the old value was retained Throws `oroboros\core\utilities\exception\InvalidArgumentException` if passed a non-scalar key Version 0.2.4-alpha Since 0.2.4-alpha
`final protected`	# `_unsetRegistryIndex( type $key )` Deletes a registry key by dot separated key name. Deletes a registry key by dot separated key name. Parameters `$key` Throws `oroboros\core\utilities\exception\InvalidArgumentException` if a non-scalar key is passed Version 0.2.4-alpha Since 0.2.4-alpha
`final protected string`	# `_getRegistryIndexSeparator( )` Returns the current registry index separator. Returns the current registry index separator. Returns string Version 0.2.4-alpha Since 0.2.4-alpha
`final protected`	# `_resetRegistryIndexSeparator( )` Resets the recognized registry index separator to it's default ["."]. Resets the recognized registry index separator to it's default ["."]. Version 0.2.4-alpha Since 0.2.4-alpha
`protected`	# `_setRegistryIndexSeparator( string $separator )` Sets a new registry index separator value, which can then be used to determine index depth in place of the default dot syntax. This is provided for compatibility with programming logic that is not inherently compatible with the dot syntax, so that it may still work interchangeably with the registry. Sets a new registry index separator value, which can then be used to determine index depth in place of the default dot syntax. This is provided for compatibility with programming logic that is not inherently compatible with the dot syntax, so that it may still work interchangeably with the registry. Parameters `$separator` Throws `oroboros\core\utilities\exception\InvalidArgumentException` If the supplied value is not a string Version 0.2.4-alpha Since 0.2.4-alpha Example If you want to represent separation within the system $PATH variable, change the separator to a colon [":"], and then your registry functionality can operate equivalently to the system path notation.
`private`	# `_initializeRegistry( $reset = false )` This must be called to initialize an instance of the registry at least one time, so all protected methods in this trait do so. The root registry index will be scoped to the fully qualified trait or class name that called registration. It will only distribute values in scope, maintaining privacy, and leaving it to the referencing construct to expose those values as needed. This must be called to initialize an instance of the registry at least one time, so all protected methods in this trait do so. The root registry index will be scoped to the fully qualified trait or class name that called registration. It will only distribute values in scope, maintaining privacy, and leaving it to the referencing construct to expose those values as needed. This method may be called redundantly without mutating state. Version 0.2.4-alpha Since 0.2.4-alpha
`private string`	# `_extractRegistryLocalizedIndex( string $backreference )` Returns the root localized key reference from a supplied fully qualified method name Returns the root localized key reference from a supplied fully qualified method name Parameters `$backreference` fully qualified method name (eg: \namespace\of\reference\ClassOrTraitName::methodName) Returns string Returns the fully namespaced reference, without the function name Version 0.2.4-alpha Since 0.2.4-alpha
`private type`	# `_resolveRegistryKeyMapping( type $index, type $key )` Returns whether a specified index exists or not, honoring dot separated index notation. Returns whether a specified index exists or not, honoring dot separated index notation. Parameters `$index` `$key` Returns type Version 0.2.4-alpha Since 0.2.4-alpha
`private boolean`	# `_checkRegistryKeyMapping( type $index, type $key )` Returns a determination as to whether or not a key exists in any provided subset, as defined in its dot separated notation (or literal representation, if no dos separation occurs) Returns a determination as to whether or not a key exists in any provided subset, as defined in its dot separated notation (or literal representation, if no dos separation occurs) Parameters `$index` The array or object to begin the search against. `$key` the key or key tree to isolate Returns boolean true if found, false if not Throws `oroboros\core\utilities\exception\LogicException` as a redundancy if some specific edge case was not considered. This means the core code needs to be patched if this occurs, and otherwise should never occur. Version 0.2.4-alpha Since 0.2.4-alpha Recursive
`private mixed &`	# `_getRegistryKeyMapping( array\|object $index, scalar $key = null )` Returns the specified key from the registry, honoring dot separated index depth notation. Returns the specified key from the registry, honoring dot separated index depth notation. Parameters `$index` the specific index of the registry to start searching within `$key` the key to identify the value by Returns mixed a reference to the value within the registry corresponding to the key. Higher visibility methods are responsible for conversion if a return reference is not desireable. Throws `oroboros\core\utilities\exception\InvalidArgumentException` if the key does not exist in the registry Version 0.2.4-alpha Since 0.2.4-alpha
`private boolean`	# `_setRegistryKeyMapping( array\|object & $index, scalar $key, mixed $value = array() , boolean $safe,… )` Sets a value in the registry by dot notated index reference. Sets a value in the registry by dot notated index reference. Parameters `$index` A specific index of the registry to match within `$key` a key identifier for the value `$value` the value to set `$safe`,… (optional) if true, will not overwrite existing keys. Default false. Returns boolean if true, the value was set. If false, safe mode was declared and the key already existed, or you tried to set a value in a leaf that can't take one (like a string or integer). Version 0.2.4-alpha Since 0.2.4-alpha
`private type`	# `_deleteRegistryKeyMapping( type & $index, type $key )` Deletes a key from the registry Deletes a key from the registry Parameters `$index` `$key` Returns type Version 0.2.4-alpha Since 0.2.4-alpha

Methods used from oroboros\core\traits\utilities\logic\BackreferenceTrait

_convertBackReferenceNameSpaceToRelativeFilePath(), _filterBackReferenceTraitInheritance(), _findBackReferenceRealInheritanceLocation(), _getBackReference(), _getBackReferenceMatchingTraits(), _getBackReferenceTraceReferenceReflector()

Properties summary

`private array`	`$_registry_values` Primary container for private registry encapsulation. Primary container for private registry encapsulation.	# `[ ]`
`private string`	`$_registry_default_index_separator` the default registry index separator. This will be allowed to be overidden later, but that will need a lot of testing. the default registry index separator. This will be allowed to be overidden later, but that will need a lot of testing.	# `'.'`
`private string`	`$_registry_index_separator` the registry index separator. This will be allowed to be overidden later, but that will need a lot of testing. the registry index separator. This will be allowed to be overidden later, but that will need a lot of testing.	# `'.'`

Namespaces

Traits

Trait RegistryTrait

Direct Known Users

but ALL of our internal class and logic structure does.

Methods summary

Parameters

Returns

Throws

Version

Since

Example

Returns

Parameters

Returns

Throws

Parameters

Returns

Throws

Version

Since

Example

Parameters

Returns

Throws

Parameters

Returns

Throws

Version

Since

Parameters

Throws

Version

Since

Returns

Version

Since

Version

Since

Parameters

Throws

Version

Since

Example

Version

Since

Parameters

Returns

Version

Since

Parameters

Returns

Version

Since

Parameters

Returns

Throws

Version

Since

Recursive

Parameters

Returns

Throws

Version

Since

Parameters

Returns

Version

Since

Parameters

Returns

Version

Since

Methods used from oroboros\core\traits\utilities\logic\BackreferenceTrait

Properties summary