README

A powerful and flexible data transformation component for PHP, part of the KaririCode Framework. It uses attribute-based transformation with configurable processors to ensure consistent data transformation and formatting in your applications.

Features
Installation
Usage
- Basic Usage
- Advanced Usage: Data Formatting
Available Transformers
Configuration
Integration with Other KaririCode Components
Development and Testing
Contributing
License
Support and Community

Features

Attribute-based transformation for object properties
Comprehensive set of built-in transformers for common use cases
Easy integration with other KaririCode components
Configurable processors for customized transformation logic
Extensible architecture allowing custom transformers
Robust error handling and reporting
Chainable transformation pipelines for complex data transformation
Built-in support for multiple transformation scenarios
Type-safe transformation with PHP 8.3 features
Preservation of original data types
Flexible formatting options for various data types

Installation

You can install the Transformer component via Composer:

composer require kariricode/transformer

Requirements

PHP 8.3 or higher
Composer
Extensions: ext-mbstring, ext-json

Usage

Basic Usage

Define your data class with transformation attributes:

use KaririCode\Transformer\Attribute\Transform;

class DataFormatter
{
    #[Transform(
        processors: ['date' => ['inputFormat' => 'd/m/Y', 'outputFormat' => 'Y-m-d']]
    )]
    private string $date = '25/12/2024';

    #[Transform(
        processors: ['number' => ['decimals' => 2, 'decimalPoint' => ',', 'thousandsSeparator' => '.']]
    )]
    private float $price = 1234.56;

    #[Transform(
        processors: ['mask' => ['type' => 'phone']]
    )]
    private string $phone = '11999887766';

    // Getters and setters...
}

Set up the transformer and use it:

use KaririCode\ProcessorPipeline\ProcessorRegistry;
use KaririCode\Transformer\Transformer;
use KaririCode\Transformer\Processor\Data\{DateTransformer, NumberTransformer};
use KaririCode\Transformer\Processor\String\MaskTransformer;

$registry = new ProcessorRegistry();
$registry->register('transformer', 'date', new DateTransformer());
$registry->register('transformer', 'number', new NumberTransformer());
$registry->register('transformer', 'mask', new MaskTransformer());

$transformer = new Transformer($registry);

$formatter = new DataFormatter();
$result = $transformer->transform($formatter);

if ($result->isValid()) {
    echo "Date: " . $formatter->getDate() . "\n";          // Output: 2024-12-25
    echo "Price: " . $formatter->getPrice() . "\n";        // Output: 1.234,56
    echo "Phone: " . $formatter->getPhone() . "\n";        // Output: (11) 99988-7766
}

Advanced Usage: Data Formatting

Here's an example of how to use the KaririCode Transformer in a real-world scenario, demonstrating various transformation capabilities:

use KaririCode\Transformer\Attribute\Transform;

class ComplexDataTransformer
{
    #[Transform(
        processors: ['case' => ['case' => 'snake']]
    )]
    private string $text = 'transformThisTextToSnakeCase';

    #[Transform(
        processors: ['slug' => []]
    )]
    private string $title = 'This is a Title for URL!';

    #[Transform(
        processors: ['arrayKey' => ['case' => 'camel']]
    )]
    private array $data = [
        'user_name' => 'John Doe',
        'email_address' => 'john@example.com',
        'phone_number' => '1234567890'
    ];

    #[Transform(
        processors: [
            'template' => [
                'template' => 'Hello {{name}}, your order #{{order_id}} is {{status}}',
                'removeUnmatchedTags' => true,
                'preserveData' => true
            ]
        ]
    )]
    private array $templateData = [
        'name' => 'John',
        'order_id' => '12345',
        'status' => 'completed'
    ];

    // Getters and setters...
}

Available Transformers

String Transformers

CaseTransformer: Transforms string case (camel, snake, pascal, kebab).
- Configuration Options:
  - case: Target case format (lower, upper, title, sentence, camel, pascal, snake, kebab)
  - preserveNumbers: Whether to preserve numbers in transformation
MaskTransformer: Applies masks to strings (phone, CPF, CNPJ, etc.).
- Configuration Options:
  - mask: Custom mask pattern
  - type: Predefined mask type
  - placeholder: Mask placeholder character
SlugTransformer: Generates URL-friendly slugs.
- Configuration Options:
  - separator: Separator character
  - lowercase: Convert to lowercase
  - replacements: Custom character replacements
TemplateTransformer: Processes templates with variable substitution.
- Configuration Options:
  - template: Template string
  - removeUnmatchedTags: Remove unmatched placeholders
  - preserveData: Keep original data in result

Data Transformers

DateTransformer: Converts between date formats.
- Configuration Options:
  - inputFormat: Input date format
  - outputFormat: Output date format
  - inputTimezone: Input timezone
  - outputTimezone: Output timezone
NumberTransformer: Formats numbers with locale-specific settings.
- Configuration Options:
  - decimals: Number of decimal places
  - decimalPoint: Decimal separator
  - thousandsSeparator: Thousands separator
  - roundUp: Round up decimals
JsonTransformer: Handles JSON encoding/decoding.
- Configuration Options:
  - encodeOptions: JSON encoding options
  - preserveType: Keep original data type
  - assoc: Use associative arrays

Array Transformers

ArrayFlattenTransformer: Flattens nested arrays.
- Configuration Options:
  - depth: Maximum depth to flatten
  - separator: Key separator for flattened structure
ArrayGroupTransformer: Groups array elements by key.
- Configuration Options:
  - groupBy: Key to group by
  - preserveKeys: Maintain original keys
ArrayKeyTransformer: Transforms array keys.
- Configuration Options:
  - case: Target case for keys
  - recursive: Apply to nested arrays
ArrayMapTransformer: Maps array keys to new structure.
- Configuration Options:
  - mapping: Key mapping configuration
  - removeUnmapped: Remove unmapped keys
  - recursive: Apply to nested arrays

Composite Transformers

ChainTransformer: Executes multiple transformers in sequence.
- Configuration Options:
  - transformers: Array of transformers to execute
  - stopOnError: Stop chain on first error
ConditionalTransformer: Applies transformations based on conditions.
- Configuration Options:
  - condition: Condition callback
  - transformer: Transformer to apply
  - defaultValue: Value when condition fails

Configuration

Transformers can be configured globally or per-instance. Example of configuring the NumberTransformer:

use KaririCode\Transformer\Processor\Data\NumberTransformer;

$numberTransformer = new NumberTransformer();
$numberTransformer->configure([
    'decimals' => 2,
    'decimalPoint' => ',',
    'thousandsSeparator' => '.',
]);

$registry->register('transformer', 'number', $numberTransformer);

Integration with Other KaririCode Components

The Transformer component integrates with:

KaririCode\Contract: Provides interfaces for component integration
KaririCode\ProcessorPipeline: Used for transformation pipelines
KaririCode\PropertyInspector: Processes transformation attributes

Registry Example

Complete registry setup example:

$registry = new ProcessorRegistry();

// Register String Transformers
$registry->register('transformer', 'case', new CaseTransformer())
         ->register('transformer', 'mask', new MaskTransformer())
         ->register('transformer', 'slug', new SlugTransformer())
         ->register('transformer', 'template', new TemplateTransformer());

// Register Data Transformers
$registry->register('transformer', 'date', new DateTransformer())
         ->register('transformer', 'number', new NumberTransformer())
         ->register('transformer', 'json', new JsonTransformer());

// Register Array Transformers
$registry->register('transformer', 'arrayFlat', new ArrayFlattenTransformer())
         ->register('transformer', 'arrayGroup', new ArrayGroupTransformer())
         ->register('transformer', 'arrayKey', new ArrayKeyTransformer())
         ->register('transformer', 'arrayMap', new ArrayMapTransformer());

Development and Testing

Similar development setup as the Validator component, using Docker and Make commands.

Available Make Commands

make up: Start services
make down: Stop services
make test: Run tests
make coverage: Generate coverage report
make cs-fix: Fix code style
make quality: Run quality checks

Contributing

Contributions are welcome! Please see our Contributing Guide.

License

MIT License - see LICENSE file.

Support and Community

Documentation: https://kariricode.org/docs/transformer
Issues: GitHub Issues
Forum: KaririCode Club Community
Stack Overflow: Tag with kariricode-transformer

Built with ❤️ by the KaririCode team. Transforming data with elegance and precision.

kariricode / transformer

Maintainers

Details