Transformer

transform array keys easily.

This package supports PHP 8.4+ and has no dependencies of its own, so it can be used in any PHP framework — Laravel, Symfony and the rest — as well as in no framework at all.

List of contents

• Install
• How to use
  • Renaming with a format
  • Renaming with from and to
  • Nested arrays
  • How keys that collide are resolved
  • Custom transformers
• Errors
• Testing
• Change log
• Contributing
• Security
• Credits
• License

Install

Via Composer

$ composer require shetabit/transformer

How to use

Renaming with a format

A format maps the keys the data has onto the keys it should have. Hand it to a Transformer and run it with get($transformer).

use Shetabit\Transformer\Classes\Transform;
use Shetabit\Transformer\Classes\Transformer;

$originalData = [
    'f_name' => 'mahdi',
    'l_name' => 'khanzadi',
];

$format = [
    'f_name' => 'first_name',
    'l_name' => 'last_name',
];

$transformedData = new Transform($originalData)->get(new Transformer($format));

/*
[
    'first_name' => 'mahdi',
    'last_name' => 'khanzadi',
]
*/

A key the format does not mention is left as it is, and every key keeps the place it had in the data.

The original data can be set at any time with setOriginalData(), so one Transform can be run over row after row:

$transform = new Transform()->use(new Transformer($format));

foreach ($rows as $row) {
    $transformed[] = $transform->setOriginalData($row)->get();
}

Renaming with from and to

The same format can be written down pair by pair with from($currentFormat) and to($destinationFormat).

$transformer = new Transformer();

$transformer->from('f_name')->to('first_name');
$transformer->from('l_name')->to('last_name');

$transformedData = new Transform($originalData)->use($transformer)->get();

Both take a list as well:

$transformer = new Transformer()
    ->from(['f_name', 'l_name'])
    ->to(['first_name', 'last_name']);

Nested arrays

By default only the keys of the array itself are renamed. A recursive transformer applies the same format to every array nested in the data, including the arrays of a list:

$transformer = new Transformer([
    'cust' => 'customer',
    'f_name' => 'first_name',
    'itms' => 'items',
    'sku' => 'code',
], recursive: true);

$transformedData = new Transform([
    'cust' => ['f_name' => 'mahdi'],
    'itms' => [['sku' => 'A-1'], ['sku' => 'B-7']],
])->get($transformer);

/*
[
    'customer' => ['first_name' => 'mahdi'],
    'items' => [['code' => 'A-1'], ['code' => 'B-7']],
]
*/

recursive() turns it on for a transformer that was built without it, recursive(false) turns it off again.

How keys that collide are resolved

Every key is renamed at once, so a key can take the name another key is giving up in the same run. Two columns that were filled in the wrong order are swapped back with:

new Transformer(['first_name' => 'last_name', 'last_name' => 'first_name']);

Where two keys would end up with the same name the renamed one wins, and of two renamed ones the one that comes first in the data:

new Transformer(['legacy_total' => 'total'])->transform(['legacy_total' => 12900, 'total' => 0]);

// ['total' => 12900]

Custom transformers

For a structure a format cannot describe, write a transformer of your own by implementing TransformerInterface.

use Shetabit\Transformer\Contracts\TransformerInterface;

class CredentialsTransformer implements TransformerInterface
{
    public function transform(array $data) : array
    {
        return [
            'username' => $data['u'],
            'password' => $data['p'],
        ];
    }
}

$transformedData = new Transform(['u' => 'mahdikhanzadi', 'p' => '246810'])
    ->get(new CredentialsTransformer());

/*
[
    'username' => 'mahdikhanzadi',
    'password' => '246810',
]
*/

Errors

Every exception of the package extends Shetabit\Transformer\Exceptions\TransformerException, so all of them can be caught at once.

Exception	Thrown when
TransformerNotValidException	Transform::get() is run without a transformer.
InvalidFormatException	from() and to() were not given the same number of keys.

Testing

Every pull request and every push to master is checked by GitHub Actions: the test suite runs on PHP 8.4 and 8.5 (against both the lowest and the highest supported dependencies), the coding style is checked with PHP_CodeSniffer, the sources are analysed with PHPStan and the code coverage of the test suite is measured and has to stay above 95%.

Next to the unit tests there are feature tests that run realistic nested payloads through the package end to end: a whole tree renamed and renamed back with the flipped format, rows whose columns are swapped or shifted along, and the output of one transformer handed to the next.

You can run the same checks locally. With PHP and Composer installed on your machine:

composer install

composer test           # run the test suite
composer test-coverage  # run the test suite and report code coverage
composer check-style    # check the coding style
composer fix-style      # fix the coding style where possible
composer analyse        # run static analysis
composer ci             # run all of the checks above

If you would rather not install PHP on your machine, the shipped Dockerfile and Makefile run everything inside a container:

make test              # run the test suite
make coverage          # run the test suite and report code coverage
make check-style       # check the coding style
make fix-style         # fix the coding style where possible
make analyse           # run static analysis
make ci                # run all of the checks above
make shell             # open a shell inside the container
make help              # list every available target

Another PHP version can be used with make test PHP_VERSION=8.5.

Change log

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING and CONDUCT for details.

Security

If you discover any security related issues, please email khanzadimahdi@gmail.com instead of using the issue tracker.

Credits

• Mahdi khanzadi
• All Contributors

License

The MIT License (MIT). Please see License File for more information.