Dot gives you easy access to nested PHP arrays using dot notation. Instead of chaining $array['user']['address']['city'] and checking every level with isset(), you write $dot->get('user.address.city').
It’s lightweight and inspired by Laravel’s collections. A Dot object also implements ArrayAccess and Countable, so you can keep using it like a normal array, with dot notation on top.
$dot = dot(['user' => ['name' => 'Jane']]);
$dot->get('user.name'); // 'Jane'
$dot->set('user.address.city', 'Helsinki');
$dot->has('user.address.city'); // true
$dot['user.email'] = '[email protected]'; // works like an array tooInstall the latest version using Composer:
composer require adbario/php-dot-notation
Create a new Dot object:
$dot = new \Adbar\Dot;
// With existing array
$dot = new \Adbar\Dot($array);
// Or with auto-parsing dot notation keys in an existing array
$dot = new \Adbar\Dot($array, true);
// You can also set a custom delimiter instead of the default dot (.)
$dot = new \Adbar\Dot($array, false, "_");You can also use a helper function to create the object:
$dot = dot();
// With existing array
$dot = dot($array);
// Or with auto-parsing dot notation keys in an existing array
$dot = dot($array, true);
// You can also set a custom delimiter instead of the default dot (.)
$dot = dot($array, true, "_");All methods that do not return a specific value return the Dot object for chaining:
$dot = dot();
$dot->add('user.name', 'John')
->set('user.email', '[email protected]')
->clear(); // returns empty DotDot has the following methods:
- add()
- all()
- clear()
- count()
- delete()
- flatten()
- get()
- has()
- isEmpty()
- merge()
- mergeRecursive()
- mergeRecursiveDistinct()
- pull()
- push()
- replace()
- set()
- setArray()
- setReference()
- toJson()
Sets a given key/value pair if the key doesn't exist already:
$dot->add('user.name', 'John');
// Equivalent vanilla PHP
if (!isset($array['user']['name'])) {
$array['user']['name'] = 'John';
}Multiple key/value pairs:
$dot->add([
'user.name' => 'John',
'page.title' => 'Home'
]);Returns all the stored items as an array:
$values = $dot->all();Deletes the contents of a given key (sets an empty array):
$dot->clear('user.settings');
// Equivalent vanilla PHP
$array['user']['settings'] = [];Multiple keys:
$dot->clear(['user.settings', 'app.config']);All the stored items:
$dot->clear();
// Equivalent vanilla PHP
$array = [];Returns the number of items in a given key. A non-countable value counts as one item and a missing key counts as zero items:
$dot->count('user.siblings');Items in the root of the Dot object:
$dot->count();
// Or use count() function as Dot implements Countable
count($dot);Deletes the given key:
$dot->delete('user.name');
// ArrayAccess
unset($dot['user.name']);
// Equivalent vanilla PHP
unset($array['user']['name']);Multiple keys:
$dot->delete([
'user.name',
'page.title'
]);Returns a flattened array with the keys delimited by a given character (default "."):
$flatten = $dot->flatten();Returns the value of a given key:
echo $dot->get('user.name');
// ArrayAccess
echo $dot['user.name'];
// Equivalent vanilla PHP
echo $array['user']['name'] ?? null;Returns a given default value if the given key doesn't exist:
echo $dot->get('user.name', 'some default value');Checks if a given key exists (returns boolean true or false):
$dot->has('user.name');
// ArrayAccess
isset($dot['user.name']);Multiple keys:
$dot->has([
'user.name',
'page.title'
]);Checks if a given key is empty (returns boolean true or false):
$dot->isEmpty('user.name');
// ArrayAccess
empty($dot['user.name']);
// Equivalent vanilla PHP
empty($array['user']['name']);Multiple keys:
$dot->isEmpty([
'user.name',
'page.title'
]);Checks the whole Dot object:
$dot->isEmpty();Merges a given array or another Dot object:
$dot->merge($array);
// Equivalent vanilla PHP
array_merge($originalArray, $array);Merges a given array or another Dot object with the given key:
$dot->merge('user', $array);
// Equivalent vanilla PHP
array_merge($originalArray['user'], $array);Recursively merges a given array or another Dot object:
$dot->mergeRecursive($array);
// Equivalent vanilla PHP
array_merge_recursive($originalArray, $array);Recursively merges a given array or another Dot object with the given key:
$dot->mergeRecursive('user', $array);
// Equivalent vanilla PHP
array_merge_recursive($originalArray['user'], $array);Recursively merges a given array or another Dot object. Duplicate keys overwrite the value in the original array (unlike mergeRecursive(), where duplicate keys are transformed into arrays with multiple values):
$dot->mergeRecursiveDistinct($array);Recursively merges a given array or another Dot object with the given key. Duplicate keys overwrite the value in the original array.
$dot->mergeRecursiveDistinct('user', $array);Returns the value of a given key and deletes the key:
echo $dot->pull('user.name');
// Equivalent vanilla PHP
echo $array['user']['name'] ?? null;
unset($array['user']['name']);Returns a given default value if the given key doesn't exist:
echo $dot->pull('user.name', 'some default value');Returns all the stored items as an array and clears the Dot object:
$items = $dot->pull();Pushes a given value to the end of the array at a given key:
$dot->push('users', 'John');
// Equivalent vanilla PHP
$array['users'][] = 'John';Pushes a given value to the end of the array:
$dot->push('John');
// Equivalent vanilla PHP
$array[] = 'John';If the given key already holds a non-array, non-null value, the value is not pushed and the Dot object is left unchanged.
Replaces the values with values having the same keys in the given array or Dot object:
$dot->replace($array);
// Equivalent vanilla PHP
array_replace($originalArray, $array);Replaces the values with values having the same keys in the given array or Dot object with the given key:
$dot->replace('user', $array);
// Equivalent vanilla PHP
array_replace($originalArray['user'], $array);replace() is not recursive.
Sets a given key/value pair:
$dot->set('user.name', 'John');
// ArrayAccess
$dot['user.name'] = 'John';
// Equivalent vanilla PHP
$array['user']['name'] = 'John';Multiple key/value pairs:
$dot->set([
'user.name' => 'John',
'page.title' => 'Home'
]);Replaces all items in the Dot object with a given array:
$dot->setArray($array);Replaces all items in the Dot object with a given array by reference, and all future changes to Dot will be made directly to the original array:
$dot->setReference($array);Returns the value of a given key as JSON:
echo $dot->toJson('user');Returns all the stored items as JSON:
echo $dot->toJson();You can also pass JSON encoding options:
// For a given key
echo $dot->toJson('user', JSON_PRETTY_PRINT);
// For all the stored items
echo $dot->toJson(JSON_PRETTY_PRINT);- Fork the Dot repository
- Create a new branch for each feature or improvement
- Send a pull request from each feature branch to the 3.x branch
Keep new features and improvements in separate feature branches, and submit a pull request for each branch. This lets us review and merge new features or improvements individually.
All pull requests must adhere to the PSR-12 standard.
All pull requests must be accompanied by passing unit tests and complete code coverage. Dot uses PHPUnit for testing.
All pull requests must pass static analysis using PHPStan.