README

Extendable set of data and data file encoders and decoders. It allows to transfer PHP arrays into data strings and datafiles and vice versa with chosen format like YAML and JSON. It provides encapsulation of various decoding and encoding mechanisms, unifies interface and exceptions handling.

There are various groups of decoders and encoders

With predefined data format - e.g. Coder\Json\Data\Decoder, Coder\Yaml\Datafile\Encoder
With configurable data format - e.g. Coder\Data\Decoder, Coder\Datafile\Encoder
For raw data - e.g. Coder\Json\Data\Decoder, Coder\Data\Encoder
For data in the file - e.g. Coder\Yaml\Datafile\Encoder, Coder\Datafile\Decoder

Getting Started

Prerequisities

PHP 8.1 - 8.3
Git 2.25.1+
Composer 2.6.0+

The instruction assumes using the Linux operating system or compatible tools for other operating systems.

Installation

php8.*-cli, Git and Composer required

The recommended way to install DataCoder into the source code of the project is to handle it as code dependency by Composer. Git is needed to fetch packages from version control repositories.

The php8.*-cli is needed for installing Composer.

DataCoder installation

Add to your composer.json file appropriate entry by running the following command

composer require exorg/data-coder

If it's project set-up stage and no one dependency have been installed yet, run

composer install

If another dependencies have been intalled previously, run

composer update

Usage

The simplest way to autoload all needed files in executable file is attaching autoload.php file generated by Composer (after running composer install or composer update command) like in following example

require_once (__DIR__ . '/vendor/autoload.php');

Data Encoders with predefined format

use ExOrg\DataCoder\Coder\Json\Data\Encoder;

$data = [
    "firstName" => "John",
    "lastName" => "Smith",
    "address" => [
        "streetAddress" => "21 2nd Street",
        "city" => "New York",
        "state" => "NY",
        "postalCode" => "10021-3100",
    ],
];

$encoder = new Encoder();
$result = $encoder->encodeData($data);

print($result);

{
    "firstName": "John",
    "lastName": "Smith",
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10021-3100"
    }
}

Data Decoders with predefined format

use ExOrg\DataCoder\Coder\Yaml\Data\Decoder;

$data = '
firstName: John
lastName: Smith
address:
  streetAddress: 21 2nd Street
  city: New York
  state: NY
  postalCode: 10021-3100
';

$decoder = new Decoder();
$result = $decoder->decodeData($data);

print_r($result);

Array
(
    [firstName] => John
    [lastName] => Smith
    [address] => Array
        (
            [streetAddress] => 21 2nd Street
            [city] => New York
            [state] => NY
            [postalCode] => 10021-3100
        )

)

Data Encoder with configurable format

use ExOrg\DataCoder\Coder\Data\Encoder;

$data = [
    "firstName" => "John",
    "lastName" => "Smith",
    "address" => [
        "streetAddress" => "21 2nd Street",
        "city" => "New York",
        "state" => "NY",
        "postalCode" => "10021-3100",
    ],
];

$encoder = new Encoder();
$encoder->setDataFormat('yaml');
$result = $encoder->encodeData($data);

print($result);

firstName: John
lastName: Smith
address:
    streetAddress: '21 2nd Street'
    city: 'New York'
    state: NY
    postalCode: 10021-3100

Data Decoder with configurable format

use ExOrg\DataCoder\Coder\Data\Decoder;

$data = '
{
    "firstName": "John",
    "lastName": "Smith",
    "isAlive": true,
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10021-3100"
    }
}
';

$decoder = new Decoder();
$decoder->setDataFormat('json');
$result = $decoder->decodeData($data);

print_r($result);

Array
(
    [firstName] => John
    [lastName] => Smith
    [isAlive] => 1
    [address] => Array
        (
            [streetAddress] => 21 2nd Street
            [city] => New York
            [state] => NY
            [postalCode] => 10021-3100
        )

)

Datafile Encoders and Decoders

Datafile Encoders and Decoders usage is similar to the Data Encoders and Decoders. There are coders with predefined data format like Coder\Json\Datafile\Encoder or Coder\Yaml\Datafile\Decoder and those, where data format can be chosen by function setDataFormat, just like in examples above - Code\Datafile\Encoder and Code\Datafile\Decoder.

Data format recognizing by file extension

Datafile coders with configurable data format - Coder\Datafile\Encoder and Coder\Datafile\Decoder - can recognize data format by file extension. In that case, there is no need to set data format manually.

Datafile Encoder

use ExOrg\DataCoder\Coder\Datafile\Encoder;

$data = [
    "firstName" => "John",
    "lastName" => "Smith",
    "address" => [
        "streetAddress" => "21 2nd Street",
        "city" => "New York",
        "state" => "NY",
        "postalCode" => "10021-3100",
    ],
];

$datafilePath = 'data.json';

$encoder = new Encoder();
$encoder->encodeFile($data, $datafilePath);

print file_get_contents($datafilePath);

{
    "firstName": "John",
    "lastName": "Smith",
    "address": {
        "streetAddress": "21 2nd Street",
        "city": "New York",
        "state": "NY",
        "postalCode": "10021-3100"
    }
}

Datafile Decoder

use ExOrg\DataCoder\Coder\Datafile\Decoder;

$datafilePath = 'data.yaml';

print file_get_contents($datafilePath);

$decoder = new Decoder();
$data = $decoder->decodeFile($datafilePath);

print_r($data);

firstName: John
lastName: Smith
address:
    streetAddress: '21 2nd Street'
    city: 'New York'
    state: NY
    postalCode: 10021-3100
Array
(
    [firstName] => John
    [lastName] => Smith
    [address] => Array
        (
            [streetAddress] => 21 2nd Street
            [city] => New York
            [state] => NY
            [postalCode] => 10021-3100
        )

)

Tests

Unit tests

This project has unit tests, which has been built with PHPUnit framework and run on Linux operating system.

To run tests, write the following command in your command line inside the main DataCoder project directory

vendor/bin/phpunit tests/

or use a Composer script

composer test

Code style tests

This code follows PSR-1 and PSR-12 standards.

To run tests for code style write the following command in your command line inside the main DataCoder project directory

vendor/bin/phpcs tests/ src/

or use a Composer script

composer sniff

You can also use a Composer script for running both tests and check code style

composer check

Built with

Versioning

This project is versioning according to SemVer versioning standars. All available releases are tagged.

Contributing

Please read CONTRIBUTING.md for details on the code of conduct, and the process for submitting pull requests.

Author

Katarzyna Krasińska - katheroine, ExOrg

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

exorg / data-coder

Maintainers

Details