Repository files navigation

Vale helps you working with complex data structures. Easily get, set, unset and check the existence of values indeeply nested arrays and objects.

Developed byFlorian Eckerstorfer in Vienna, Europe.

• 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();        }    }}

You can install Vale usingComposer:

$ composer require cocur/vale

You can use either the static methods provided by Vale or create an instance of Vale.

useCocur\Vale\Vale;$data = ['name' =>'Tyrion'];Vale::get($data, ['name']);// -> "Tyrion"Vale::set($data, ['name'],'Cersei');// -> ["name" => "Cersei"]Vale::has($data, ['name']);// -> trueVale::remove($data, ['name']);// -> []$vale =newVale();$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 stringor integer as key. This works for the static as well as the instance methods.

Vale::get(['name' =>'Tyrion'],'name');// -> "Tyrion"Vale::get(['Tyrion'],0);// -> "Tyrion"

::get() and->getValue() return the value of a specified element.

mixedget(mixed$data, array|string|int$keys, mixed$default =null)mixedgetValue(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 is1,$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.

Vale tries different ways to access the element specified in$keys. The following variants are tried in this order:

1. $data[$key]
2. $data->$key()
3. $data->get$Key()
4. $data->get($key)
5. $data->has$Key()
6. $data->has($key)
7. $data->is$Key()
8. $data->is($key)
9. $data->$key

::set() and->setValue() set the value of an element at the given position.

mixedset(mixed$data, array|string|int$keys, mixed$value)mixedsetValue(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 is1,$keys can be a string or int
• $value is the value for the element

Returns the modified$data

Set utilizes the same means of navigating through nested data structures asGet and tries the followingvariants to set the value:

1. $data[$key] = $value
2. $data->$key($value)
3. $data->set$Key($value)
4. $data->set($key, $value)
5. $data->$key = $value

::has() and->hasValue() returns if an element exists

boolhas(mixed$data, array|string|int$keys)boolhasValue(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 is1,$keys can be a string or int

Returnstrue if the element exists,false otherwise.

Has utilizes the same means of navigating through nested data structures asGet and tries the followingvariants to check the existence of an element:

1. isset($data[$key])
2. isset($data->$key)
3. $data->has$Key()
4. $data->has($key)
5. $data->is$Key()
6. $data->is($key)
7. $data->$key()
8. $data->get$Key()

The variants involving a method call (such ashas$Key() orhas()) returntrue if the method returnstrue ora value that evaluates totrue. If the method returns a value that evaluates tofalse (such as'',0 ornull)thenhas returnsfalse.

::remove() and->removeValue() remove an element from the given data structure

mixedremove(mixed$data, array|string|int$keys)mixedremoveValue(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 is1,$keys can be a string or int

Returns the modified$data ornull if$keys is empty

Remove utilizes the same means of navigating through nested data structures asGet and tries the followingvariants to remove the element from the data structure:

1. unset($data[$key])
2. unset($data->$key)
3. $data->unset$Key()
4. $data->remove$Key()
5. $data->remove($key)

Please note thatunset() is not used, because it is an reserved keyword in PHP.

• Addhas() method to check if key exists
• Addremove() method to remove key from item
• Improved navigating through complex structures
• Major refactoring, making the code more reusable and testable

• Initial release

Vale was largely motivated by the need for a simpler, but faster implementation of theSymfony PropertyAccess component.PropertyAccess is great when used in templates or config files, that is, code that is compiled and cached beforebeing executed. However, the heavy use of string parsing and reflection make PropertyAccess not suitable for code thatis not compiled. Another source of inspiration was theget-in library by IgorWiedler for array traversal.

Name: I used A Song of Ice and Fire related strings for testing and due to having to writevalue quite often, I cameup withVale.

Vale has been developed byFlorian Eckerstorfer (Twitter) inVienna, Europe.

Vale is a project ofCocur. You can contact us on Twitter:@cocurco

The MIT license applies to Vale. For the full copyright and license information, please view theLICENSE file distributed with this source code.