phrity / util-accessor
Utility to handle access to a data set by using access paths.
Installs: 1 074
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: ^8.0
Requires (Dev)
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^9.0 | ^10.0 | ^11.0
- squizlabs/php_codesniffer: ^3.0
README
Introduction
Utility to handle access to a data set by using access paths.
Installation
Install with Composer;
composer require phrity/util-accessor
How to use
Basic operation get()
and has()
methods
Any set of data (including arrays, objects, and scalar values) can be access using a path.
use Phrity\Util\Accessor; $subject = [ 'string-val' => 'A string', 'assoc-array-val' => [ 'string-val' => 'Another string', ], 'num-array-val' => [ 'a', ], 'object-val' => (object)[ 'string-val' => 'Yet another string', ], ]; $accessor = new Accessor(); $accessor->get($subject, 'string-val'); // => "A string" $accessor->get($subject, 'assoc-array-val'); // => ['string-val' => "Another string"] $accessor->get($subject, 'assoc-array-val/string-val'); // => "Another string" $accessor->get($subject, 'num-array-val/0'); // => "a" $accessor->get($subject, 'object-val/string-val'); // => "Yet another string" $accessor->has($subject, 'assoc-array-val/string-val'); // => true $accessor->has($subject, 'assoc-array-val/non-exising'); // => false
Using default return value for get()
method
The get()
method can also have default value specified, to be returned when path do not match the data set.
If not specified, null
will be returned in these cases.
use Phrity\Util\Accessor; $subject = [ 'string-val' => 'A string', ]; $accessor = new Accessor(); $accessor->get($subject, 'non-existing'); // => null $accessor->get($subject, 'non-existing', 'My default'); // => "My default"
The set()
method
The set()
method add or replace value in data set as specified by path.
Note that this operation do not merge values, but set explicitly.
Depending on scope, it may not be possible to use set()
on class properties.
In this case an AccessorException
will be thrown.
use Phrity\Util\Accessor; $subject = [ 'string-val' => 'A string', ]; $accessor = new Accessor(); $subject = $accessor->set($subject, 'string-val', 'Replaced value'); $subject = $accessor->set($subject, 'non-existing', 'Added value'); // $subject => ['string-val' => 'Replaced value', 'non-existing' => 'Added value']
Specifying path separator
By default, path uses /
as separator. Optionally, separator can be set in constructor.
use Phrity\Util\Accessor; $subject = [ 'object-val' => (object)[ 'string-val' => 'A string', ], ]; $accessor = new Accessor('.'); $accessor->get($subject, 'object-val.string-val'); // => "A string" $accessor->has($subject, 'object-val.string-val'); // => true
The PathAccessor
If multiple data sets should be accessed using the same path, the PathAccessor can be used instead.
The path is then specified on constructor, and then used on all calls to get()
, has()
and set()
.
use Phrity\Util\PathAccessor; $subject_1 = [ 'object-val' => (object)[ 'string-val' => 'A string', ], ]; $subject_2 = [ 'object-val' => (object)[ 'string-val' => 'Another string', ], ]; $accessor = new PathAccessor('object-val/string-val'); $accessor->get($subject_1); // => "A string" $accessor->get($subject_2); // => "Another string" $subject_1 = $accessor->set($subject_1, 'Replaced value'); $subject_2 = $accessor->set($subject_2, 'Replaced value');
The DataAccessor
If a data sets should be accessed using multiple paths, the DataAccessor can be used instead.
The data is then specified on constructor, and then used on all calls to get()
, has()
and set()
.
use Phrity\Util\DataAccessor; $subject = [ 'object-val' => (object)[ 'string-val' => 'A string', 'int-val' => 23, ], ]; $accessor = new DataAccessor(subject); $accessor->get('object-val/string-val'); // => "A string" $accessor->get('object-val/int-val'); // => 23 $accessor->set('object-val/string-val', 'Replaced string'); $accessor->set('object-val/int-val', 48);
I want to incorporate this in my own class
Sure, no problem. Just use the AccessorTrait
in your class, and call the available worker methods.
The internal, recursive worker methods takes path as an array of path segments.
There is also a helper to extract array path from a string path.
use Phrity\Util\AccessorTrait; class MyClass { use AccessorTrait; public function doThings(): void { $my_data = ['array-val' => ['string-val' => 'A string']]; $exists = $this->accessorHas($my_data, ['array-val', 'string-val']); $something = $this->accessorGet($my_data, ['array-val', 'string-val'], 'My default'); $my_path = $this->accessorParsePath('array-val#string-val', '#'); $exists = $this->accessorHas($my_data, $my_path); $something = $this->accessorGet($my_data, $my_path, 'My default'); $modified = $this->accessorSet($my_data, $my_path, 'My new value'); } }