https://github.com/setnemo/asterisk-notation
Asterisk notation for array access in PHP
https://github.com/setnemo/asterisk-notation
arrays asterisk asterisk-notation hacktoberfest notation php php74 php8
Last synced: about 2 months ago
JSON representation
Asterisk notation for array access in PHP
- Host: GitHub
- URL: https://github.com/setnemo/asterisk-notation
- Owner: setnemo
- License: mit
- Created: 2021-08-09T20:59:48.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2021-10-09T11:06:38.000Z (over 4 years ago)
- Last Synced: 2025-03-11T11:13:28.187Z (12 months ago)
- Topics: arrays, asterisk, asterisk-notation, hacktoberfest, notation, php, php74, php8
- Language: PHP
- Homepage:
- Size: 43.9 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# PHP Asterisk Notation
[](https://github.com/setnemo/asterisk-notation/releases)
[](//github.com/setnemo/asterisk-notation/actions)
[](https://sonarcloud.io/component_measures/metric/coverage/list?id=setnemo_asterisk-notation)
[](https://sonarcloud.io/component_measures/metric/reliability_rating/list?id=setnemo_asterisk-notation)
[](https://sonarcloud.io/component_measures/metric/security_rating/list?id=setnemo_asterisk-notation)
[](https://sonarcloud.io/component_measures/metric/bugs/list?id=setnemo_asterisk-notation)
[](https://sonarcloud.io/component_measures/metric/code_smells/list?id=setnemo_asterisk-notation)
[](https://packagist.org/packages/setnemo/asterisk-notation)
Asterisk notation for array access in PHP. Update array access to the next level of usability.
## Asterisk notation
```php
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:
```bash
composer require setnemo/asterisk-notation
```
## Usage
Create a new \Setnemo\Asterisk object:
```php
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()](#add)
- [all()](#all)
- [clear()](#clear)
- [count()](#count)
- [delete()](#delete)
- [flatten()](#flatten)
- [get()](#get)
- [has()](#has)
- [isEmpty()](#isempty)
- [merge()](#merge)
- [mergeRecursive()](#mergerecursive)
- [mergeRecursiveDistinct()](#mergerecursivedistinct)
- [pull()](#pull)
- [push()](#push)
- [replace()](#replace) // use Dot::replace(), **need write tests**, because used get(), set()
- [set()](#set)
- [setArray()](#setarray)
- [setReference()](#setreference)
- [toJson()](#tojson) // use Dot::toJson(), **need write tests**, because used get()
Using for adding element with asterisk in key
> Work like [Adbar\Dot::add()](https://github.com/adbario/php-dot-notation#add)
> Work like [Adbar\Dot::all()](https://github.com/adbario/php-dot-notation#all)
Deletes the contents of a given key (sets an empty array):
```php
$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:
```php
$asterisk->clear(['department.*.write_rules', 'department.*.read_rules']);
```
All the stored items:
```php
$asterisk->clear();
// Equivalent vanilla PHP
$array = [];
```
> If key not contains * (asterisk) - it works like [Adbar\Dot::clear()](https://github.com/adbario/php-dot-notation#clear)
Returns the number of items in a given key:
```php
$asterisk->count('user.siblings');
```
Items in the root of Dot object:
```php
$asterisk->count();
// Or use count() function as Dot implements Countable
count($asterisk);
```
> If key not contains * (asterisk) - it works like [Adbar\Dot::count()](https://github.com/adbario/php-dot-notation#count)
Deletes the given key:
```php
$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:
```php
$asterisk->delete([
'*.name',
'*.title'
]);
```
> It works like [Adbar\Dot::flatten()](https://github.com/adbario/php-dot-notation#flatten)
Returns the value of a given key:
```php
$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:
```php
echo $asterisk->get('user.name', 'some default value');
```
> Default value not work with asterisk
Checks if a given key exists (returns boolean true or false):
```php
$asterisk->has('user.name');
// ArrayAccess
isset($asterisk['user.name']);
```
Multiple keys:
```php
$asterisk->has([
'user.name',
'page.title'
]);
```
With asterisk:
```php
$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:
```php
$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):
```php
$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
```
Checks if a given key is empty (returns boolean true or false):
```php
$asterisk->isEmpty('user.name');
// ArrayAccess
empty($asterisk['user.name']);
// Equivalent vanilla PHP
empty($array['user']['name']);
```
Multiple keys:
```php
$asterisk->isEmpty([
'user.name',
'page.title'
]);
```
Checks the whole Asterisk object:
```php
$asterisk->isEmpty();
```
Also works with asterisk in key:
```php
$asterisk = new \Setnemo\Asterisk(['user1' => ['name' => 'John'], 'user2' => ['name' => 'Robin']);
$asterisk->isEmpty('*.name'); // false
$asterisk->isEmpty('*.spouse'); // true
```
> It works like [Adbar\Dot::merge()](https://github.com/adbario/php-dot-notation#merge)
> Asterisk in path Asterisk::merge('key', 'value') work like Asterisk::set('key', 'value', false)
> It works like [Adbar\Dot::mergeRecursive()](https://github.com/adbario/php-dot-notation#mergeRecursive)
> Asterisk in path Asterisk::mergeRecursive('key', 'value') work like Asterisk::set('key', 'value', false)
> It works like [Adbar\Dot::mergeRecursiveDistinct()](https://github.com/adbario/php-dot-notation#mergeRecursiveDistinct)
Returns the value of a given key and deletes the key:
```php
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:
```php
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:
```php
$items = $asterisk->pull();
```
Key with asterisk:
```php
$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:
```php
$asterisk->push('users', 'John');
// Equivalent vanilla PHP
$array['users'][] = 'John';
```
Pushes a given value to the end of the array:
```php
$asterisk->push('John');
// Equivalent vanilla PHP
$array[] = 'John';
```
With asterisk:
```php
$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()](#set)
> It works like [Adbar\Dot::replace()](https://github.com/adbario/php-dot-notation#replace)
Sets a given key / value pair:
```php
$asterisk->set('user.name', 'John');
// ArrayAccess
$asterisk['user.name'] = 'John';
// Equivalent vanilla PHP
$array['user']['name'] = 'John';
```
Multiple key / value pairs:
```php
$asterisk->set([
'user.name' => 'John',
'page.title' => 'Home'
]);
```
> It works like [Adbar\Dot::setarray()](https://github.com/adbario/php-dot-notation#setarray)
> It works like [Adbar\Dot::setreference()](https://github.com/adbario/php-dot-notation#setreference)
> It works like [Adbar\Dot::toJson()](https://github.com/adbario/php-dot-notation#toJson)
## License
[MIT license](LICENSE.txt)