, (*1)
About Dot
Dot provides an easy access to arrays of data with dot notation in a lightweight and fast way. Inspired by Laravel Collection., (*2)
Dot implements PHP's ArrayAccess interface and Dot object can also be used the same way as normal arrays with additional dot notation., (*3)
Examples
With Dot you can change this regular array syntax:, (*4)
$array['info']['home']['address'] = 'Kings Square';
echo $array['info']['home']['address'];
// Kings Square
to this (Dot object):, (*5)
$dot->set('info.home.address', 'Kings Square');
echo $dot->get('info.home.address');
or even this (ArrayAccess):, (*6)
$dot['info.home.address'] = 'Kings Square';
echo $dot['info.home.address'];
Install
Install the latest version using Composer:, (*7)
composer require adbario/php-dot-notation
Usage
Create a new Dot object:, (*8)
$dot = new \Adbar\Dot;
// With existing array
$dot = new \Adbar\Dot($array);
// Or with auto parsing dot notation keys in 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:, (*9)
$dot = dot();
// With existing array
$dot = dot($array);
// Or with auto parsing dot notation keys in existing array
$dot = dot($array, true);
// You can also set a custom delimiter instead of the default dot (.)
$dot = dot($array, true, "_");
All methods not returning a specific value returns the Dot object for chaining:, (*10)
$dot = dot();
$dot->add('user.name', 'John')
->set('user.email', 'john@example.com')
->clear(); // returns empty Dot
Methods
Dot has the following methods:, (*11)
, (*12)
add()
Sets a given key / value pair if the key doesn't exist already:, (*13)
$dot->add('user.name', 'John');
// Equivalent vanilla PHP
if (!isset($array['user']['name'])) {
$array['user']['name'] = 'John';
}
Multiple key / value pairs:, (*14)
$dot->add([
'user.name' => 'John',
'page.title' => 'Home'
]);
, (*15)
all()
Returns all the stored items as an array:, (*16)
$values = $dot->all();
, (*17)
clear()
Deletes the contents of a given key (sets an empty array):, (*18)
$dot->clear('user.settings');
// Equivalent vanilla PHP
$array['user']['settings'] = [];
Multiple keys:, (*19)
$dot->clear(['user.settings', 'app.config']);
All the stored items:, (*20)
$dot->clear();
// Equivalent vanilla PHP
$array = [];
, (*21)
count()
Returns the number of items in a given key:, (*22)
$dot->count('user.siblings');
Items in the root of Dot object:, (*23)
$dot->count();
// Or use count() function as Dot implements Countable
count($dot);
, (*24)
delete()
Deletes the given key:, (*25)
$dot->delete('user.name');
// ArrayAccess
unset($dot['user.name']);
// Equivalent vanilla PHP
unset($array['user']['name']);
Multiple keys:, (*26)
$dot->delete([
'user.name',
'page.title'
]);
, (*27)
flatten()
Returns a flattened array with the keys delimited by a given character (default "."):, (*28)
$flatten = $dot->flatten();
, (*29)
get()
Returns the value of a given key:, (*30)
echo $dot->get('user.name');
// ArrayAccess
echo $dot['user.name'];
// Equivalent vanilla PHP < 7.0
echo isset($array['user']['name']) ? $array['user']['name'] : null;
// Equivalent vanilla PHP >= 7.0
echo $array['user']['name'] ?? null;
Returns a given default value, if the given key doesn't exist:, (*31)
echo $dot->get('user.name', 'some default value');
, (*32)
has()
Checks if a given key exists (returns boolean true or false):, (*33)
$dot->has('user.name');
// ArrayAccess
isset($dot['user.name']);
Multiple keys:, (*34)
$dot->has([
'user.name',
'page.title'
]);
, (*35)
isEmpty()
Checks if a given key is empty (returns boolean true or false):, (*36)
$dot->isEmpty('user.name');
// ArrayAccess
empty($dot['user.name']);
// Equivalent vanilla PHP
empty($array['user']['name']);
Multiple keys:, (*37)
$dot->isEmpty([
'user.name',
'page.title'
]);
Checks the whole Dot object:, (*38)
$dot->isEmpty();
, (*39)
merge()
Merges a given array or another Dot object:, (*40)
$dot->merge($array);
// Equivalent vanilla PHP
array_merge($originalArray, $array);
Merges a given array or another Dot object with the given key:, (*41)
$dot->merge('user', $array);
// Equivalent vanilla PHP
array_merge($originalArray['user'], $array);
, (*42)
mergeRecursive()
Recursively merges a given array or another Dot object:, (*43)
$dot->mergeRecursive($array);
// Equivalent vanilla PHP
array_merge_recursive($originalArray, $array);
Recursively merges a given array or another Dot object with the given key:, (*44)
$dot->mergeRecursive('user', $array);
// Equivalent vanilla PHP
array_merge_recursive($originalArray['user'], $array);
, (*45)
mergeRecursiveDistinct()
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):, (*46)
$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., (*47)
$dot->mergeRecursiveDistinct('user', $array);
, (*48)
pull()
Returns the value of a given key and deletes the key:, (*49)
echo $dot->pull('user.name');
// Equivalent vanilla PHP < 7.0
echo isset($array['user']['name']) ? $array['user']['name'] : null;
unset($array['user']['name']);
// Equivalent vanilla PHP >= 7.0
echo $array['user']['name'] ?? null;
unset($array['user']['name']);
Returns a given default value, if the given key doesn't exist:, (*50)
echo $dot->pull('user.name', 'some default value');
Returns all the stored items as an array and clears the Dot object:, (*51)
$items = $dot->pull();
, (*52)
push()
Pushes a given value to the end of the array in a given key:, (*53)
$dot->push('users', 'John');
// Equivalent vanilla PHP
$array['users'][] = 'John';
Pushes a given value to the end of the array:, (*54)
$dot->push('John');
// Equivalent vanilla PHP
$array[] = 'John';
, (*55)
replace()
Replaces the values with values having the same keys in the given array or Dot object:, (*56)
$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:, (*57)
$dot->merge('user', $array);
// Equivalent vanilla PHP
array_replace($originalArray['user'], $array);
replace() is not recursive., (*58)
, (*59)
set()
Sets a given key / value pair:, (*60)
$dot->set('user.name', 'John');
// ArrayAccess
$dot['user.name'] = 'John';
// Equivalent vanilla PHP
$array['user']['name'] = 'John';
Multiple key / value pairs:, (*61)
$dot->set([
'user.name' => 'John',
'page.title' => 'Home'
]);
, (*62)
setArray()
Replaces all items in Dot object with a given array:, (*63)
$dot->setArray($array);
, (*64)
setReference()
Replaces all items in Dot object with a given array as a reference and all future changes to Dot will be made directly to the original array:, (*65)
$dot->setReference($array);
, (*66)
toJson()
Returns the value of a given key as JSON:, (*67)
echo $dot->toJson('user');
Returns all the stored items as JSON:, (*68)
echo $dot->toJson();
Contributing
Pull Requests
- 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
It is very important to separate new features or improvements into separate feature branches, and to send a pull request for each branch. This allows me to review and pull in new features or improvements individually., (*69)
Style Guide
All pull requests must adhere to the PSR-12 standard., (*70)
Unit Testing
All pull requests must be accompanied by passing unit tests and complete code coverage. Dot uses PHPUnit for testing., (*71)
Static Analysis
All pull requests must pass static analysis using PHPStan., (*72)
License
MIT license, (*73)
Wallogit.com
