File: README.md

Recommend this page to a friend!

README.md

File:	`README.md`
Role:	Documentation
Content type:	`text/markdown`
Description:	Documentation
Class:	Schematic PHP Data Mapper Process and convert nested arrays and objects
Author:	By Smoren Freelight
Last change:	Tests and README updated.
Date:	1 year ago
Size:	`15,626 bytes`

Download

Schematic data mapper

Packagist PHP Version Support

Schematic data mapper is a tool for converting nested data structures (any compositions of associative arrays, non-associative arrays and objects) according to the given conversion schema.

How to install to your project

composer require smoren/schemator

Usage

Simple usage

use Smoren\Schemator\Factories\SchematorFactory;

$input = [
    'id' => 100,
    'name' => 'Oxford',
    'country' => [
        'id' => 10,
        'name' => 'UK',
        'neighbours' => ['Ireland', 'Sweden', 'France'],
        'capitals' => [
            'lnd' => 'London',
            'edb' => 'Edinburgh',
        ],
    ],
    'streets' => [
        [
            'id' => 1000,
            'name' => 'Woodstock Rd',
            'houses' => [1, 5, 9],
        ],
        [
            'id' => 1002,
            'name' => 'Banbury Rd',
            'houses' => [22, 35, 49],
        ],
        [
            'id' => 1003,
            'name' => 'Beamont St',
            'houses' => [11, 12, 15],
        ],
    ],
    'lnd_path' => 'country.capitals.lnd',
];

$schema = [
    'city_id' => 'id',
    'city_name' => 'name',
    'city_street_names' => 'streets.name',
    'country_id' => 'country.id',
    'country_name' => 'country.name',
    'country_neighbours' => 'country.neighbours',
    'country_neighbour' => 'country.neighbours',
    'country_first_capital' => 'country.capitals.lnd',
    'country_second_capital' => 'country.capitals.edb',
    'country_data.country_id' => 'country.id',
    'country_data.country_name' => 'country.name',
];

$schemator = SchematorFactory::create();
$output = $schemator->convert($input, $schema);

print_r($output);
/* Array
(
    [city_id] => 100
    [city_name] => Oxford
    [city_street_names] => Array
        (
            [0] => Woodstock Rd
            [1] => Banbury Rd
            [2] => Beamont St
        )

    [country_id] => 10
    [country_name] => UK
    [country_neighbours] => Array
        (
            [0] => Ireland
            [1] => Sweden
            [2] => France
        )

    [country_neighbour] => Array
        (
            [0] => Ireland
            [1] => Sweden
            [2] => France
        )

    [country_first_capital] => London
    [country_second_capital] => Edinburgh
    [country_data] => Array
        (
            [country_id] => 10
            [country_name] => UK
        )

)
*/

Setting errors level

use Smoren\Schemator\Factories\SchematorFactory;
use Smoren\Schemator\Structs\ErrorsLevelMask;
use Smoren\Schemator\Exceptions\SchematorException;

$input = [
    'some_key' => null,
];
$schema = [
    'my_value' => ['some_key', ['date', 'Y-m-d']],
];

$schemator = SchematorFactory::createBuilder()
    ->withErrorsLevelMask(
        ErrorsLevelMask::nothing()
            ->add([SchematorException::FILTER_ERROR, SchematorException::CANNOT_GET_VALUE])
    )
    ->get();

try {
    $schemator->convert($input, $schema);
} catch(SchematorException $e) {
    echo $e->getMessage(); // filter error: 'date'
}

Using base filters

use Smoren\Schemator\Factories\SchematorFactory;
use Smoren\Schemator\Filters\BaseFiltersStorage;

$input = [
    'id' => 100,
    'name' => 'Oxford',
    'country' => [
        'id' => 10,
        'name' => 'UK',
        'neighbours' => ['Ireland', 'Sweden', 'France'],
        'capitals' => [
            'lnd' => 'London',
            'edb' => 'Edinburgh',
        ],
    ],
    'streets' => [
        [
            'id' => 1000,
            'name' => 'Woodstock Rd',
            'houses' => [1, 5, 9],
        ],
        [
            'id' => 1002,
            'name' => 'Banbury Rd',
            'houses' => [22, 35, 49],
        ],
        [
            'id' => 1003,
            'name' => 'Beamont St',
            'houses' => [11, 12, 15],
        ],
    ],
    'lnd_path' => 'country.capitals.lnd',
];

$schema = [
    'city_street_names.all' => ['streets.name', ['implode', ', ']],
    'city_street_names.sorted' => ['streets.name', ['sort'], ['implode', ', ']],
    'city_street_names.filtered' => ['streets.name', ['filter', function (string $candidate) {
        return strpos($candidate, 'Ban') !== false;
    }]],
    'lnd' => ['lnd_path', ['path']],
    'city_street_houses' => ['streets.houses', ['flatten']],
];

$schemator = SchematorFactory::create();
$output = $schemator->convert($input, $schema);

print_r($output);
/*
Array
(
    [city_street_names] => Array
        (
            [all] => Woodstock Rd, Banbury Rd, Beamont St
            [sorted] => Banbury Rd, Beamont St, Woodstock Rd
            [filtered] => Array
                (
                    [0] => Banbury Rd
                )

        )

    [lnd] => London
    [city_street_houses] => Array
        (
            [0] => 1
            [1] => 5
            [2] => 9
            [3] => 22
            [4] => 35
            [5] => 49
            [6] => 11
            [7] => 12
            [8] => 15
        )

)
*/

Using smart filter and replace

use Smoren\Schemator\Factories\SchematorFactory;
use Smoren\Schemator\Filters\BaseFiltersStorage;

$schemator = SchematorFactory::create();
$input = [
    'numbers' => [-1, 10, 5, 22, -10, 0, 35, 7, 8, 9, 0],
];

$output = $schemator->convert($input, [
    'positive' => [
        'numbers',
        ['filter', [['>', 0]]],
        ['sort'],
    ],
    'negative' => [
        'numbers',
        ['filter', [['<', 0]]],
        ['sort'],
    ],
    'complicated' => [
        'numbers',
        ['filter', [['>=', 8], ['<', 0]]],
        ['filter', [['<', 22]]],
        ['sort'],
    ],
]);

print_r($output);
/*
Array
(
    [positive] => Array
        (
            [0] => 5
            [1] => 7
            [2] => 8
            [3] => 9
            [4] => 10
            [5] => 22
            [6] => 35
        )

    [negative] => Array
        (
            [0] => -10
            [1] => -1
        )

    [complicated] => Array
        (
            [0] => -10
            [1] => -1
            [2] => 8
            [3] => 9
            [4] => 10
        )

)
*/

$output = $schemator->convert($input, [
    'number_types' => ['numbers', [
        'replace',
        [
            ['=0', '=', 0],
            ['>9', '>', 9],
            ['<0', '<', 0],
            ['1-8', 'between', 1, 8],
        ]
    ]]
]);

print_r($output);
/*
Array
(
    [number_types] => Array
        (
            [0] => <0
            [1] => >9
            [2] => 1-8
            [3] => >9
            [4] => <0
            [5] => =0
            [6] => >9
            [7] => 1-8
            [8] => 1-8
            [9] => 9
            [10] => =0
        )

)
*/

Using custom filters

use Smoren\Schemator\Factories\SchematorFactory;
use Smoren\Schemator\Interfaces\FilterContextInterface;

$schemator = SchematorFactory::createBuilder()
    ->withFilters([
        'startsWith' => function (FilterContextInterface $context, string $start) {
            return array_filter($context->getSource(), function (string $candidate) use ($start) {
                return strpos($candidate, $start) === 0;
            });
        },
    ])
    ->get();

$input = [
    'streets' => ['Woodstock Rd', 'Banbury Rd', 'Beamont St'],
];

$schema = [
    'street_names' => ['streets', ['startsWith', 'T'], ['implode', ', ']],
];

$output = $schemator->convert($input, $schema);

print_r($output);
/*
Array
(
    [street_names] => Woodstock Rd, Beamont St
)
*/

Mass usage

use Smoren\Schemator\Factories\SchematorFactory;

$massSchemator = SchematorFactory::createMass();

$cities = [
    [
        'id' => 100,
        'name' => 'London',
        'country' => [
            'id' => 10,
            'name' => 'UK',
        ],
        'streets' => [
            [
                'id' => 1001,
                'name' => 'The Mall',
            ],
            [
                'id' => 1002,
                'name' => 'Carnaby Street',
            ],
        ],
    ],
    [
        'id' => 101,
        'name' => 'Oxford',
        'country' => [
            'id' => 10,
            'name' => 'UK',
        ],
        'streets' => [
            [
                'id' => 1003,
                'name' => 'Turl Street',
            ],
            [
                'id' => 1004,
                'name' => 'Holywell Street',
            ],
        ],
    ],
];

$schema = [
    'city_id' => 'id',
    'city_name' => 'name',
    'city_street_names' => 'streets.name',
    'country_id' => 'country.id',
    'country_name' => 'country.name',
];

$gen = $massSchemator->generate($cities, $schema);

$result = [];
foreach($gen as $item) {
    $result[] = $item;
}

print_r($result);
/*
Array
(
    [0] => Array
        (
            [city_id] => 100
            [city_name] => London
            [city_street_names] => Array
                (
                    [0] => The Mall
                    [1] => Carnaby Street
                )

            [country_id] => 10
            [country_name] => UK
        )
    [1] => Array
        (
            [city_id] => 101
            [city_name] => Oxford
            [city_street_names] => Array
                (
                    [0] => Turl Street
                    [1] => Holywell Street
                )

            [country_id] => 10
            [country_name] => UK
        )
)
*/

Filters

const

Sets the value from const param.

Schema:

["value" => [["const", "My const value"]]]

Result:

["value" => "My const value"]

sum

Returns the sum of given array.

Given:

["numbers" => [1, 2, 3, 4, 5]]

Schema:

["value" => ["numbers", ["sum"]]]

Result:

["value" => 15]

average

Returns the average of given array.

Given:

["numbers" => [1, 2, 3, 4, 5]]

Schema:

["value" => ["numbers", ["average"]]]

Result:

["value" => 3]

date

Returns formatted date from the Unix timestamp given value.

Params:

Date format * required * data type ? string * example: `d.m.Y H:i:s` * more about formats
Time zone offset from GMT * optional * data type ? integer * default ? 0

Given:

["some_date" => 1651481881]

Schema:

["value" => ["some_date", ["date", "d.m.Y H:i:s", 3]]]

Result:

["value" => "02.05.2022 11:58:01"]

implode

Returns string of imploded items of given array with separator from args list.

params:

Separator * required * data type ? string * example: `; `

Given:

["numbers" => [1, 2, 3, 4, 5]]

Schema:

["value" => ["numbers", ["implode", "; "]]]

Result:

["value" => "1; 2; 3; 4; 5"]

explode

Returns array of exploded strings from given string with separator from args list

params:

Separator * required * data type ? string * example: `; `

Given:

["numbers" => "1; 2; 3; 4; 5"]

Schema:

["value" => ["numbers", ["explode", "; "]]]

Result:

["value" => ["1", "2", "3", "4", "5"]]

flatten

Returns flat array contains all the dead end leaves of tree array.

Given:

[
   "numbers" => [
      [
         [1, 2, 3],
         [4, 5, 6]
      ],
      [7, 8, 9]
   ],
]

Schema:

["value" => ["numbers", ["flatten"]]]

Result:

["value" => [1, 2, 3, 4, 5, 6, 7, 8, 9]]

sort

Sorts and returns given array.

Given:

["numbers" => [3, 5, 4, 1, 2]]

Schema:

["value" => ["numbers", ["sort"]]]

Result:

["value" => [1, 2, 3, 4, 5]]

rsort

Sorts reversely and returns given array.

Given:

["numbers" => [3, 5, 4, 1, 2]]

Schema:

["value" => ["numbers", ["sort"]]]

Result:

["value" => [5, 4, 3, 2, 1]]

filter

Returns array contains elements from given array, that match the predicates from params list.

Rules:

Every predicate has such format `["predicate name", ...parans]`.
Predicates in one filter apply according the "OR" logic.
To apply "AND" logic use chain of filters.
Available predicates: * `["=", 10]` means `value = 10` * `[">", 10]` means `value > 10` * `[">=", 10]` means `value >= 10` * `["<", 10]` means `value < 10` * `["<=", 10]` means `value <= 10` * `["in", [1, 2]]` means `value = 1 OR value = 2` * `["not in", [1, 2]]` means `value != 1 AND value != 2` * `["between", 1, 5]` means `1 <= value <= 5` * `["between strict", 1, 5]` means `1 < value < 5`

Given:

["numbers" => [-5, -3, -1, 1, 3, 5]]

Schema:

[
   "value" => [
      "numbers",
      [
         "filter",
         [[">", 1], ["<", -1]] // value > 1 OR value < -1
      ],
   ],
]

Result:

["value" => [-5, -3, 3, 5]]

replace

Returns array of elements from given array with replaces by rules from params list.

Rules:

Every rule has such format `["value to replace", "rule name", ...params]`.
Rules in one filter apply according the "OR" logic.
To apply "AND" logic use chain of filters.
Available rules: * `["=", 10]` means `value = 10` * `[">", 10]` means `value > 10` * `[">=", 10]` means `value >= 10` * `["<", 10]` means `value < 10` * `["<=", 10]` means `value <= 10` * `["in", [1, 2]]` means `value = 1 ??? value = 2` * `["not in", [1, 2]]` means `value != 1 ? value != 2` * `["between", 1, 5]` means `1 <= value <= 5` * `["between strict", 1, 5]` means `1 < value < 5` * `["else"]` ? no rules matched for value _(If rule `else` did not use, by default such values are replaced with `null`)_

Given:

["numbers" => [-5, -3, -1, 1, 3, 5]]

Schema:

[
   "value" => [
      "numbers",
      [
         "replace",
         [
            ["positive", ">", 0],
            ["negative", "<", 0],
            ["zero", "else"]
         ],
      ],
   ],
]

Result:

["value" => ["negative", "negative", "negative", "zero", "positive", "positive", "positive"]]

Chain of filters

Given:

["numbers" => [-5, -3, -1, 1, 3, 5]]

Schema:

[
   "value" => [
      "numbers",
      [
         "filter",
         [[">", 1], ["<", -1]] // (value > 1 OR value < -1)
      ],
      // AND
      [
         "filter",
         [[">=", -3]] // value >= -3
      ],
   ],
]

Result:

["value" => [-3, 3, 5]]

Unit testing

composer install
composer test-init
composer test

Standards

Schemator conforms to the following standards:

License

Schemator is licensed under the MIT License.

About us

Advertise on this site

For more information send a message to info at phpclasses dot org.

File: README.md

Contents

Schematic data mapper

How to install to your project

Usage

Simple usage

Setting errors level

Using base filters

Using smart filter and replace

Using custom filters

Mass usage

Filters

const

sum

average

date

implode

explode

flatten

sort

rsort

filter

replace

Chain of filters

Unit testing

Standards

License