graste / params
Array wrapper that eases the retrieval of values. Has parameters, options and settings and traits for inclusion in other libraries.
Installs: 6 910
Dependents: 1
Suggesters: 0
Security: 0
Stars: 11
Watchers: 3
Forks: 0
Open Issues: 1
Requires
- php: ^7.0
- mtdowling/jmespath.php: ^1.1 || ^2.4
Requires (Dev)
- phpunit/phpunit: ^5.7
- squizlabs/php_codesniffer: ^3.3
README
Purpose
Array wrapper object that eases the retrieval of values. It provides a get
method that can return a default value if the given key is missing. In addition to the usage as a normal array and the various get
, set
, has
etc. methods Parameters defines a getValues($expression)
method that allows the retrieval of values by providing more or less complex expressions. You can easily retrieve values from nested arrays or get several values from different nesting levels with one call. There are traits for convenient creation of configurable classes.
Requirements and installation
- PHP ^7.0
Install the library via Composer:
./composer.phar require graste/params [optional version]
Adding it manually as a vendor library requirement to the composer.json
file of your project works as well:
{ "require": { "graste/params": "^3.0.0" } }
Alternatively, you can download a release archive from the releases.
Documentation and usage
$data = array( 'str' => 'some string', 'first_level' => 'first level', 'nested' => array( 'str' => 'some nested string', '2nd level' => 'second level', ), 'more' => array( 'str' => 'other nested string', ) ); // base object of the aliased versions: $arrayobj = new \Params\ConfigurableArrayObject($array); // create mutable parameters instance: $params = new \Params\Parameters($data); // or initialize an immutable instance that prevents further modifications after construction $params = new \Params\Immutable\ImmutableParameters($data); // do you like options instead of parameters in your classes? $params = new \Params\Options($data); $params = new \Params\Immutable\ImmutableOptions($data); // do you like settings instead of parameters in your classes? $params = new \Params\Settings($data); $params = new \Params\Immutable\ImmutableSettings($data); // use it as a recursive object: $params->has("foo") // returns true now $params->get("str") // gives "some string" $params->get("nested") // gives array stored under "nested" key $params->get("nested")->get('str') // gives "some nested string" $params->get("non-existant", "default value") // gives "default value" as given key is non existant $params->get("nested")->set("foo", "bar") // sets key "foo" to value "bar" on the "nested" array $params->getKeys() // returns all first level keys $params->toArray() // returns internal array // or use the mutable methods $params->set("foo", "bar") // sets key "foo" to value "bar" $params->add(array|ArrayAccess) // add array or other ArrayAccess implementing object to current instance $params->clear() // empty internal array $params->map(function($key, $value) { … }) // modifies each value to the value returned by the callback // retrieve values using expressions $params->getValues("foo") // gives "bar" $params->getValues("nested.str") // gives "some nested string" $params->getValues('*.str') // gives array("some nested string", "other nested string") $params->getValues('[str, nested.str]') // gives array("some string", "some nested string") $params->getValues('nested."2nd level" || first_level') // gives "second level" as that key exists; other expression not evaluated $params->getValues('first_level || nested."2nd level"') // gives "first level" as that key exists; other expression not evaluated // use it as an array: $params["str"] // gives "some string" $params["nested"] // gives the array under the "nested" key $params[1] // gives "first level" // use it as an object with properties $params->foo = 'bar' // sets key 'foo' to value 'bar' $params->filter->bool = 'yes' // sets $params['filter']['bool'] to value 'yes'
The expression syntax used is provided by Michael Dowling's JMESPath.
Traits
There are Traits may be used for own configurable classes:
ImmutableParametersTrait
wrapsparameters
ParametersTrait
wrapsparameters
ImmutableOptionsTrait
wrapsoptions
OptionsTrait
wrapsoptions
ImmutableSettingsTrait
wrapssettings
SettingsTrait
wrapssettings
For fluent API support the methods add
, set
, remove
and clear
return the class instance they're mixed into.
ElasticSearch queries
The syntax sugar Parameters
provides is not only nice to define configurable classes, but also eases the creation and modification of ElasticSearch queries:
$params->filter->bool->must[1]->term->live = false; $params->get('filter')->set('bool', …); $params->filter->bool->must[] = array(…);
Contribution
Please contribute by forking and sending a pull request. More information can be found in the CONTRIBUTING.md
file.
To develop on this repository clone your fork and use the Makefile
targets:
make install
installs composer and all necessary vendor librariesmake tests
runs the phpunit testsmake code-sniffer-cli
runs the code sniffer on console
The code tries to adhere to the following PHP-FIG standards: PSR-4, PSR-1 and PSR-2. The current license is MIT.
The authors and contributors are mentioned in the github contributors graph of this repository. The license file must be left intact for attribution and sharing of this work.
Changelog
See CHANGELOG.md
for more information about changes.