alamellama / carapace
Framework-agnostic DTOs for PHP
Fund package maintenance!
alamellama
Requires
- php: ^8.2
Requires (Dev)
- laravel/pint: ^1.24
- peckphp/peck: ^0.1.3
- pestphp/pest: ^3.3.1|^4.0.3
- phpstan/phpstan: ^2.1
- rector/rector: ^2.1
This package is auto-updated.
Last update: 2025-10-01 12:01:09 UTC
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.