Vale
Vale helps you working with complex data structures. Easily get, set, unset and check the existence of values in
deeply nested arrays and objects., (*1)
, (*2)
Developed by Florian Eckerstorfer in Vienna, Europe., (*3)
Features
- Get, set, unset and check the existence of values in deeply nested arrays and objects
- Works with arbitrary arrays and objects and any combination of them
- Uses getters, setters, unsetters, hassers and issers in objects
$name = Vale::get($families, ['lannister', 'leader', 'children', 2, 'name']);
// This would be equal to the following
$name = null;
if (isset($families['lannister']) && $families['lannister']) {
if ($families['lannister']->getLeader()) {
if (isset($families['lannister']->getLeader()->children[2]) && $families['lannister']->getLeader()->children[2]) {
$name = $families['lannister']->getLeader()->children[2]->name();
}
}
}
Installation
You can install Vale using Composer:, (*4)
$ composer require cocur/vale
Usage
You can use either the static methods provided by Vale or create an instance of Vale., (*5)
use Cocur\Vale\Vale;
$data = ['name' => 'Tyrion'];
Vale::get($data, ['name']); // -> "Tyrion"
Vale::set($data, ['name'], 'Cersei'); // -> ["name" => "Cersei"]
Vale::has($data, ['name']); // -> true
Vale::remove($data, ['name']); // -> []
$vale = new Vale();
$vale->getValue($data, ['name']); // -> "Tyrion"
$vale->setValue($data, ['name'], 'Cersei'); // -> ["name" => "Cersei"]
$vale->hasValue($data, ['name']); // -> true
$vale->removeValue($data, ['name']); // -> []
For flat arrays and objects (that is, arrays and objects with only one level of depth) you can also use a string
or integer as key. This works for the static as well as the instance methods., (*6)
Vale::get(['name' => 'Tyrion'], 'name'); // -> "Tyrion"
Vale::get(['Tyrion'], 0); // -> "Tyrion"
Get
::get() and ->getValue() return the value of a specified element., (*7)
mixed get(mixed $data, array|string|int $keys, mixed $default = null)
mixed getValue(mixed $data, array|string|int $keys, mixed $default = null)
-
$data is an arbitrary data structure
-
$keys is an array of keys to access the value. If the length is 1, $keys can be a string or int
-
$default is the default value that is returned if the value does not exist in $data
Returns the element at the given position or the original $data if $keys is empty., (*8)
Vale tries different ways to access the element specified in $keys. The following variants are tried in this order:, (*9)
$data[$key]$data->$key()$data->get$Key()$data->get($key)$data->has$Key()$data->has($key)$data->is$Key()$data->is($key)$data->$key
Set
::set() and ->setValue() set the value of an element at the given position., (*10)
mixed set(mixed $data, array|string|int $keys, mixed $value)
mixed setValue(mixed $data, array|string|int $keys, mixed $value)
-
$data is an arbitrary data structure
-
$keys is an array of keys to access the value. If the length is 1, $keys can be a string or int
-
$value is the value for the element
Returns the modified $data, (*11)
Set utilizes the same means of navigating through nested data structures as Get and tries the following
variants to set the value:, (*12)
$data[$key] = $value$data->$key($value)$data->set$Key($value)$data->set($key, $value)$data->$key = $value
Has
::has() and ->hasValue() returns if an element exists, (*13)
bool has(mixed $data, array|string|int $keys)
bool hasValue(mixed $data, array|string|int $keys)
-
$data is an arbitrary data structure
-
$keys is an array of keys to access the value. If the length is 1, $keys can be a string or int
Returns true if the element exists, false otherwise., (*14)
Has utilizes the same means of navigating through nested data structures as Get and tries the following
variants to check the existence of an element:, (*15)
isset($data[$key])isset($data->$key)$data->has$Key()$data->has($key)$data->is$Key()$data->is($key)$data->$key()$data->get$Key()
The variants involving a method call (such as has$Key() or has()) return true if the method returns true or
a value that evaluates to true. If the method returns a value that evaluates to false (such as '', 0 or null)
then has returns false., (*16)
Remove
::remove() and ->removeValue() remove an element from the given data structure, (*17)
mixed remove(mixed $data, array|string|int $keys)
mixed removeValue(mixed $data, array|string|int $keys)
-
$data is an arbitrary data structure
-
$keys is an array of keys to access the value. If the length is 1, $keys can be a string or int
Returns the modified $data or null if $keys is empty, (*18)
Remove utilizes the same means of navigating through nested data structures as Get and tries the following
variants to remove the element from the data structure:, (*19)
unset($data[$key])unset($data->$key)$data->unset$Key()$data->remove$Key()$data->remove($key)
Please note that unset() is not used, because it is an reserved keyword in PHP., (*20)
Change Log
Version 0.2 (24 March 2015)
- Add
has() method to check if key exists
- Add
remove() method to remove key from item
- Improved navigating through complex structures
- Major refactoring, making the code more reusable and testable
Version 0.1 (15 March 2015)
Motivation
Vale was largely motivated by the need for a simpler, but faster implementation of the
Symfony PropertyAccess component.
PropertyAccess is great when used in templates or config files, that is, code that is compiled and cached before
being executed. However, the heavy use of string parsing and reflection make PropertyAccess not suitable for code that
is not compiled. Another source of inspiration was the get-in library by Igor
Wiedler for array traversal., (*21)
Name: I used A Song of Ice and Fire related strings for testing and due to having to write value quite often, I came
up with Vale., (*22)
Author
Vale has been developed by Florian Eckerstorfer (Twitter) in
Vienna, Europe., (*23)
Vale is a project of Cocur. You can contact us on Twitter:
@cocurco, (*24)
License
The MIT license applies to Vale. For the full copyright and license information, please view the
LICENSE file distributed with this source code., (*25)
Wallogit.com
