PHPackages                             roke22/data-transfer-object - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. roke22/data-transfer-object

ActiveLibrary[Utility & Helpers](/categories/utility)

roke22/data-transfer-object
===========================

Data transfer objects with batteries included

3.3.1(4y ago)0660MITPHPPHP ^8.0

Since Oct 18Pushed 4y agoCompare

[ Source](https://github.com/roke22/data-transfer-object)[ Packagist](https://packagist.org/packages/roke22/data-transfer-object)[ Docs](https://github.com/roke22/data-transfer-object)[ Fund](https://spatie.be/open-source/support-us)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/roke22-data-transfer-object/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (57)Used By (0)

Data transfer objects with batteries included
=============================================

[](#data-transfer-objects-with-batteries-included)

[![Latest Version on Packagist](https://camo.githubusercontent.com/692f7efac17f2c85af8843b3ef0548ac58071cef2c20f2c005a92f0c5f13ca3b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f646174612d7472616e736665722d6f626a6563742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/data-transfer-object)[![Test](https://github.com/spatie/data-transfer-object/workflows/Test/badge.svg)](https://github.com/spatie/data-transfer-object/workflows/Test/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/d079403ccd6a131eb0d63f48905bd3248a7f9bdc52f14dfd139c26d8cb252e1f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f646174612d7472616e736665722d6f626a6563742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/data-transfer-object)

Installation
------------

[](#installation)

You can install the package via composer:

```
composer require spatie/data-transfer-object
```

- **Note**: v3 of this package only supports `php:^8.0`. If you're looking for the older version, check out [v2](https://github.com/spatie/data-transfer-object/tree/v2).

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/d4c6ccbae3269c999932ef18614a2ae97700443797cdb3c5ff9f393ac186d3af/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f646174612d7472616e736665722d6f626a6563742e6a70673f743d31)](https://spatie.be/github-ad-click/data-transfer-object)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Usage
-----

[](#usage)

The goal of this package is to make constructing objects from arrays of (serialized) data as easy as possible. Here's what a DTO looks like:

```
use Spatie\DataTransferObject\DataTransferObject;

class MyDTO extends DataTransferObject
{
    public OtherDTO $otherDTO;

    public OtherDTOCollection $collection;

    #[CastWith(ComplexObjectCaster::class)]
    public ComplexObject $complexObject;

    public ComplexObjectWithCast $complexObjectWithCast;

    #[NumberBetween(1, 100)]
    public int $a;
}
```

You could construct this DTO like so:

```
$dto = new MyDTO(
    a: 5,
    collection: [
        ['id' => 1],
        ['id' => 2],
        ['id' => 3],
    ],
    complexObject: [
        'name' => 'test',
    ],
    complexObjectWithCast: [
        'name' => 'test',
    ],
    otherDTO: ['id' => 5],
);
```

Let's discuss all possibilities one by one.

Named arguments
---------------

[](#named-arguments)

Constructing a DTO can be done with named arguments. It's also possible to still use the old array notation. This example is equivalent to the one above.

```
$dto = new MyDTO([
    'a' => 5,
    'collection' => [
        ['id' => 1],
        ['id' => 2],
        ['id' => 3],
    ],
    'complexObject' => [
        'name' => 'test',
    ],
    'complexObjectWithCast' => [
        'name' => 'test',
    ],
    'otherDTO' => ['id' => 5],
]);
```

Value casts
-----------

[](#value-casts)

If a DTO has a property that is another DTO or a DTO collection, the package will take care of automatically casting arrays of data to those DTOs:

```
$dto = new MyDTO(
    collection: [ // This will become an object of class OtherDTOCollection
        ['id' => 1],
        ['id' => 2], // Each item will be an instance of OtherDTO
        ['id' => 3],
    ],
    otherDTO: ['id' => 5], // This data will be cast to OtherDTO
);
```

### Custom casters

[](#custom-casters)

You can build your own caster classes, which will take whatever input they are given, and will cast that input to the desired result.

Take a look at the `ComplexObject`:

```
class ComplexObject
{
    public string $name;
}
```

And its caster `ComplexObjectCaster`:

```
use Spatie\DataTransferObject\Caster;

class ComplexObjectCaster implements Caster
{
    /**
     * @param array|mixed $value
     *
     * @return mixed
     */
    public function cast(mixed $value): ComplexObject
    {
        return new ComplexObject(
            name: $value['name']
        );
    }
}
```

### Class-specific casters

[](#class-specific-casters)

Instead of specifying which caster should be used for each property, you can also define that caster on the target class itself:

```
class MyDTO extends DataTransferObject
{
    public ComplexObjectWithCast $complexObjectWithCast;
}
```

```
#[CastWith(ComplexObjectWithCastCaster::class)]
class ComplexObjectWithCast
{
    public string $name;
}
```

### Default casters

[](#default-casters)

It's possible to define default casters on a DTO class itself. These casters will be used whenever a property with a given type is encountered within the DTO class.

```
#[
    DefaultCast(DateTimeImmutable::class, DateTimeImmutableCaster::class),
    DefaultCast(MyEnum::class, EnumCaster::class),
]
abstract class BaseDataTransferObject extends DataTransferObject
{
    public MyEnum $status; // EnumCaster will be used

    public DateTimeImmutable $date; // DateTimeImmutableCaster will be used
}
```

### Using custom caster arguments

[](#using-custom-caster-arguments)

Any caster can be passed custom arguments, the built-in `ArrayCaster` implementation is such an example:

```
class ArrayCaster implements Caster
{
    public function __construct(
        private string $type,
        private string $itemType,
    ) {
    }

    public function cast(mixed $value): array|ArrayAccess
    {
        if ($this->type == 'array') {
            return $this->castArray($value);
        }

        if (is_subclass_of($this->type, ArrayAccess::class)) {
            return $this->castArrayAccess($value);
        }

        throw new LogicException("Caster [ArrayCaster] may only be used to cast arrays or objects that implement ArrayAccess.");
    }

    private function castArray(mixed $value): array
    {
        return array_map(
            fn(array $data) => new $this->itemType(...$data),
            $value
        );
    }

    private function castArrayAccess(mixed $value): ArrayAccess
    {
        $arrayAccess = new $this->type();

        array_walk(
            $value,
            fn(array $data) => $arrayAccess[] = new $this->itemType(...$data)
        );

        return $arrayAccess;
    }
}
```

Note that you don't need to use named arguments to pass input as generic caster arguments, though they do make it more clear:

```
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, itemType: Foo::class)]
    public array $collectionWithNamedArguments;

    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, Foo::class)]
    public array $collectionWithoutNamedArguments;
```

Also note that the first argument passed to the caster constructor is always the type of the value being casted. All other arguments will be the ones passed as extra arguments in the `CastWith` attribute.

Validation
----------

[](#validation)

This package doesn't offer any specific validation functionality, but it does give you a way to build your own validation attributes. For example, `NumberBetween` is a user-implemented validation attribute:

```
class MyDTO extends DataTransferObject
{
    #[NumberBetween(1, 100)]
    public int $a;
}
```

It works like this under the hood:

```
#[Attribute(Attribute::TARGET_PROPERTY | Attribute::IS_REPEATABLE)]
class NumberBetween implements Validator
{
    public function __construct(
        private int $min,
        private int $max
    ) {
    }

    public function validate(mixed $value): ValidationResult
    {
        if ($value < $this->min) {
            return ValidationResult::invalid("Value should be greater than or equal to {$this->min}");
        }

        if ($value > $this->max) {
            return ValidationResult::invalid("Value should be less than or equal to {$this->max}");
        }

        return ValidationResult::valid();
    }
}
```

Strict DTOs
-----------

[](#strict-dtos)

The previous version of this package added the `FlexibleDataTransferObject` class which allowed you to ignore properties that didn't exist on the DTO. This behaviour has been changed, all DTOs are flexible now by default, but you can make them strict by using the `#[Strict]` attribute:

```
class NonStrictDto extends DataTransferObject
{
    public string $name;
}

// This works
new NonStrictDto(
    name: 'name',
    unknown: 'unknown'
);
```

```
use \Spatie\DataTransferObject\Attributes\Strict;

#[Strict]
class StrictDto extends DataTransferObject
{
    public string $name;
}

// This throws a \Spatie\DataTransferObject\Exceptions\UnknownProperties exception
new StrictDto(
    name: 'name',
    unknown: 'unknown'
);
```

Helper functions
----------------

[](#helper-functions)

There are also some helper functions provided for working with multiple properties at once.

```
$postData->all();

$postData
    ->only('title', 'body')
    ->toArray();

$postData
    ->except('author')
    ->toArray();
```

Note that `all()` will simply return all properties, while `toArray()` will cast nested DTOs to arrays as well.

You can chain the `except()` and `only()` methods:

```
$postData
    ->except('title')
    ->except('body')
    ->toArray();
```

It's important to note that `except()` and `only()` are immutable, they won't change the original data transfer object.

Immutable DTOs and cloning
--------------------------

[](#immutable-dtos-and-cloning)

This package doesn't force immutable objects since PHP doesn't support them, but you're always encouraged to keep your DTOs immutable. To help you, there's a `clone` method on every DTO which accepts data to override:

```
$clone = $original->clone(other: ['name' => 'a']);
```

Note that no data in `$original` is changed.

Collections of DTOs
-------------------

[](#collections-of-dtos)

This version removes the `DataTransferObjectCollection` class. Instead you can use simple casters and you own collection classes.

Here's an example of casting a collection of DTOs to an array of DTOs:

```
class Bar extends DataTransferObject
{
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(FooArrayCaster::class)]
    public array $collectionOfFoo;
}

class Foo extends DataTransferObject
{
    public string $name;
}
```

```
class FooArrayCaster implements Caster
{
    public function cast(mixed $value): array
    {
        if (! is_array($value)) {
            throw new Exception("Can only cast arrays to Foo");
        }

        return array_map(
            fn (array $data) => new Foo(...$data),
            $value
        );
    }
}
```

If you don't want the redundant typehint, or want extended collection functionality; you could create your own collection classes using any collection implementation. In this example, we use Laravel's:

```
class Bar extends DataTransferObject
{
    #[CastWith(FooCollectionCaster::class)]
    public CollectionOfFoo $collectionOfFoo;
}

class Foo extends DataTransferObject
{
    public string $name;
}
```

```
use Illuminate\Support\Collection;

class CollectionOfFoo extends Collection
{
    // Add the correct return type here for static analyzers to know which type of array this is
    public function offsetGet($key): Foo
    {
        return parent::offsetGet($key);
    }
}
```

```
class FooCollectionCaster implements Caster
{
    public function cast(mixed $value): CollectionOfFoo
    {
        return new CollectionOfFoo(array_map(
            fn (array $data) => new Foo(...$data),
            $value
        ));
    }
}
```

Simple arrays of DTOs
---------------------

[](#simple-arrays-of-dtos)

For a simple array of DTOs, or an object that implements PHP's built-in `ArrayAccess`, consider using the `ArrayCaster` which requires an item type to be provided:

```
class Bar extends DataTransferObject
{
    /** @var \Spatie\DataTransferObject\Tests\Foo[] */
    #[CastWith(ArrayCaster::class, itemType: Foo::class)]
    public array $collectionOfFoo;
}
```

Testing
-------

[](#testing)

```
composer test
```

### Changelog

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

### Security

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker.

Postcardware
------------

[](#postcardware)

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.

We publish all received postcards [on our company website](https://spatie.be/en/opensource/postcards).

External tools
--------------

[](#external-tools)

- [json2dto](https://json2dto.atymic.dev): a GUI to convert JSON objects to DTO classes (with nesting support). Also provides a [CLI tool](https://github.com/atymic/json2dto#cli-tool) for local usage.
- [Data Transfer Object Factory](https://github.com/anteris-dev/data-transfer-object-factory): Intelligently generates a DTO instance using the correct content for your properties based on its name and type.

Credits
-------

[](#credits)

- [Brent Roose](https://github.com/brendt)
- [All Contributors](../../contributors)

Our `Arr` class contains functions copied from Laravels `Arr` helper.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity80

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 66.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~19 days

Total

54

Last Release

1760d ago

Major Versions

0.1.0 → 1.0.02018-10-24

1.13.3 → 2.0.02020-04-28

v2.x-dev → 3.0.02021-04-02

PHP version history (4 changes)0.0.1PHP ^7.1

2.0.0PHP ^7.4

2.6.0PHP ^7.4|^8.0

3.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/b2e29770fa56f161118f0b401453c0ce7f49f44639e427fcffd0df5eec3b2069?d=identicon)[roke22](/maintainers/roke22)

---

Top Contributors

[![brendt](https://avatars.githubusercontent.com/u/6905297?v=4)](https://github.com/brendt "brendt (234 commits)")[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (18 commits)")[![mfn](https://avatars.githubusercontent.com/u/87493?v=4)](https://github.com/mfn "mfn (15 commits)")[![morrislaptop](https://avatars.githubusercontent.com/u/67807?v=4)](https://github.com/morrislaptop "morrislaptop (14 commits)")[![rubenvanassche](https://avatars.githubusercontent.com/u/619804?v=4)](https://github.com/rubenvanassche "rubenvanassche (10 commits)")[![bhulsman](https://avatars.githubusercontent.com/u/612651?v=4)](https://github.com/bhulsman "bhulsman (8 commits)")[![bastien-phi](https://avatars.githubusercontent.com/u/10199039?v=4)](https://github.com/bastien-phi "bastien-phi (8 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (4 commits)")[![koomai](https://avatars.githubusercontent.com/u/1274618?v=4)](https://github.com/koomai "koomai (4 commits)")[![pikant](https://avatars.githubusercontent.com/u/24542171?v=4)](https://github.com/pikant "pikant (3 commits)")[![jantonzataca](https://avatars.githubusercontent.com/u/215002742?v=4)](https://github.com/jantonzataca "jantonzataca (3 commits)")[![cappuc](https://avatars.githubusercontent.com/u/4271608?v=4)](https://github.com/cappuc "cappuc (3 commits)")[![joaorobertopb](https://avatars.githubusercontent.com/u/6556083?v=4)](https://github.com/joaorobertopb "joaorobertopb (3 commits)")[![sasa-b](https://avatars.githubusercontent.com/u/18427949?v=4)](https://github.com/sasa-b "sasa-b (3 commits)")[![atymic](https://avatars.githubusercontent.com/u/50683531?v=4)](https://github.com/atymic "atymic (3 commits)")[![doox911-opensource](https://avatars.githubusercontent.com/u/74534192?v=4)](https://github.com/doox911-opensource "doox911-opensource (2 commits)")[![kevinsmith](https://avatars.githubusercontent.com/u/397904?v=4)](https://github.com/kevinsmith "kevinsmith (2 commits)")[![aidan-casey](https://avatars.githubusercontent.com/u/6686277?v=4)](https://github.com/aidan-casey "aidan-casey (2 commits)")[![telkins](https://avatars.githubusercontent.com/u/53731?v=4)](https://github.com/telkins "telkins (2 commits)")[![XavRsl](https://avatars.githubusercontent.com/u/1185840?v=4)](https://github.com/XavRsl "XavRsl (1 commits)")

---

Tags

data-transfer-objectroke22

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/roke22-data-transfer-object/health.svg)

```
[![Health](https://phpackages.com/badges/roke22-data-transfer-object/health.svg)](https://phpackages.com/packages/roke22-data-transfer-object)
```

###  Alternatives

[cerbero/dto

Data Transfer Object (DTO)

17119.4k1](/packages/cerbero-dto)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)