alaasarhan / php-flatten

php-flatten

A utility function to mainly flatten multidimensional-arrays and traversables into a one-dimensional array, preserving keys and joining them with a customizable separator to from fully-qualified keys in the final array.

Installation

  composer require sarhan/php-flatten

Usage

Example 1

use Sarhan\Flatten\Flatten;

$multiArray = [
    'say' => 'what',
    'hi' => [ 'de' => 'Hallo', 'es' => 'Hola' ]
];

/*
Flatten::__construct(
    string $separator = '.',
    string $prefix = '',
    int $flags = 0
)
*/
$flatten = new Flatten();

// Flatten::flattenToArray is provided for convinience. It internally
// calls Flatten::flatten and converts it's output, which is a 1-dimensional
// iterator, into a 1-dimensional array.
$flattened = $flatten->flattenToArray($multiArray);

// Flatten::unflattenToArray is provided for convinience. It internally
// calls Flatten::unflatten and converts it's output, which is a recursive
// generator structure, into a multi-dimensional array.
$unflattened = $flatten->unflattenToArray($flattened);

assert($flattened == [
    'say' => what
    'hi.de' => Hallo
    'hi.es' => Hola
]);

assert($unflattened == $multiArray);

Example 2

Custom Separator and initial prefix

use Sarhan\Flatten\Flatten;

$allowAccess = [
    'root' => false,
    'var' => [ 'log' => ['nginx' => true, 'apt' => false], 'www' => true ],
];

$flatten = new Flatten(
  '/',  // separator
  '/'   // prefix
);

$flattened = $flatten->flattenToArray($allowAccess);

$unflattened = $flatten->unflattenToArray($flattened);

assert($flatten == [
    '/root' => false,
    '/var/log/nginx' => true,
    '/var/log/apt' => false,
    '/var/www' => true
]);

assert($unflattened == $allowAccess);

Example 3

Notice that the prefix will not be separated in FQkeys. If it should be separated, separator must be appeneded to the prefix string.

use Sarhan\Flatten\Flatten;

$api = [
    'category' => [ 'health' => 321, 'sport' => 769, 'fashion' => 888 ],
    'tag' => [ 'soccer' => 7124, 'tennis' => [ 'singles' => 9833, 'doubles' => 27127 ] ],
];

$flatten = new Flatten('/', 'https://api.dummyhost.domain/');

$flattened = $flatten->flattenToArray($api);

$unflattened = $flatten->unflattenToArray($flattened);

assert($flattened == [
    'https://api.dummyhost.domain/category/health' => 321,
    'https://api.dummyhost.domain/category/sport' => 769,
    'https://api.dummyhost.domain/category/fashion' => 888,
    'https://api.dummyhost.domain/tag/soccer' => 7124,
    'https://api.dummyhost.domain/tag/tennis/singles' => 9833,
    'https://api.dummyhost.domain/tag/tennis/doubles' => 27127
]);

assert($unflattened == $api);

Example 4

Numeric keys are treated as associative keys.

Note: This behavior can be changed using flags. See FLAG_NUMERIC_NOT_FLATTENED

use Sarhan\Flatten\Flatten;

$nutrition = [
    'nutrition',
    'fruits' => [ 'oranges', 'apple', 'banana' ],
    'veggies' => ['lettuce', 'broccoli'],
];

$flatten = new Flatten('-');

$flattened = $flatten->flattenToArray($nutrition);

$unflattened = $flatten->unflattenToArray($flattened);

assert($flattened == [
    '0' => 'nutrition',
    'fruits-0' => 'oranges',
    'fruits-1' => 'apple',
    'fruits-2' => 'banana',
    'veggies-0' => 'lettuce',
    'veggies-1' => 'broccoli'
]);

assert($unflattened == $nutrition);

Flags

FLAG_NUMERIC_NOT_FLATTENED

Turns off flattening values with numeric (integer) keys.

Those values will be wrapped in an array (preserving their keys) and associated to the parent FQK.

use Sarhan\Flatten\Flatten;

$examples = [
    'templates' => [
      ['lang' => 'js', 'template' => "console.log('%s');"],
      ['lang' => 'php', 'template' => 'echo "%s";']
    ],
    'values' => [3 => 'hello world', 5 => 'what is your name?']
];

$flatten = new Flatten(
  '.',
  'examples.',
  Flatten::FLAG_NUMERIC_NOT_FLATTENED
);

$flattened = $flatten->flattenToArray($examples);

$unflattened = $flatten->unflattenToArray($flattened);

assert($flattened == [
    'examples.templates' => [
        [
            'lang' => 'js',
            'template' => 'console.log(\'%s\')';
        ],
        [
            'lang' => 'php',
            'template' => 'echo "%s"'
        ]
    ],
    'examples.values' => [
        3 => 'hello world',
        5 => 'what is your name?'
    ]
]);

assert($unflattened == $examples);

Top level numeric (integer) keys will also be returned into an array assigned to the passed prefix.

use Sarhan\Flatten\Flatten;

$seats = [
  'A1',
  'A2',
  'B1',
  'B2',
  '_reserved' => ['A1', 'B1'],
  '_blocked' => ['B2']
];

$flatten = new Flatten(
  '_',
  'seats',
  Flatten::FLAG_NUMERIC_NOT_FLATTENED
);

$flattened = $flatten->flattenToArray($seats);

$unflattened = $flatten->unflattenToArray($flattened);

assert($flattened == [
    'seats' => ['A1', 'A2', 'B1', 'B2'],
    'seats_reserved' => ['A1', 'B1'],
    'seats_blocked' => ['B2']
]);

assert($unflattened == $seats);

php-flatten's Issues

Allow not flattening numeric-keys

• Add flags argument to flatten function to allow easy extendable.
• Add a constant flag, NUMERIC_NOT_FLATTENED that switches off flattening numeric keys, and instead keep them in an array variable as described below:

IS (without flag)

$flattened = Flatten::flatten([
    'numericOnly' => ['A', 'B', 'C', 'D'],
    'mixed' => [
        'hello world!',
        'js' => 'console.log("%s")',
        'php' => 'echo "%s"'
    ]
]);

/* print_r($flattened)
Array
(
    [numericOnly.0] => A
    [numericOnly.1] => B
    [numericOnly.2] => C
    [numericOnly.3] => D
    [mixed.0] => hello world!
    [mixed.js] => console.log("%s")
    [mixed.php] => echo "%s"
)
*/

SHOULD (with flag)

$flattened = Flatten::flatten([
    'numericOnly' => ['A', 'B', 'C', 'D'],
    'mixed' => [
        'hello world!',
        'js' => 'console.log("%s")',
        'php' => 'echo "%s"'
    ]
], Flatten::NUMERIC_NOT_FLATTENED);

/* print_r($flattened)
Array
(
    [numericOnly] => Array
        (
            [0] => A
            [1] => B
            [2] => C
            [3] => D
        )

    [mixed] => Array
        (
            [0] => hello world!
        )

    [mixed.js] => console.log("%s")
    [mixed.php] => echo "%s"
)
*/

• Cover with tests
• Update documentation and README.md accordingly.
• Adjust minor version, and create a release

Add License

License library under LGPL

release new version for php8?

Hi,
We are happy to see the master branch changing config of composer for compatible with PHP8.
Is going to release the new version with this changed recently?

 We are very appreciate and need your help.
 thanks.

Empty array is added when there's no numeric (keys) and FLAG_NUMERIC_NOT_FATTENED is used

In the following snippet:

use Sarhan\Flatten;

$var = [
   'a' => 'A',
   'b' => 'B',
   'c' => [ 'd' => 'D' ]
];

$flattened = Flatten::flatten($var, '.', '', Flatten::FLAG_NUMERIC_NOT_FLATTENED);

$flattened IS:

print_r($flattened);
/*
Array
(
    [] => Array
        (
        )

    [a] => A
    [b] => B
    [c] => Array
        (
        )

    [c.d] => D
)
*/

while it SHOULD BE:

print_r($flattened);
/*
Array
(
    [a] => A
    [b] => B
    [c.d] => D
)
*/

Configure Travis

Fix namespace

Currently PSR-4 namespace configuration for this library is setup at the very root Sarhan\. That's less optimal for other libraries under same root.

This need to be reconfigured to start with Sarhan\Flatten pointing to the right source instead.

Make methods non static

Flatten::flatten is a static function, but should be made non static and instances of flatten should be instantiated first with configuration variables (current arguments).

Add reverse flattening function to Flatten class

This function, when called on a flattened result, should produce an output equal to the original input that has been flattened using Flatten::flatten function.