Skip to content

About

Read and write nested PHP arrays with dot notation.

Topics

Resources

Stars

461 stars

Watchers

14 watching

Forks

Repository files navigation

PHP Dot Notation

ci Coverage Stable PHP Downloads LicensePHPStan

About Dot

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 too

Install

Install the latest version using Composer:

composer require adbario/php-dot-notation

Usage

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 Dot

Methods

Dot has the following methods:

add()

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'
]);

all()

Returns all the stored items as an array:

$values = $dot->all();

clear()

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 = [];

count()

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);

delete()

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'
]);

flatten()

Returns a flattened array with the keys delimited by a given character (default "."):

$flatten = $dot->flatten();

get()

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');

has()

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'
]);

isEmpty()

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

merge()

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);

mergeRecursive()

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);

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):

$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);

pull()

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

push()

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.

replace()

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.

set()

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'
]);

setArray()

Replaces all items in the Dot object with a given array:

$dot->setArray($array);

setReference()

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);

toJson()

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);

Contributing

Pull Requests

  1. Fork the Dot repository
  2. Create a new branch for each feature or improvement
  3. 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.

Style Guide

All pull requests must adhere to the PSR-12 standard.

Unit Testing

All pull requests must be accompanied by passing unit tests and complete code coverage. Dot uses PHPUnit for testing.

Static Analysis

All pull requests must pass static analysis using PHPStan.

License

MIT license

About

Read and write nested PHP arrays with dot notation.

Topics

Resources

Stars

461 stars

Watchers

14 watching

Forks

Releases

Packages

Used by

Contributors

Languages