README

Carapace is a lightweight PHP library for building immutable, strictly typed Data Transfer Objects (DTOs). It leverages PHP attributes for casting, property mapping, and serialization, while providing a simple, expressive API.

Features

• Mutable + Immutable DTOs: Define data objects by extending the Data base class, or use ImmutableData for readonly DTOs.
• Attribute-Driven Mapping: Use PHP attributes like CastWith, MapFrom, MapTo, and Hidden to control how data is hydrated, transformed, and serialized with minimal boilerplate.
• Strictly Typed: Leverage PHP's type system for predictable data structures.
• Framework-Agnostic: Works in Laravel, Symfony, or plain PHP projects.
• Simple API: Create, hydrate, and transform DTOs with minimal boilerplate.

Installation

composer require alamellama/carapace

Usage

use Alamellama\Carapace\Data;
use Alamellama\Carapace\Attributes\CastWith;
use Alamellama\Carapace\Attributes\Hidden;
use Alamellama\Carapace\Attributes\MapFrom;

class User extends Data
{
    public function __construct(
        public string $name,
        #[MapFrom('email_address')]
        public string $email,

        #[Hidden]
        public string $password,

        #[CastWith(Address::class)]
        public Address $address,
    ) {}
}

// Create from an array
$user = User::from([
    'name' => 'John Doe',
    'email_address' => 'john@example.com',
    'password' => 'secret',
    'address' => [
        'street' => '123 Main St',
        'city' => 'Anytown',
    ],
]);

// Create a modified copy
$updatedUser = $user->with(name: 'Jane Doe');

// Serialize
$array = $user->toArray(); // Password will be excluded
$json = $user->toJson();

Documentation

For detailed documentation, visit our documentation site.

Code Quality

Carapace follows PSR-12 coding standards with Laravel-style modifications. We use Laravel Pint for code style enforcement and Rector for automated refactoring. PHPStan is configured at a high strictness level.

# Apply automated fixes (Pint + Rector)
composer fix

# Run tests and quality checks
composer test

Testing

Carapace uses Pest PHP for testing and aims for 100% test coverage.

# Run all tests
composer test

Acknowledgements & Inspirations

In particular, we drew inspiration and ideas from:

• Spatie's data libraries, including spatie/data-transfer-object and spatie/laravel-data
• CuyZ/Valinor
• Symfony Serializer

We also rely on fantastic tooling that keeps this project reliable and maintainable:

• Pest PHP for testing
• PHPStan for static analysis
• Laravel Pint for code style
• Rector for automated refactoring

License

Carapace is open-sourced software licensed under the MIT license. See the LICENSE file for details.