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 wraps parameters
ParametersTrait wraps parameters
ImmutableOptionsTrait wraps options
OptionsTrait wraps options
ImmutableSettingsTrait wraps settings
SettingsTrait wraps settings

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 libraries
make tests runs the phpunit tests
make 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.

graste / params

Maintainers

Details