setnemo/asterisk-notation

Asterisk notation for array access in PHP

0.1.2 2021-09-19 20:18 UTC

Requires

• php: ^7.4|~8.0.0
• ext-json: *
• adbario/php-dot-notation: ^2.2

Requires (Dev)

• codeception/codeception: ^4.1
• codeception/module-asserts: ^1.0.0
• codeception/module-phpbrowser: ^1.0.0
• squizlabs/php_codesniffer: *
• vimeo/psalm: ^4.7

MIT

• setnemo

README

Asterisk notation for array access in PHP. Update array access to the next level of usability.

Asterisk notation

use Setnemo\Asterisk;

$items = new Asterisk([
    'Europe' => [
        'Ukraine' => [
            'capital' => 'Kyiv',
            'currency' => 'UAH'
        ],
        'Poland' => [
            'capital' => 'Warsaw',
            'currency' => 'PLN'
        ],

    ],
    'Africa' => [
        'South Africa' => [
            'capital' => 'Capetown',
            'currency' => 'ZAR'
        ],
        'Nigeria' => [
            'capital' => 'Abuja',
            'currency' => 'NGN'
        ],
    ],
]);
$city = 'Kyiv';
$resultTrue = $items->has('*.*.capital', $city);
$resultFalse = $items->has('Africa.*.capital', $city);
if ($resultTrue === true && $resultFalse === false) {
    echo "Wow! It works correctly!";
}

Install

Install the latest version using Composer:

composer require setnemo/asterisk-notation

Usage

Create a new \Setnemo\Asterisk object:

use Adbar\Dot;
use Setnemo\Asterisk;
$asterisk = new Asterisk;
$array = ['first_one' => ['second' => 'value'], 'first_two' => ['second' => 'value'],];
// With existing array
$asterisk = new Asterisk($array);
// With existing \Adbar\Dot
$dot = new Dot($array);
$asterisk = new Asterisk($dot);
// or existing Asterisk
$newAsterisk = new Asterisk($asterisk);

Methods

Asterisk has the following methods:

• add()
• all()
• clear()
• count()
• delete()
• flatten()
• get()
• has()
• isEmpty()
• merge()
• mergeRecursive()
• mergeRecursiveDistinct()
• pull()
• push()
• replace() // use Dot::replace(), need write tests, because used get(), set()
• set()
• setArray()
• setReference()
• toJson() // use Dot::toJson(), need write tests, because used get()

add()

Using for adding element with asterisk in key

Work like Adbar\Dot::add()

all()

Work like Adbar\Dot::all()

clear()

Deletes the contents of a given key (sets an empty array):

$asterisk->clear('department.*.write_rules');

// Equivalent vanilla PHP
$array['department']['project1']['write_rules'] = [];
$array['department']['project2']['write_rules'] = [];
$array['department']['projectN']['write_rules'] = [];

Multiple keys:

$asterisk->clear(['department.*.write_rules', 'department.*.read_rules']);

All the stored items:

$asterisk->clear();

// Equivalent vanilla PHP
$array = [];

If key not contains * (asterisk) - it works like Adbar\Dot::clear()

count()

Returns the number of items in a given key:

$asterisk->count('user.siblings');

Items in the root of Dot object:

$asterisk->count();

// Or use count() function as Dot implements Countable
count($asterisk);

If key not contains * (asterisk) - it works like Adbar\Dot::count()

delete()

Deletes the given key:

$asterisk->delete('*.name');

// ArrayAccess
unset($asterisk['user1.name']);
unset($asterisk['user2.name']);

// Equivalent vanilla PHP
unset($array['user1']['name']);
unset($array['user2']['name']);

Multiple keys:

$asterisk->delete([
    '*.name',
    '*.title'
]);

flatten()

It works like Adbar\Dot::flatten()

get()

Returns the value of a given key:

$result = $asterisk->get('*.name'));

// ArrayAccess
$result['user1.name'] = $asterisk['user1.name'];
$result['user2.name'] = $asterisk['user2.name'];

// Equivalent vanilla PHP 
if (isset($array['user1']['name']) {
    $result['user1.name'] = $array['user1']['name'];
}
if (isset($array['user1']['name']) {
    $result['user2.name'] = $array['user2']['name'];
}

Returns a given default value, if the given key doesn't exist:

echo $asterisk->get('user.name', 'some default value');

Default value not work with asterisk

has()

Checks if a given key exists (returns boolean true or false):

$asterisk->has('user.name');

// ArrayAccess
isset($asterisk['user.name']);

Multiple keys:

$asterisk->has([
    'user.name',
    'page.title'
]);

With asterisk:

$asterisk = new \Setnemo\Asterisk(['1' => ['second' => 'value'],'2' => ['second' => 'value']]);
$asterisk->has('*.second'); // true
$asterisk = new \Setnemo\Asterisk(['1' => ['first' => ['test' => 42]],'2' => ['second' => 'value'],'3' => ['third' => ['value' => 42]]]);
$asterisk->has('*.*.value'); // true
$asterisk = new \Setnemo\Asterisk(['user1' => ['name' => 'John', 'job' => 'warrior'], 'user2' => ['name' => 'Robin', 'job' => 'archer']);
$asterisk->has('*.spouse'); // false

With asterisk and value:

$asterisk = new \Setnemo\Asterisk([]);
$asterisk->has('*', false); // false
$asterisk = new \Setnemo\Asterisk(['*' => ['second' => 'VALUE']]);
$asterisk->has('*.second', 'VALUE'); // true
$asterisk->has('*.second', 'value'); // false because lowercase
$asterisk = new \Setnemo\Asterisk(['*' => ['second' => 'value'], 0 => [0 => 0], 11 => 11]);
$asterisk->has('*.11', 11); // true
$asterisk = new \Setnemo\Asterisk(['1' => ['second' => 'value'],'2' => ['second' => '-']]);
$asterisk->has('*.second', 'value'); // false because 'second' => '-'
$asterisk = new \Setnemo\Asterisk(['1' => ['second' => 'value'],'2' => ['second' => 'value']]);
$asterisk->has('*.second', 'value'); // true

With asterisk and value (non-strict mode):

$asterisk = new \Setnemo\Asterisk([
'locations' => [
    'Europe' => [
        'Ukraine' => [
            'capital' => 'Kyiv',
            'currency' => 'UAH'
        ],
        'Poland' => [
            'capital' => 'Warsaw',
            'currency' => 'PLN'
        ],

    ],
    'Africa' => [
        'South Africa' => [
            'capital' => 'Capetown',
            'currency' => 'ZAR'
        ],
        'Nigeria' => [
            'capital' => 'Abuja',
            'currency' => 'NGN'
        ],
    ],
]]);
// third parameter is false for non-strict mode
$asterisk->has('locations.*.*.capital', 'Kyiv', false); // true
$asterisk->has('locations.*.*.currency', 'ZAR', false); // true
$asterisk->has('locations.Europe.*.currency', 'ZAR', false); // false

isEmpty()

Checks if a given key is empty (returns boolean true or false):

$asterisk->isEmpty('user.name');

// ArrayAccess
empty($asterisk['user.name']);

// Equivalent vanilla PHP
empty($array['user']['name']);

Multiple keys:

$asterisk->isEmpty([
    'user.name',
    'page.title'
]);

Checks the whole Asterisk object:

$asterisk->isEmpty();

Also works with asterisk in key:

$asterisk = new \Setnemo\Asterisk(['user1' => ['name' => 'John'], 'user2' => ['name' => 'Robin']);
$asterisk->isEmpty('*.name'); // false
$asterisk->isEmpty('*.spouse'); // true

merge()

It works like Adbar\Dot::merge() Asterisk in path Asterisk::merge('key', 'value') work like Asterisk::set('key', 'value', false)

mergeRecursive()

It works like Adbar\Dot::mergeRecursive() Asterisk in path Asterisk::mergeRecursive('key', 'value') work like Asterisk::set('key', 'value', false)

mergeRecursiveDistinct()

It works like Adbar\Dot::mergeRecursiveDistinct()

pull()

Returns the value of a given key and deletes the key:

echo $asterisk->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:

echo $asterisk->pull('user.name', 'some default value');

Default value not work with asterisk in query!

Returns all the stored items as an array and clears the Dot object:

$items = $asterisk->pull();

Key with asterisk:

$asterisk = new \Setnemo\Asterisk([['user1' => ['name' => 'John', 'job' => 'warrior'], 'user2' => ['name' => 'Robin', 'job' => 'archer'],]]);
$result = $asterisk->pull('*.name'); // ['user1.name' => 'John', 'user2.name' => 'Robin']
$all = $asterisk->all(); // ['user1' => ['job' => 'warrior'], 'user2' => ['job' => 'archer'],]
 

push()

Pushes a given value to the end of the array in a given key:

$asterisk->push('users', 'John');

// Equivalent vanilla PHP
$array['users'][] = 'John';

Pushes a given value to the end of the array:

$asterisk->push('John');

// Equivalent vanilla PHP
$array[] = 'John';

With asterisk:

$asterisk = new \Setnemo\Asterisk([
    'first_one' => ['second' => 'value'],
    'first_two' => ['second' => 'value']
]);
$asterisk->push('*.second', 'John');

$asterisk->all();
/*
[
    'first_one' => ['second' => ['value','VALUE']],
    'first_two' => ['second' => ['value','VALUE']]
]
 */

Also work as Asterisk::set('key', 'value', true), where true is asterisk boolean. See Asterisk::set()

replace()

It works like Adbar\Dot::replace()

set()

Sets a given key / value pair:

$asterisk->set('user.name', 'John');

// ArrayAccess
$asterisk['user.name'] = 'John';

// Equivalent vanilla PHP
$array['user']['name'] = 'John';

Multiple key / value pairs:

$asterisk->set([
    'user.name' => 'John',
    'page.title'     => 'Home'
]);

setArray()

It works like Adbar\Dot::setarray()

setReference()

It works like Adbar\Dot::setreference()

toJson()

It works like Adbar\Dot::toJson()

License

MIT license