PHPackages                             cocur/vale - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. cocur/vale

ActiveLibrary[Utility & Helpers](/categories/utility)

cocur/vale
==========

Vale is a helper utility that lets you get and set values in arbitrary nested arrays and objects.

v0.2(11y ago)1498.7k—4.2%16MITPHPPHP >=5.4

Since Mar 15Pushed 10y ago1 watchersCompare

[ Source](https://github.com/cocur/vale)[ Packagist](https://packagist.org/packages/cocur/vale)[ RSS](/packages/cocur-vale/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (2)Versions (5)Used By (6)

Vale
====

[](#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.

[![Build Status](https://camo.githubusercontent.com/ddc1ae7b6e1089768e805d2b9af18aa839143bf005c47100259e9cfd389b0a5d/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f636f6375722f76616c652f6d61737465722e7376673f7374796c653d666c6174)](https://travis-ci.org/cocur/vale)[![Windows Build status](https://camo.githubusercontent.com/edcde3e463d5973f832f1ac512dc99c9657c068e7f557571accbf7f375b335be/68747470733a2f2f63692e6170707665796f722e636f6d2f6170692f70726f6a656374732f7374617475732f356a676632736f626b66397066776a643f7376673d74727565)](https://ci.appveyor.com/project/florianeckerstorfer/vale)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/0366b34f160d8b7f9032526428d24764ce7f0d4e392788e503d86af0445f32a7/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f636f6375722f76616c652e7376673f7374796c653d666c6174)](https://scrutinizer-ci.com/g/cocur/vale/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/e7fa4bb9a1fdd23c7dba969922da3780608e7266f4effebebaabbbb607743a85/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f636f6375722f76616c652e7376673f7374796c653d666c6174)](https://scrutinizer-ci.com/g/cocur/vale/?branch=master)[![StyleCI](https://camo.githubusercontent.com/95771bb0ea5621ff708ce47fc5a678319114eeccf35fe9390013d570afd6dc93/68747470733a2f2f7374796c6563692e696f2f7265706f732f33323232363938372f736869656c64)](https://styleci.io/repos/32226987)

Developed by [Florian Eckerstorfer](https://florian.ec) in Vienna, Europe.

Features
--------

[](#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
------------

[](#installation)

You can install Vale using [Composer](https://getcomposer.org):

```
$ composer require cocur/vale
```

Usage
-----

[](#usage)

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

```
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.

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

### Get

[](#get)

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

```
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.

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

[](#set)

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

```
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`

*Set* utilizes the same means of navigating through nested data structures as [Get](#get) and tries the following variants 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

[](#has)

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

```
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.

*Has* utilizes the same means of navigating through nested data structures as [Get](#get) and tries the following variants 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 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`.

### Remove

[](#remove)

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

```
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

*Remove* utilizes the same means of navigating through nested data structures as [Get](#get) and tries the following variants 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 that `unset()` is not used, because it is an reserved keyword in PHP.*

Change Log
----------

[](#change-log)

### Version 0.2 (24 March 2015)

[](#version-02-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)

[](#version-01-15-march-2015)

- Initial release

Motivation
----------

[](#motivation)

Vale was largely motivated by the need for a simpler, but faster implementation of the [Symfony PropertyAccess](http://symfony.com/doc/current/components/property_access/introduction.html) 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`](https://github.com/igorw/get-in) library by Igor Wiedler for array traversal.

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](http://awoiaf.westeros.org/index.php/Vale_of_Arryn).

Author
------

[](#author)

Vale has been developed by [Florian Eckerstorfer](https://florian.ec) ([Twitter](https://twitter.com/Florian_)) in Vienna, Europe.

> Vale is a project of [Cocur](http://cocur.co). You can contact us on Twitter: [**@cocurco**](https://twitter.com/cocurco)

License
-------

[](#license)

The MIT license applies to Vale. For the full copyright and license information, please view the [LICENSE](https://github.com/cocur/vale/blob/master/LICENSE) file distributed with this source code.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity39

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~3 days

Total

4

Last Release

4073d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/a80f9fc61cd3a7d7779e8f120b458ca4d18fdd885d719bb77d3379b96bf714d9?d=identicon)[florianeckerstorfer](/maintainers/florianeckerstorfer)

---

Tags

array-manipulationcomplex-structuresobject-manipulation

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cocur-vale/health.svg)

```
[![Health](https://phpackages.com/badges/cocur-vale/health.svg)](https://phpackages.com/packages/cocur-vale)
```

###  Alternatives

[tareq1988/wordpress-settings-api-class

WordPress settings API Abstraction Class

46611.1k3](/packages/tareq1988-wordpress-settings-api-class)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)