Home

Awesome

JBZoo / Data

CI Coverage Status Psalm Coverage Psalm Level CodeFactor
Stable Version Total Downloads Dependents GitHub License

An extended version of the ArrayObject object for working with system settings or just for working with data arrays.

It provides a short syntax for daily routine, eliminates common mistakes. Allows you to work with various line and file formats - JSON, Yml, Ini, PHP arrays and simple objects.

<!--ts--> <!--te-->

Installation

composer require jbzoo/data

Usage

Comparison with pure PHP


ActionJBZoo/DataPure PHP way
Create$d = data($someData)$ar = [/* ... */];
Supported formatsArray, Object, ArrayObject, JSON, INI, YmlArray
Load form file*.php, *.ini, *.yml, *.json, serialized-
Get value or default$d->get('key', 42)$ar['key'] ?? 42
Get undefined #1$d->get('undefined') (no any notice)$ar['undefined'] ?? null
Get undefined #2$d->find('undefined')$ar['und'] ?? null
Get undefined #3$d->undefined === null (no any notice)-
Get undefined #4$d['undefined'] === null (no any notice)-
Get undefined #5$d['undef']['undef'] === null (no any notice)-
Comparing #1$d->get('key') === $someVar$ar['key'] === $someVar
Comparing #2$d->is('key', $someVar)-
Comparing #3$d->is('key', $someVar, true) (strict)-
Like array$d['key']$ar['key']
Like object #1$d->key-
Like object #2$d->get('key')-
Like object #3$d->find('key')-
Like object #4$d->offsetGet('key')-
Isset #1isset($d['key'])isset($ar['key'])
Isset #2isset($d->key)array_key_exists('key', $ar)
Isset #3$d->has('key')-
Nested key #1$d->find('inner.inner.prop', $default)$ar['inner']['inner']['prop'] (error?)
Nested key #2$d->inner['inner']['prop']-
Nested key #3$d['inner']['inner']['prop']-
Export to Serializedecho data([/* ... */])echo serialize([/* ... */])
Export to JSONecho (json([/* ... */])) (readable)echo json_encode([/* ... */])
Export to Ymlecho yml([/* ... */]) (readable)-
Export to Iniecho ini([/* ... */]) (readable)-
Export to PHP Codeecho phpArray([/* ... */]) (readable)-
JSON+-
Filters+-
Search+-
Flatten Recursive+-
Set Value$d['value'] = 42$ar['value'] = 42
Set Nested Value$d->set('q.w.e.r.t.y') = 42$ar['q']['w']['e']['r']['t']['y'] = 42
Set Nested Value (if it's undefined)$d->set('q.w.e.r.t.y') = 42PHP Notice errors...

Know your data

$json = json('{ "some": "thing", "number": 42 }');
dump($json->getSchema();
// [
//     "some" => "string",
//     "number" => "int"
// ]

Methods

use function JBZoo\Data\data;
use function JBZoo\Data\ini;
use function JBZoo\Data\json;
use function JBZoo\Data\phpArray;
use function JBZoo\Data\yml;

$config = data([/* Assoc Array */]);       // Any PHP-array or simple object, serialized data
$config = ini('./configs/some.ini');       // Load configs from ini file (or string, or simple array)
$config = yml('./configs/some.yml');       // Yml (or string, or simple array). Parsed with Symfony/Yaml Component.
$config = json('./configs/some.json');     // JSON File (or string, or simple array)
$config = phpArray('./configs/some.php');  // PHP-file that must return array

// Read
$config->get('key', 42);                   // Returns value if it exists oR returns default value
$config['key'];                            // As regular array
$config->key;                              // As regular object

// Read nested values without PHP errors
$config->find('deep.config.key', 42);      // Gets `$config['very']['deep']['config']['key']` OR returns default value

// Write
$config->set('key', 42);
$config['key'] = 42;
$config->key = 42;

// Isset
$config->has('key');
isset($config['key']);
isset($config->key);

// Unset
$config->remove('key');
unset($config['key']);
unset($config->key);

Filter values (required JBZoo/Utils)

List of filters - JBZoo/Utils/Filter

$config->get('key', 42, 'int');         // Smart converting to integer
$config->find('key', 42, 'float');      // To float
$config->find('no', 'yes', 'bool');     // Smart converting popular word to boolean value
$config->get('key', 42, 'strip, trim'); // Chain of filters

// Your custom handler
$config->get('key', 42, function($value) {
    return (float)str_replace(',', '.', $value);
});

Utility methods

$config->search($needle);       // Find a value also in nested arrays/objects
$config->flattenRecursive();    // Return flattened array copy. Keys are <b>NOT</b> preserved.

Export to pretty-print format

echo $config;

$result = '' . $config;
$result = (string)$config;
$result = $config->__toString();

Example of serializing the JSON object

{
    "empty": "",
    "zero": "0",
    "string": " ",
    "tag": "<a href=\"http:\/\/google.com\">Google.com<\/a>",
    "array1": {
        "0": "1",
        "1": "2"
    },
    "section": {
        "array2": {
            "0": "1",
            "12": "2",
            "3": "3"
        }
    },
    "section.nested": {
        "array3": {
            "00": "0",
            "01": "1"
        }
    }
}

Example of serializing the PHPArray object

<?php

return array(
    'empty' => '',
    'zero' => '0',
    'string' => ' ',
    'tag' => '<a href="http://google.com">Google.com</a>',
    'array1' => array(
        0 => '1',
        1 => '2',
    ),
    'section' => array(
        'array2' => array(
            0 => '1',
            12 => '2',
            3 => '3',
        ),
    ),
    'section.nested' => array(
        'array3' => array(
            '00' => '0',
            '01' => '1',
        ),
    ),
);

Example of serializing the Yml object

empty: ''
zero: '0'
string: ' '
tag: '<a href="http://google.com">Google.com</a>'
array1:
    - '1'
    - '2'
section:
    array2: { 0: '1', 12: '2', 3: '3' }
section.nested:
    array3: ['0', '1']

Example of serializing the Ini object

empty = ""
zero = "0"
string = " "
tag = "<a href=\"http://google.com\">Google.com</a>"
array1[0] = "1"
array1[1] = "2"

[section]
array2[0] = "1"
array2[12] = "2"
array2[3] = "3"

[section.nested]
array3[00] = "0"
array3[01] = "1"

Example of serializing the Data object

a:7:{s:5:"empty";s:0:"";s:4:"zero";s:1:"0";s:6:"string";s:1:" ";s:3:"tag";s:42:"<a href="http://google.com">Google.com</a>";s:6:"array1";a:2:{i:0;s:1:"1";i:1;s:1:"2";}s:7:"section";a:1:{s:6:"array2";a:3:{i:0;s:1:"1";i:12;s:1:"2";i:3;s:1:"3";}}s:14:"section.nested";a:1:{s:6:"array3";a:2:{s:2:"00";s:1:"0";s:2:"01";s:1:"1";}}}

Summary benchmark info (execution time) PHP v7.4

All benchmark tests are executing without xdebug and with a huge random array and 100.000 iterations.

Benchmark tests based on the tool phpbench/phpbench. See details here.

Please, pay attention - 1μs = 1/1.000.000 of second!

benchmark: CreateObject

subjectgroupsitsrevsmeanstdevrstdevmem_realdiff
benchArrayObjectOrigNative,ArrayObject31000007.30μs0.01μs0.18%8,388,608b1.00x
benchArrayObjectExtOrigNative,ArrayObject,Extended31000007.43μs0.05μs0.66%8,388,608b1.02x
benchJsonJSON31000007.55μs0.01μs0.15%8,388,608b1.03x
benchIniIni31000007.55μs0.01μs0.15%8,388,608b1.03x
benchDataData31000007.57μs0.03μs0.41%8,388,608b1.04x
benchIniFuncIni,Func31000007.62μs0.01μs0.10%8,388,608b1.04x
benchDataFuncData,Func31000007.63μs0.01μs0.19%8,388,608b1.05x
benchYmlYml31000007.63μs0.10μs1.36%8,388,608b1.05x
benchJsonFuncJSON,Func31000007.64μs0.01μs0.11%8,388,608b1.05x
benchPhpArrayPhpArray31000007.65μs0.03μs0.44%8,388,608b1.05x
benchYmlFuncYml,Func31000007.70μs0.05μs0.60%8,388,608b1.05x
benchPhpArrayFuncPhpArray,Func31000007.75μs0.06μs0.72%8,388,608b1.06x

benchmark: GetUndefinedValue

subjectgroupsitsrevsmeanstdevrstdevmem_realdiff
benchArrayIssetNative,Array,Undefined310000000.04μs0.00μs1.48%8,388,608b1.00x
benchDataOffsetGetData,Undefined310000000.11μs0.00μs0.41%8,388,608b2.88x
benchDataGetData,Undefined310000000.14μs0.00μs0.39%8,388,608b3.56x
benchDataArrayData,Undefined310000000.14μs0.00μs0.08%8,388,608b3.72x
benchDataArrowData,Undefined310000000.15μs0.00μs0.34%8,388,608b3.86x
benchArrayRegularMutedNative,Array,Undefined310000000.19μs0.00μs0.04%8,388,608b4.99x
benchDataFindData,Undefined310000000.37μs0.00μs0.11%8,388,608b9.69x
benchDataFindInnerData,Undefined310000000.41μs0.00μs0.14%8,388,608b10.86x

benchmark: GetValue

subjectgroupsitsrevsmeanstdevrstdevmem_realdiff
benchArrayRegularNative,Array310000000.04μs0.00μs5.02%8,388,608b1.00x
benchArrayRegularMutedNative,Array310000000.04μs0.00μs1.40%8,388,608b1.06x
benchArrayIssetNative,Array310000000.04μs0.00μs2.04%8,388,608b1.07x
benchArrayObjectArrayNative,ArrayObject310000000.05μs0.00μs1.07%8,388,608b1.14x
benchArrayObjectArrayExtNative,ArrayObject,Extended310000000.05μs0.00μs0.24%8,388,608b1.19x
benchArrayObjectOffsetGetNative,ArrayObject310000000.07μs0.00μs1.35%8,388,608b1.77x
benchArrayObjectExtOffsetGetNative,ArrayObject,Extended310000000.08μs0.00μs0.23%8,388,608b1.86x
benchDataOffsetGetData310000000.16μs0.00μs0.28%8,388,608b4.01x
benchDataArrayData310000000.20μs0.00μs0.17%8,388,608b4.96x
benchDataArrowData310000000.21μs0.00μs0.21%8,388,608b5.07x
benchDataGetData310000000.28μs0.00μs0.21%8,388,608b6.95x
benchDataFindData310000000.35μs0.00μs0.65%8,388,608b8.52x

benchmark: GetValueInner

subjectgroupsitsrevsmeanstdevrstdevmem_realdiff
benchArrayRegularNative,Array310000000.05μs0.00μs0.23%8,388,608b1.00x
benchArrayRegularMutedNative,Array310000000.06μs0.00μs0.86%8,388,608b1.06x
benchArrayIssetNative,Array310000000.06μs0.00μs0.27%8,388,608b1.08x
benchArrayObjectArrayExtNative,ArrayObject,Extended310000000.06μs0.00μs0.76%8,388,608b1.14x
benchArrayObjectArrayNative,ArrayObject310000000.07μs0.00μs1.39%8,388,608b1.22x
benchDataFindData310000000.81μs0.01μs1.06%8,388,608b15.22x

Unit tests and check code style

make update
make test-all

License

MIT

See Also