Quick Start

Get up and running with Data Helpers in just a few minutes. This library provides data mapping, type-safe DTOs and utility helpers for common operations.

Installation

composer require event4u/data-helpers

Basic Usage

DataAccessor - Read Nested Data

use event4u\DataHelpers\DataAccessor;

$data = [
    'user' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'orders' => [
            ['id' => 1, 'total' => 100],
            ['id' => 2, 'total' => 200],
        ],
    ],
];

$accessor = new DataAccessor($data);

// Simple access
$name = $accessor->get('user.name'); // 'John Doe'

// Wildcard access
$totals = $accessor->get('user.orders.*.total'); // [100, 200]

DataMutator - Modify Nested Data

use event4u\DataHelpers\DataMutator;

$data = [
    'user' => [
        'name' => 'John Doe',
        'orders' => [
            ['id' => 1, 'total' => 100],
            ['id' => 2, 'total' => 200],
        ],
    ],
];

// Set nested value
DataMutator::make($data)->set('user.phone', '+1234567890');

// Set multiple values with wildcards
DataMutator::make($data)->set('user.orders.*.status', 'shipped');
// Result: ['user' => ['name' => 'John Doe', 'orders' => [['id' => 1, 'total' => 100, 'status' => 'shipped'], ['id' => 2, 'total' => 200, 'status' => 'shipped']], 'phone' => '+1234567890']]

DataMapper - Transform Data (Fluent API)

use event4u\DataHelpers\DataMapper;

$data = [
    'user' => [
        'name' => 'John Doe',
        'email' => 'john@example.com',
        'orders' => [
            ['id' => 1, 'total' => 100],
            ['id' => 2, 'total' => 200],
        ],
    ],
];

// Fluent API with template-based mapping
$result = DataMapper::source($data)
    ->template([
        'customer_name' => '{{ user.name }}',
        'customer_email' => '{{ user.email }}',
        'total_orders' => '{{ user.orders | count }}',
        'order_ids' => '{{ user.orders.*.id }}',
    ])
    ->map()
    ->getTarget();
// Result: ['customer_name' => 'John Doe', 'customer_email' => 'john@example.com', 'total_orders' => 2, 'order_ids' => [1, 2]]

With WHERE/ORDER BY in template (recommended for database-stored templates):

use event4u\DataHelpers\DataMapper;

$data = [
    'user' => [
        'orders' => [
            ['id' => 1, 'total' => 100],
            ['id' => 2, 'total' => 200],
            ['id' => 3, 'total' => 150],
        ],
    ],
];

$result = DataMapper::source($data)
    ->template([
        'items' => [
            'WHERE' => [
                '{{ user.orders.*.total }}' => ['>', 100],
            ],
            'ORDER BY' => [
                '{{ user.orders.*.total }}' => 'DESC',
            ],
            'LIMIT' => 5,
            '*' => [
                'id' => '{{ user.orders.*.id }}',
                'total' => '{{ user.orders.*.total }}',
            ],
        ],
    ])
    ->map()
    ->getTarget();
// Result: ['items' => [['id' => 2, 'total' => 200], ['id' => 3, 'total' => 150]]]

DataFilter - Query Data

use event4u\DataHelpers\DataFilter;

$orders = [
    ['id' => 1, 'total' => 100],
    ['id' => 2, 'total' => 200],
    ['id' => 3, 'total' => 150],
];

$expensive = DataFilter::query($orders)
    ->where('total', '>', 150)
    ->orderBy('total', 'DESC')
    ->get();
// Result: [['id' => 2, 'total' => 200]]

SimpleDto - Data Transfer Objects

use event4u\DataHelpers\SimpleDto;
use event4u\DataHelpers\SimpleDto\Attributes\AutoCast;
use event4u\DataHelpers\SimpleDto\Attributes\Validation\Required;
use event4u\DataHelpers\SimpleDto\Attributes\Validation\Email;

#[AutoCast]  // Optional: Enable automatic type casting
class UserDto extends SimpleDto
{
    public function __construct(
        #[Required]
        public readonly string $name,

        #[Required, Email]
        public readonly string $email,

        public readonly ?string $phone = null,
    ) {}
}

// Create from array
$user = UserDto::fromArray([
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

// Convert to array
$array = $user->toArray();

// Convert to JSON
$json = $user->toJson();

Utility Helpers - Common Operations

use event4u\DataHelpers\Helpers\MathHelper;
use event4u\DataHelpers\Helpers\EnvHelper;

// Math operations with precision
$result = MathHelper::add('10.5', '20.3', 2);  // 30.8
$average = MathHelper::average([10, 20, 30]);  // 20.0
$sum = MathHelper::sum([5, 10, 15]);  // 30.0

// Environment variable access with type casting
$debug = EnvHelper::boolean('APP_DEBUG', false);
$port = EnvHelper::integer('APP_PORT', 8080);
$timeout = EnvHelper::float('REQUEST_TIMEOUT', 30.0);

Next Steps

• Core Concepts - Learn about dot notation and wildcards
• Main Classes - Explore all main classes
• Helpers - Utility helpers for common operations
• Examples - Browse 90+ code examples
• API Reference - Complete API documentation