Une base sérieuse pour lire, transformer et exporter des données en PHP.

Vue d’ensemble

La bibliothèque repose sur un principe simple : tous les readers renvoient un tableau PHP normalisé, puis le pipeline transforme ce tableau avant qu’un writer le persiste dans un format cible.

$rows = [
    ['id' => 1, 'name' => 'Ada'],
    ['id' => 2, 'name' => 'Grace'],
];

Installation

composer require gbelsalvador/data-transformer

Prérequis

• PHP 8.0 ou supérieur
• PhpSpreadsheet pour les fichiers XLSX
• PDO pour les intégrations SQL

Démarrage rapide

use Gbelsalvador\DataTransformer\Core\Transformer;
use Gbelsalvador\DataTransformer\Readers\CsvReader;
use Gbelsalvador\DataTransformer\Writers\JsonWriter;

$transformer = new Transformer();

$result = $transformer->transform(
    new CsvReader('input.csv'),
    new JsonWriter('output.json')
);

echo $result->rowsRead();
echo $result->rowsWritten();

transform() retourne un objet ExecutionResult utilisable pour le reporting et le logging.

Pipeline fluent

L’API fluent est l’approche recommandée pour les cas d’usage métier.

use Gbelsalvador\DataTransformer\Core\Transformer;
use Gbelsalvador\DataTransformer\Readers\CsvReader;
use Gbelsalvador\DataTransformer\Writers\JsonWriter;

$result = (new Transformer())
    ->read(new CsvReader('users.csv'))
    ->filter(fn (array $row) => ($row['active'] ?? null) === '1')
    ->map([
        'id' => 'user_id',
        'full_name' => fn (array $row) => trim(($row['first_name'] ?? '') . ' ' . ($row['last_name'] ?? '')),
        'email' => 'email',
        'country' => 'country',
    ])
    ->validate([
        'id' => 'required|integer',
        'full_name' => 'required|max:120',
        'email' => 'required|email',
        'country' => 'in:FR,BE,CH,CA',
    ])
    ->write(new JsonWriter('clean-users.json'));

• read() charge les données.
• filter() garde les lignes utiles.
• map() renomme, projette ou calcule des champs.
• validate() applique les règles de validation.
• write() persiste le résultat et retourne un rapport.

Formats supportés

Validation

La validation permet d’éliminer les lignes non conformes avant export et de produire un rapport d’erreurs.

• required
• email
• numeric
• integer
• boolean
• date
• max:<longueur>
• in:valeur1,valeur2,valeur3
• same:autre_colonne

$result = (new Transformer())
    ->read($reader)
    ->validate([
        'email' => 'required|email',
        'status' => 'required|in:active,inactive,pending',
        'name' => 'max:120',
    ])
    ->write($writer);

SQL et filtres structurés

SqlReader accepte un tableau de filtres structurés pour construire un WHERE paramétré. Cette approche est la plus sûre et la plus lisible pour les usages applicatifs.

new SqlReader(
    pdo: $pdo,
    tableName: 'users',
    columns: ['id', 'name', 'email'],
    filters: [
        'active' => 1,
        'created_at' => [
            'operator' => '>=',
            'value' => '2026-01-01',
        ],
    ]
);

Opérateurs disponibles

• =
• !=
• >
• >=
• <
• <=
• like
• in
• is_null
• is_not_null

Sécurité

La bibliothèque embarque plusieurs garde-fous utiles sur les flux de données les plus courants.

Référence API

Transformer

$transformer = new Transformer();

$transformer->read(ReaderInterface $reader);
$transformer->filter(callable $callback);
$transformer->map(callable|array $mapping);
$transformer->validate(array $rules);
$result = $transformer->write(WriterInterface $writer);

Readers disponibles

new CsvReader(string $filePath, string $delimiter = ',', bool $hasHeader = true, string $enclosure = '"', string $escape = '\\');
new JsonReader(string $filePath, bool $assoc = true);
new XmlReader(string $filePath, string $rootElement = 'root');
new SqlReader(PDO $pdo, string $tableName, array $columns = ['*'], ?string $whereClause = null, array $whereParams = [], array $filters = []);
new XlsxReader(string $filePath, ?string $sheetName = null, bool $hasHeader = true);

Writers disponibles

new CsvWriter(string $filePath, string $delimiter = ',', string $enclosure = '"', bool $includeHeader = true);
new JsonWriter(string $filePath, int $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
new XmlWriter(string $filePath, string $rootElement = 'root', string $rowElement = 'row');
new SqlWriter(PDO $pdo, string $tableName, bool $truncateFirst = false);
new XlsxWriter(string $filePath, ?string $sheetName = null);

Exemples d’intégration

CSV vers JSON

$result = (new Transformer())->transform(
    new CsvReader('products.csv', delimiter: ';'),
    new JsonWriter('products.json')
);

SQL vers XLSX

$result = (new Transformer())->transform(
    new SqlReader(
        pdo: $pdo,
        tableName: 'users',
        columns: ['id', 'name', 'email', 'created_at'],
        filters: [
            'active' => 1,
            'created_at' => ['operator' => '>=', 'value' => '2026-01-01'],
        ]
    ),
    new XlsxWriter('active-users.xlsx', sheetName: 'Users')
);

JSON vers XML

$result = (new Transformer())->transform(
    new JsonReader('catalog.json'),
    new XmlWriter('catalog.xml', rootElement: 'catalog', rowElement: 'item')
);

Tests

composer install
composer test

• Tests unitaires sur le pipeline fluent.
• Tests d’intégration sur CSV, JSON et XML.
• Tests SQL prêts à s’exécuter lorsque pdo_sqlite est activé.

Roadmap

• Support du streaming pour les gros volumes.
• Validation de schéma plus riche.
• Primitives de transformation supplémentaires.
• Modes d’append et stratégies de fusion.
• Nouvelles sources d’entrée comme HTTP ou YAML.