README

Data Helpers

A powerful, framework-agnostic PHP library for accessing, transforming, and mapping complex nested data structures with ease.

Stop writing nested loops and array checks. Access, transform, and map complex data structures with simple, expressive syntax.

// From this messy API response...
$apiResponse = [
    'data' => [
        'departments' => [
            ['users' => [['email' => 'alice@example.com'], ['email' => 'bob@example.com']]],
            ['users' => [['email' => 'charlie@example.com']]],
        ],
    ],
];

// ...to this clean result in a few lines
$accessor = new DataAccessor($apiResponse);
$emails = $accessor->get('data.departments.*.users.*.email');
// ['alice@example.com', 'bob@example.com', 'charlie@example.com']

Framework-agnostic • Works with Laravel, Symfony/Doctrine, or standalone PHP • Zero required dependencies

📖 Full Documentation • Getting Started • API Reference

💖 Support the Development - Help us build better tools for the PHP community

💡 Why Data Helpers?

🎯 Stop Writing Nested Loops

// ❌ Without Data Helpers
$emails = [];
foreach ($data['departments'] ?? [] as $dept) {
    foreach ($dept['users'] ?? [] as $user) {
        if (isset($user['email'])) {
            $emails[] = $user['email'];
        }
    }
}

// ✅ With Data Helpers
$emails = $accessor->get('departments.*.users.*.email');

🚀 Key Benefits

Type-Safe - PHPStan Level 9 compliant with 3500+ tests

Fast - SimpleDto with #[UltraFast] is up to 34.0x faster than Other Serializer

Framework-Agnostic - Works with Laravel, Symfony, Doctrine, or plain PHP
Zero Dependencies - No required dependencies, optional framework integrations
No-Code Mapping - Store templates in database, create with drag-and-drop editors

📦 Installation

composer require event4u/data-helpers

Requirements: PHP 8.2+

Framework support (all optional):

🔴 Laravel 9+ - Collections, Eloquent Models
⚫ Symfony/Doctrine 6+ - Collections, Entities
🔧 Standalone PHP - Works out of the box

📖 Installation Guide • Configuration

⚡ Core Components

1️⃣ DataAccessor - Read Nested Data

Access deeply nested data with dot notation and wildcards:

$data = [
    'users' => [
        ['email' => 'alice@example.com'],
        ['email' => 'bob@example.com'],
    ],
];

$accessor = new DataAccessor($data);
$emails = $accessor->get('users.*.email');
// $emails = ['alice@example.com', 'bob@example.com']

📖 DataAccessor Documentation

2️⃣ DataMutator - Modify Nested Data

Safely modify nested structures:

$data = ['user' => ['profile' => []]];
DataMutator::make($data)
    ->set('user.profile.name', 'Alice')
    ->merge('user.profile', ['age' => 30]);
// $data is now modified: ['user' => ['profile' => ['name' => 'Alice', 'age' => 30]]]

📖 DataMutator Documentation

4️⃣ DataFilter - Query Data

Filter and query data with SQL-like API:

$products = [
    ['id' => 1, 'name' => 'Laptop', 'category' => 'Electronics', 'price' => 1200],
    ['id' => 2, 'name' => 'Mouse', 'category' => 'Electronics', 'price' => 25],
    ['id' => 3, 'name' => 'Monitor', 'category' => 'Electronics', 'price' => 400],
];

$result = DataFilter::query($products)
    ->where('category', '=', 'Electronics')
    ->where('price', '>', 100)
    ->orderBy('price', 'DESC')
    ->get();
// Result: [Laptop ($1200), Monitor ($400)]

📖 DataFilter Documentation

5️⃣ SimpleDto - Immutable Dtos

Create type-safe, immutable Data Transfer Objects with automatic type casting:

use event4u\DataHelpers\SimpleDto\Attributes\AutoCast;

#[AutoCast]  // Enable automatic type casting (opt-in for performance)
class ReadmeUserDto extends SimpleDto
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
        public readonly int $age,
    ) {}
}

// Automatic type conversion with #[AutoCast]
$user = ReadmeUserDto::fromArray([
    'name' => 'John',
    'email' => 'john@example.com',
    'age' => '30'  // String "30" → int 30 (automatic)
]);

// Without #[AutoCast]: Strict types, better performance
class StrictUserDto extends SimpleDto
{
    public function __construct(
        public readonly string $name,
        public readonly int $age,  // Must be int, no conversion
    ) {}
}

📖 SimpleDto Documentation

6️⃣ LiteDto - Ultra-Fast Dtos

Create ultra-fast, minimalistic DTOs with essential features:

use event4u\DataHelpers\LiteDto\LiteDto;
use event4u\DataHelpers\LiteDto\Attributes\MapFrom;
use event4u\DataHelpers\LiteDto\Attributes\Hidden;

class UserDto extends LiteDto
{
    public function __construct(
        public readonly string $name,

        #[MapFrom('email_address')]
        public readonly string $email,

        #[Hidden]
        public readonly string $password,
    ) {}
}

$user = UserDto::from([
    'name' => 'John',
    'email_address' => 'john@example.com',
    'password' => 'secret',
]);

$array = $user->toArray();
// ['name' => 'John', 'email' => 'john@example.com']
// password is hidden

Performance: LiteDto is 7.6x faster than SimpleDto Normal (~2.3μs vs ~18.5μs)

📖 LiteDto Documentation

3️⃣ DataMapper - Transform Data

Map between different data structures with templates:

$source = [
    'user' => ['name' => 'John Doe', 'email' => 'john@example.com'],
    'orders' => [
        ['id' => 1, 'status' => 'shipped', 'total' => 100],
        ['id' => 2, 'status' => 'pending', 'total' => 50],
        ['id' => 3, 'status' => 'shipped', 'total' => 200],
    ],
];

$result = DataMapper::from($source)
    ->template([
        'customer_name' => '{{ user.name }}',
        'customer_email' => '{{ user.email }}',
        'shipped_orders' => [
            'WHERE' => [
                '{{ orders.*.status }}' => 'shipped',
            ],
            'ORDER BY' => [
                '{{ orders.*.total }}' => 'DESC',
            ],
            '*' => [
                'id' => '{{ orders.*.id }}',
                'total' => '{{ orders.*.total }}',
            ],
        ],
    ])
    ->map()
    ->getTarget();

💡 No-Code Data Mapping: Templates can be stored in a database and created with a drag-and-drop editor - perfect for import wizards, API integrations, and ETL pipelines without writing code!

📖 DataMapper Documentation

🎯 Advanced Features

No-Code Data Mapping

Store templates in database and create mappings without programming:

// Load template from database (created with drag-and-drop editor)
$template = Mappings::find(3)->template;

$result = DataMapper::from($source)
    ->template($template)
    ->map()
    ->getTarget();

Perfect for:

📥 Import Wizards - Let users map CSV/Excel columns to your data model
🔌 API Integration - Configure API mappings without code changes
🏢 Multi-Tenant Systems - Each tenant can have custom data mappings
🔄 Dynamic ETL - Build data transformation pipelines visually
📝 Form Builders - Map form submissions to different data structures

📖 Template-Based Mapping Guide

Complex Nested Mapping

Map complex nested structures to Eloquent Models or Doctrine Entities:

// Automatic relation detection for Eloquent/Doctrine
$company = new Company();
$result = DataMapper::from($jsonData)
    ->target($company)
    ->template([
        'name' => '{{ company.name }}',
        'departments' => [
            '*' => [
                'name' => '{{ company.departments.*.name }}',
                'budget' => '{{ company.departments.*.budget }}',
            ],
        ],
    ])
    ->map()
    ->getTarget();

✅ Automatic Relation Detection
✅ Type Casting (string → int/float/bool)
✅ Snake_case → camelCase conversion
✅ Nested Wildcards

📖 Advanced Mapping Guide

Pipeline API

Transform data with composable filters:

use Tests\Utils\Docu\TrimStrings;
use Tests\Utils\Docu\LowercaseEmails;
use Tests\Utils\Docu\SkipEmptyValues;

$source = ['name' => '  John  ', 'email' => 'JOHN@EXAMPLE.COM'];
$mapping = ['name' => '{{ name }}', 'email' => '{{ email }}'];

$result = DataMapper::from($source)
    ->template($mapping)
    ->pipeline([
        new TrimStrings(),
        new LowercaseEmails(),
        new SkipEmptyValues(),
    ])
    ->map()
    ->getTarget();

// $result = ['name' => 'John', 'email' => 'john@example.com']

📖 Pipeline Documentation

Template Expressions

Use Twig-like expressions with 18+ built-in filters:

$mapping = [
    'name' => '{{ user.firstName | ucfirst }} {{ user.lastName | ucfirst }}',
    'email' => '{{ user.email | lower | trim }}',
    'role' => '{{ user.role | upper ?? "USER" }}',
];

📖 Template Expressions

Query Builder

Laravel-style fluent interface for building queries:

$result = DataMapper::query()
    ->source('products', $data)
    ->where('category', 'Electronics')
    ->where('price', '>', 100)
    ->orderBy('price', 'DESC')
    ->groupBy('category', ['total' => ['COUNT']])
    ->get();

📖 Query Builder Documentation

📚 Documentation

Comprehensive documentation with guides, examples, and API reference is available at:

🔗 event4u-app.github.io/data-helpers

The documentation includes:

📖 Getting Started Guides - Installation, configuration, and quick start tutorials
🔧 Main Classes - Detailed guides for DataAccessor, DataMutator, DataMapper, and DataFilter
🎯 SimpleDto - Type-safe Dtos with validation, casting, and collections
⚡ LiteDto - Ultra-fast, minimalistic Dtos (7.6x faster than SimpleDto)
🚀 Advanced Features - Template expressions, query builder, pipelines, and reverse mapping
🔌 Framework Integration - Laravel, Symfony, and Doctrine integration guides
💡 90+ Code Examples - Runnable examples for every feature
📊 Performance Benchmarks - Optimization tips and benchmark results
🔍 Complete API Reference - Full API documentation for all classes and methods

🧪 Testing & Quality

✅ 3500+ tests with comprehensive coverage
✅ PHPStan Level 9 - Highest static analysis level
✅ 100% type coverage - All methods fully typed
✅ Continuous Integration - Automated testing across PHP 8.2, 8.3, 8.4

📖 Contributing Guide • Development Setup

⚡ Performance

All operations are highly optimized:

Simple access: ~0.2μs
Nested access: ~0.3μs
Wildcards: ~5μs
SimpleDto #[UltraFast] is up to 34.0x faster than Other Serializer

📖 Performance Benchmarks • Optimization Tips

🤝 Contributing

Contributions are welcome! Please see the Contributing Guide for details.

# Install dependencies
composer install

# Run tests
composer test

# Run quality checks
composer quality

💖 Sponsoring

This package is part of the event4u ecosystem - a comprehensive event management platform. Your sponsorship helps us:

🚀 Develop event4u - The next-generation event management app
📦 Maintain open-source packages - Like this Data Helpers library
🔧 Build new tools - More packages and utilities for the PHP community
📚 Improve documentation - Better guides and examples
🐛 Fix bugs faster - Dedicated time for maintenance and support

Support the Development

Every contribution, no matter how small, makes a difference and is greatly appreciated! 🙏

📄 License

MIT License. See LICENSE for details.

🌟 Show Your Support

If this package helps you, please consider:

⭐ Giving it a star on GitHub
💖 Sponsoring the development
📢 Sharing it with others

galawork / data-helpers

Maintainers

Details