PHP dot notation array access

0.1.0 2018-02-15 12:21 UTC

README

Based on adbario/php-dot-notation package

Easy access to multidimensional arrays with dot notation. With dot notation, your code is cleaner and handling deeper arrays is super easy.

This class implements PHP's ArrayAccess class, so Dot object can also be used the same way as normal arrays with additional dot notation.

With Dot you can change this:

echo $data['info']['home']['address'];

to this:

echo $data->get('info.home.address');

or even this:

echo $data['info.home.address'];

Installation

Via composer:

composer require adbario/php-dot-notation

Or just copy the class file Dot.php and handle namespace yourself.

With Composer:

composer require adbario/php-dot-notation

Manual installation:

  1. Download the latest release
  2. Extract the files into your project
  3. require_once '/path/to/php-dot-notation/src/Dot.php';

Usage

This array will be used as a reference on this guide:

$array = [
    'user' => [
        'firstname' => 'John',
        'lastname'  => 'Smith'
    ],
    'info' => [
        'kids' => [
            0 => 'Laura',
            1 => 'Chris',
            2 => 'Little Johnny'
        ],
        'home' => [
            'address' => 'Rocky Road 3'
        ]
    ]
];

Create a Dot object

To start with an empty array, just create a new Dot object:

$data = new \Adbar\Dot;

If you have an array already available, inject it to the Dot object:

$data = new \Adbar\Dot($array);

Set an array after creating the Dot object:

$data->setArray($array);

Set an array as a reference, and all changes will be made directly to the original array:

$data->setReference($array);

Set a value

Set i.e. a phone number in the 'home' array:

$data->set('info.home.tel', '09-123-456-789');

// Array style
$data['info.home.tel'] = '09-123-456-789';

Set multiple values at once:

$data->set([
    'user.haircolor'    => 'blue',
    'info.home.address' => 'Private Lane 1'
]);

If the value already exists, Dot will override it with a new value.

Get a value

echo $data->get('info.home.address');

// Default value if the path doesn't exist
echo $data->get('info.home.country', 'some default value');

// Array style
echo $data['info.home.address'];

Get all the stored values:

$values = $data->all();
``

Get a value from a path and remove it:

```php
$address = $data->pull('home.address');

Get all the stored values and remove them:

$values = $data->pull();

Add a value

$data->add('info.kids', 'Amy');

Multiple values at once:

$data->add('info.kids', [
    'Ben', 'Claire'
]);

Check if a value exists

if ($data->has('info.home.address')) {
    // Do something...
}

// Array style
if (isset($data['info.home.address'])) {
    // Do something...
}

Delete a value

$data->delete('info.home.address');

// Array style
unset($data['info.home.address']);

Multiple values at once:

$data->delete([
    'user.lastname', 'info.home.address'
]);

Clear values

Delete all the values from a path:

$data->clear('info.home');

Clear multiple paths at once:

$data->clear([
    'user', 'info.home'
]);

Clear all data:

$data->clear();

Sort the values

You can sort the values of a given path or all the stored values.

Sort the values of a path:

$kids = $data->sort('info.kids');

// Sort recursively
$info = $data->sort('info');

Sort all the values

$sorted = $data->sort();

// Sort recursively
$sorted = $data->sort();

Magic methods

Magic methods can be used to handle single level data (without dot notation). These examples are not using the same data array as examples above.

Set a value:

$data->name = 'John';

Get a value:

echo $data->name;

Check if a value exists:

if (isset($data->name)) {
    // Do something...
}

Delete a value:

unset($data->name);

License

MIT license