windwalker/structure

Windwalker Structure package

Windwalker Structure

Windwalker Structure is a storage of nested array or object, help us manage multi-level structures data., _(*1)

Installation via Composer

Add this to the require block in your composer.json., _(*2)

``` json { "require": { "windwalker/structure": "~3.0" } }, <sub>(*3)</sub>

## Supported Formats

- JSON
- PHP file (return array or class)
- JSON
- [HJSON](https://hjson.org/)
- YAML
- [TOML](https://github.com/toml-lang/toml)
- XML
- INI

## Getting Started

``` php
use Windwalker\Structure\Structure;

$structure = new Structure;

// Set a value in the structure.
$structure->set('foo', 'bar');

// Get a value from the structure;
$value = $structure->get('foo');

Load config by Structure

``` php use Windwalker\Structure\Structure;, <sub>(*4)</sub>

$structure = new Structure;, <sub>(*5)</sub>

// Load by string $structure->loadString('{"foo" : "bar"}');, <sub>(*6)</sub>

$structure->loadString('', 'xml');, <sub>(*7)</sub>

// Load by object or array $structure->load($object);, <sub>(*8)</sub>

// Load by file $structure->loadFile($root . '/config/config.json', 'json');, <sub>(*9)</sub>

## Accessing a Structure by getter & setter

### Get value

``` php
$structure->get('foo');

// Get a non-exists value and return default
$structure->get('foo', 'default');

// OR

$structure->get('foo') ?: 'default';

Set value

``` php // Set value $structure->set('bar', $value);, <sub>(*10)</sub>

// Sets a default value if not already assigned. $structure->def('bar', $default);, <sub>(*11)</sub>

### Accessing children value by path

``` php
$json = '{
    "parent" : {
        "child" : "Foo"
    }
}';

$structure = new Structure($json);

$structure->get('parent.child'); // return 'Foo'

$structure->set('parent.child', $value);

Append & Prepend

Support push / pop / shift / unshift methods., <sub>(*12)</sub>

``` php $structure->set('foo.bar', array('fisrt', 'second'));, <sub>(*13)</sub>

$structure->push('foo.bar', 'third');, <sub>(*14)</sub>

$structure->get('foo.bar'); // Result: Array(first, second, third), <sub>(*15)</sub>

### Use other separator

``` php
$structure->setSeparator('/');

$data = $structure->get('foo/bar');

Accessing a Structure as an Array

The Structure class implements ArrayAccess so the properties of the structure can be accessed as an array. Consider the following examples:, <sub>(*16)</sub>

``` php // Set a value in the structure. $structure['foo'] = 'bar';, <sub>(*17)</sub>

// Get a value from the structure; $value = $structure['foo'];, <sub>(*18)</sub>

// Check if a key in the structure is set. if (isset($structure['foo'])) { echo 'Say bar.'; }, <sub>(*19)</sub>

## Merge Structure

#### Using load* methods to merge two config files.

``` php
$json1 = '{
    "field" : {
        "keyA" : "valueA",
        "keyB" : "valueB"
    }
}';

$json2 = '{
    "field" : {
        "keyB" : "a new valueB"
    }
}';

$structure->loadString($json1);
$structure->loadString($json2);

Output, <sub>(*20)</sub>

Array(
    field => Array(
        keyA => valueA
        keyB => a new valueB
    )
)

Merge Another Structure

``` php $object1 = '{ "foo" : "foo value", "bar" : { "bar1" : "bar value 1", "bar2" : "bar value 2" } }';, <sub>(*21)</sub>

$object2 = '{ "foo" : "foo value", "bar" : { "bar2" : "new bar value 2" } }';, <sub>(*22)</sub>

$structure1 = new Structure(json_decode($object1)); $structure2 = new Structure(json_decode($object2));, <sub>(*23)</sub>

$structure1->merge($structure2);, <sub>(*24)</sub>

If you just want to merge first level, do not hope recursive:

``` php
$structure1->merge($structure2, false); // Set param 2 to false that Structure will only merge first level

Merge to a child node:, <sub>(*25)</sub>

``` php $structure->mergeTo('foo.bar', $anotherStructure);, <sub>(*26)</sub>

## Dump to file.

``` php
$structure->toString();

$structure->toString('xml');

$structure->toString('ini');

Dump to one dimension

``` php $array = array( 'flower' => array( 'sunflower' => 'light', 'sakura' => 'samurai' ) );, <sub>(*27)</sub>

$structure = new Structure($array);, <sub>(*28)</sub>

// Make data to one dimension, <sub>(*29)</sub>

$flatted = $structure->flatten();, <sub>(*30)</sub>

print_r($flatted);, <sub>(*31)</sub>

The result:

Array ( [flower.sunflower] => light [flower.sakura] => samurai ), <sub>(*32)</sub>

## Using YAML

Add Symfony YAML component in `composer.json`

``` json
{
    "require-dev": {
        "symfony/yaml": "^4.0||^5.0"
    }
}

Using yaml format, <sub>(*33)</sub>

``` php $structure->loadFile($yamlFile, 'yaml');, <sub>(*34)</sub>

$structure->loadString('foo: bar', 'yaml');, <sub>(*35)</sub>

// Convert to string $structure->toString('yaml');, <sub>(*36)</sub>

## StructureHelper

``` php
use Windwalker\Structure\StructureHelper;

StructureHelper::loadFaile($file, $format); // File to array
StructureHelper::loadString($string, $format); // String to array
StructureHelper::toString($array, $format); // Array to string

// Use format class
$json = StructureHelper::getFormatClass('json'); // Get JsonFormat
$string = $json::structToString($array);