diff --git a/README.md b/README.md index fe84766..0912155 100644 --- a/README.md +++ b/README.md @@ -1,577 +1,8 @@ # KaririCode Framework: Transformer Component -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. - -## Table of Contents - -- [Features](#features) -- [Installation](#installation) -- [Usage](#usage) - - [Basic Usage](#basic-usage) - - [Advanced Usage: Data Formatting](#advanced-usage-data-formatting) -- [Available Transformers](#available-transformers) - - [String Transformers](#string-transformers) - - [Data Transformers](#data-transformers) - - [Array Transformers](#array-transformers) - - [Composite Transformers](#composite-transformers) -- [Configuration](#configuration) -- [Integration with Other KaririCode Components](#integration-with-other-kariricode-components) -- [Development and Testing](#development-and-testing) -- [Contributing](#contributing) -- [License](#license) -- [Support and Community](#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: - -```bash -composer require kariricode/transformer -``` - -### Requirements - -- PHP 8.3 or higher -- Composer -- Extensions: `ext-mbstring`, `ext-json` - -## Usage - -### Basic Usage - -1. Define your data class with transformation attributes: - -```php -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... -} -``` - -2. Set up the transformer and use it: - -```php -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: - -```php -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... -} -``` - -## Practical Examples - -### 1. String Transformation Examples - -```php -class StringTransformerExample -{ - #[Transform( - processors: ['case' => ['case' => 'snake']] - )] - private string $methodName = 'getUserProfileData'; - - #[Transform( - processors: ['case' => ['case' => 'camel']] - )] - private string $variableName = 'user_profile_data'; - - #[Transform( - processors: ['slug' => ['separator' => '-']] - )] - private string $articleTitle = 'How to Use PHP 8.3 Features!'; - - #[Transform( - processors: ['mask' => ['type' => 'phone']] - )] - private string $phoneNumber = '11999887766'; -} - -// Output: -// methodName: get_user_profile_data -// variableName: userProfileData -// articleTitle: how-to-use-php-8-3-features -// phoneNumber: (11) 99988-7766 -``` - -### 2. Number and Currency Formatting - -```php -class CurrencyTransformerExample -{ - #[Transform( - processors: ['number' => [ - 'decimals' => 2, - 'decimalPoint' => ',', - 'thousandsSeparator' => '.' - ]] - )] - private float $price = 1234567.89; - - #[Transform( - processors: ['number' => [ - 'decimals' => 0, - 'thousandsSeparator' => ',' - ]] - )] - private int $quantity = 1000000; -} - -// Output: -// price: 1.234.567,89 -// quantity: 1,000,000 -``` - -### 3. Date Transformation for Different Locales - -```php -class DateTransformerExample -{ - #[Transform( - processors: ['date' => [ - 'inputFormat' => 'd/m/Y', - 'outputFormat' => 'Y-m-d' - ]] - )] - private string $sqlDate = '25/12/2024'; - - #[Transform( - processors: ['date' => [ - 'inputFormat' => 'Y-m-d', - 'outputFormat' => 'F j, Y' - ]] - )] - private string $displayDate = '2024-12-25'; - - #[Transform( - processors: ['date' => [ - 'inputFormat' => 'Y-m-d H:i:s', - 'outputFormat' => 'd/m/Y H:i', - 'inputTimezone' => 'UTC', - 'outputTimezone' => 'America/Sao_Paulo' - ]] - )] - private string $timestamp = '2024-12-25 15:30:00'; -} - -// Output: -// sqlDate: 2024-12-25 -// displayDate: December 25, 2024 -// timestamp: 25/12/2024 12:30 -``` - -### 4. Array Transformation for API Response - -```php -class ApiResponseTransformerExample -{ - #[Transform( - processors: ['arrayKey' => ['case' => 'camel']] - )] - private array $userData = [ - 'user_id' => 123, - 'first_name' => 'John', - 'last_name' => 'Doe', - 'email_address' => 'john@example.com', - 'phone_numbers' => [ - 'home_phone' => '1234567890', - 'work_phone' => '0987654321' - ] - ]; - - #[Transform( - processors: ['arrayFlat' => ['separator' => '.']] - )] - private array $nestedConfig = [ - 'database' => [ - 'mysql' => [ - 'host' => 'localhost', - 'port' => 3306 - ] - ], - 'cache' => [ - 'redis' => [ - 'host' => '127.0.0.1', - 'port' => 6379 - ] - ] - ]; -} - -// Output: -// userData: -// { -// "userId": 123, -// "firstName": "John", -// "lastName": "Doe", -// "emailAddress": "john@example.com", -// "phoneNumbers": { -// "homePhone": "1234567890", -// "workPhone": "0987654321" -// } -// } -// -// nestedConfig: -// { -// "database.mysql.host": "localhost", -// "database.mysql.port": 3306, -// "cache.redis.host": "127.0.0.1", -// "cache.redis.port": 6379 -// } -``` - -### 5. Template Transformation for Notifications - -```php -class NotificationTransformerExample -{ - #[Transform( - processors: [ - 'template' => [ - 'template' => <<