JBZoo Data

Extended implementation of ArrayObject.

Really useful objects for any config in your system (write, read, store, change, validate, convert to other format and etc).

Install

composer require jbzoo/data:"1.x-dev"  # Last version
composer require jbzoo/data            # Stable version

Comparing the useful for every day

Action	JBZoo/Data (ArrayObject)	Simple PHP Array
Create	$d = new Data($someData)	$ar = [/* ... */];
Supported formats	Array, Object, ArrayObject, JSON, INI, Yml	Array only
Load form file	with array, ini, yml, json, serialized	-
Get value or default	$d->get('key', 42)	array_key_exists('k', $ar) ? $ar['k'] : 42
Get undefined #1	$d->get('undefined')	@$ar['undefined'] (@ is bad idea!)
Get undefined #2	$d->find('undefined')	isset($ar['und']) ? $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)	-
Compare #1	$d->get('key') === $someVar	$ar['key'] === $someVar
Compare #2	$d->is('key', $someVar)	-
Compare #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 #1	isset($d['key'])	isset($ar['key'])
Isset #2	isset($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']
Nested key #2	$d->inner['inner']['prop']	-
Nested key #3	$d['inner']['inner']['prop']	-
Export to Serialized	echo (new Data([/* ... */]))	echo serialize([/* ... */])
Export to JSON	echo (new JSON([/* ... */])) (readable)	echo json_encode([/* ... */])
Export to Yml	echo (new Yml ([/* ... */])) (readable)	-
Export to Ini	echo (new Ini([/* ... */])) (readable)	-
Export to PHP Code	echo (new PHPArray ([/* ... */])) (readable)	-
Pretty JSON	+	-
Filters	+	-
Search	+	-
Flatten Recursive	+	-

Usage

Methods to create config object

require_once './vendor/autoload.php'; // composer autoload.php

// Get needed classes
namespace JBZoo\Data\Data; // And others

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

// Read
$config->get('key', 42);                   // Check exists and get parameter by key or return default value
$config['key'];                            // Like array
$config->key;                              // Like object
$config->find('very.deep.config.key', 42); // Check and get $config['very']['deep']['config']['key'] or return default

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

// Isset
$config->has('key');        // Method
isset($config['key']);      // Like array
isset($config->key);        // Like object

// Unset
$config->remove('key');     // Method
unset($config['key']);      // Like array
unset($config->key);        // Like object

Filter values (required JBZoo/Utils)

List of filters - JBZoo/Utils/Filter

• bool - Converts many english words that equate to true or false to boolean.
• int - Smart filter for integer
• float - Smart filter for float
• digits - Only 0..9
• alpha - Only a..z
• alphanum - Only 0..9 and a..z
• base64 - Return only chars for base64
• path - Some path
• trim - Extend trim
• arr - Array filter
• cmd - Cleanup for system command
• email - Email or null
• strip - Strip tags
• alias - Sluggify
• low - String to lower (check mbstring)
• up - String to upper (check mbstring)
• clean - Safe string
• html - HTML escaping
• xml - XML escaping
• esc - Escape for UTF-8
• function($value) { return $value; } - Your custom callback function

$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

// 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.

Save to pretty format

echo $config;
$result = '' . $config;
$result = (string)$config;
$result = $config->write();
$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";}}}

Overhead on PHP 5.6.x

All benchmark tests are executing without xdebug and with big random array and 10 000 iterations.

For more details see the travis log and tests

Action	JBZoo/Data	ArrayObject	Simple PHP Array
Create - time	100%	24%	-
Create - memory	-	-	8%
Get by key - time	21%	-	5%
Get by key - memory	-	-	906%
Find nested defined var - time	41%	4%	-
Find nested defined var - memory	440%	-	940%
Find nested undefined var - time	22%	4%	-
Find nested undefined var - memory	-	-	-
Average time for 10 000 iterations!	68ms (+44%)	51ms (+9%)	47ms

Overhead on PHP 7.0.x

All benchmark tests are executing without xdebug and with big random array and 100 000 iterations.

For more details see the travis log and tests

Action	JBZoo/Data	ArrayObject	Simple PHP Array
Create - time	373%	161%	-
Create - memory	-	-	-
Get by key - time	90%	2%	-
Get by key - memory	-	-	-
Find nested defined var - time	-	28%	15%
Find nested defined var - memory	-	-	-
Find nested undefined var - time	-	22%	6%
Find nested undefined var - memory	-	-	-
Average time for 100 000 iterations!	77ms (+54%)	65ms (+30%)	50ms

Unit tests and check code style

composer update-all
composer test

License

MIT