PHPackages                             larapie/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. [Validation & Sanitization](/categories/validation)
4. /
5. larapie/data-transfer-object

ActiveLibrary[Validation & Sanitization](/categories/validation)

larapie/data-transfer-object
============================

Data transfer objects with validation

3.1.2(7y ago)29682MITPHPPHP ^7.1

Since Oct 18Pushed 6y ago1 watchersCompare

[ Source](https://github.com/larapie/data-transfer-object)[ Packagist](https://packagist.org/packages/larapie/data-transfer-object)[ Docs](https://github.com/larapie/data-transfer-object)[ RSS](/packages/larapie-data-transfer-object/feed)WikiDiscussions master Synced today

READMEChangelog (9)Dependencies (6)Versions (31)Used By (0)

Data transfer objects with validation through annotations
=========================================================

[](#data-transfer-objects-with-validation-through-annotations)

[![Latest Stable Version](https://camo.githubusercontent.com/5e74bd7a5a40d460f46cf212362b766ded66650c8c91a67464d743a489702716/68747470733a2f2f706f7365722e707567782e6f72672f6c6172617069652f646174612d7472616e736665722d6f626a6563742f762f737461626c65)](https://packagist.org/packages/larapie/data-transfer-object)[![Build Status](https://camo.githubusercontent.com/d199ac28f533ecc2b263973775c2ecd27b98309c87d6e478fad9f818f77431bd/68747470733a2f2f7472617669732d63692e6f72672f6c6172617069652f646174612d7472616e736665722d6f626a6563742e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/larapie/data-transfer-object)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/6db400d77ec38b2a9882bc79681da1f0c39f85bf8009bb3d3dbc6f8275accc95/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c6172617069652f646174612d7472616e736665722d6f626a6563742f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/larapie/data-transfer-object/?branch=master)[![Code Coverage](https://camo.githubusercontent.com/9aaf12644940d4c317d24177424044caac4932b73b82620de3c71df6fead2493/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c6172617069652f646174612d7472616e736665722d6f626a6563742f6261646765732f636f7665726167652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/larapie/data-transfer-object/?branch=master)[![StyleCI](https://camo.githubusercontent.com/bf9f696fccfd5dd07ae43f0a852327e33ab5af44b738efdc981b33e4fca598b5/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3137373633363536372f736869656c643f6272616e63683d6d6173746572)](https://github.styleci.io/repos/177636567)[![Total Downloads](https://camo.githubusercontent.com/9f0dee37ceade7a54641ec77b3fa147933702db21c3d6452f9bf41e44a276a7e/68747470733a2f2f706f7365722e707567782e6f72672f6c6172617069652f646174612d7472616e736665722d6f626a6563742f646f776e6c6f616473)](https://packagist.org/packages/larapie/data-transfer-object)

Note
----

[](#note)

Even though most of the codebase has been rewritten entirely. This project was originally forked from (). The base repository is still maintained by spatie (). Our goal is to increase the performance (mostly through caching of the reflection properties) and improve this package with additional features (see more below).

#### Improvements:

[](#improvements)

- Improved immutability.
- Reflection property & annotation caching (for improved performance).
- Fully qualified name resolving.
- Immutable properties (through annotations).
- Validation (through annotations).
- Overriding & adding properties.
- Optional property support.
- Annotation/validation inheritance.

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

[](#installation)

You can install the package via composer:

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

Have you ever…
--------------

[](#have-you-ever)

… worked with an array of data, retrieved from a request, a CSV file or a JSON API; and wondered what was in it?

Here's an example:

```
public function handleRequest(array $dataFromRequest)
{
    $dataFromRequest[/* what to do now?? */];
}
```

The goal of this package is to structure "unstructured data", which is normally stored in associative arrays. By structuring this data into an object, we gain several advantages:

- We're able to type hint data transfer objects, instead of just calling them `array`.
- By making all properties on our objects typeable, we're sure that their values are never something we didn't expect.
- Because of typed properties, we can statically analyze them and have auto completion.

Let's look at the example of a JSON API call:

```
$post = $api->get('posts', 1);

[
    'title' => '…',
    'body' => '…',
    'author_id' => '…',
]
```

Working with this array is difficult, as we'll always have to refer to the documentation to know what's exactly in it. This package allows you to create data transfer object definitions, classes, which will represent the data in a structured way.

We did our best to keep the syntax and overhead as little as possible:

```
class PostData extends DataTransferObject
{
    /** @var string */
    public $title;

    /** @var string */
    public $body;

    /** @var \Author */
    public $author;
}
```

An object of `PostData` can from now on be constructed like so:

```
$postData = new PostData([
    'title' => '…',
    'body' => '…',
    'author_id' => '…',
]);
```

Now you can use this data in a structured way:

```
$postData->title;
$postData->body;
$postData->author_id;
```

It's, of course, possible to add static constructors to `PostData`:

```
class PostData extends DataTransferObject
{
    // …

    public static function fromRequest(Request $request): self
    {
        return new self([
            'title' => $request->get('title'),
            'body' => $request->get('body'),
            'author' => Author::find($request->get('author_id')),
        ]);
    }
}
```

By adding doc blocks to our properties, their values will be validated against the given type; and a `TypeError` will be thrown if the value doesn't comply with the given type.

Here are the possible ways of declaring types:

```
class PostData extends DataTransferObject
{
    /**
     * Built in types:
     *
     * @var string
     */
    public $property;

    /**
     * Classes with their FQCN:
     *
     * @var \App\Models\Author
     */
    public $property;

    /**
     * Lists of types:
     *
     * @var \App\Models\Author[]
     */
    public $property;

    /**
     * Union types:
     *
     * @var string|int
     */
    public $property;

    /**
     * Nullable types:
     *
     * @var string|null
     */
    public $property;

    /**
     * Mixed types:
     *
     * @var mixed|null
     */
    public $property;

    /**
     * No type, which allows everything
     */
    public $property;
}
```

When PHP 7.4 introduces typed properties, you'll be able to simply remove the doc blocks and type the properties with the new, built-in syntax.

### Immutability

[](#immutability)

If you want your data object to be never changeable (this is a good idea in some cases), you can make it immutable:

```
class PostData extends DataTransferObject
{
    use MakeImmutable;

    /** @var string */
    public $name;
}
```

If you only want to make a certain property immutable you can annotate this on the variable.

```
class PostData extends DataTransferObject
{
    /**
     * @Immutable
     * @var string $name
     */
    public $name;
}
```

Trying to change a property of `$postData` after it's constructed, will result in a `ImmutableDtoException`.

### Optional Properties

[](#optional-properties)

By default all dto properties are required. If you want to make certain properties on the dto optional:

```
class PostData extends DataTransferObject
{
    /**
     * @Optional
     * @var string $name
     */
    public $name;
}
```

###### Note

[](#note-1)

The default value will NOT be set when a property is annotated as optional!

### Additional Properties

[](#additional-properties)

By default only dto properties can be set on the dto. Attempting to input data that is not declared as a public property on the dto will throw a `UnknownPropertiesDtoException`. If you want to allow additional properties you can do so by implementing the `AdditionalProperties` or `WithAdditionalProperties` interface.

AdditionalProperties:

```
class PostData extends DataTransferObject implements AdditionalProperties
{
    /**
     * @var string $name
     */
    public $name;
}

$dto = new PostData(["name" => "foo", "address" => "bar"]);
$dto->toArray();

returns:
["name" => "foo"]
```

WithAdditionalProperties:

```
class PostData extends DataTransferObject implements WithAdditionalProperties
{
    /**
     * @var string $name
     */
    public $name;
}

$dto = new PostData(["name" => "foo", "address" => "bar"]);
$dto->toArray();

returns:
["name" => "foo", "address" => "bar"]
```

### Overriding & Adding Properties

[](#overriding--adding-properties)

If you want to add or override a certain value on the dto you can do it as follows:

Adding Data:

```
    public function create(PostData $data, User $user)
    {
        $data->with('user_id', $user->id);
        return $this->repository->create($data->toArray());
    }
```

Overriding Property:

```
    public function create(PostData $data, User $user)
    {
        if($this->user->isAdmin()){
            $data->override('name', 'admin');
        }
        $data->with('user_id', $user->id);
        return $this->repository->create($data->toArray());
    }
```

##### Notes:

[](#notes)

- You cannot add or override data on an immutable dto. You also can't override immutable properties.
- You cannot use the with method to add properties that are declared as public properties on the dto.

### Validation

[](#validation)

##### Constraints

[](#constraints)

If you want to validate the input of a property. You can do so through annotations.

```
class PostData extends DataTransferObject
{
    /**
     * @var string
     * @Assert\NotBlank()
     * @Assert\Length(min = 3, max = 20)
     */
    public $name;
}
```

##### Inheritence

[](#inheritence)

If you want to extend a dto and add extra constraints or the optional annotation you can do so by adding the `Inherit` annotation. This will merge all existing constraints from the parent class. If no type is specified on the current class it will also inherit the type of the parent dto.

```
class UpdatePostData extends PostData
{
    /**
     * @Optional
     * @Inherit
     */
    public $name;
}
```

##### Notes:

[](#notes-1)

- If you are using phpstorm you can install this plugin:  to typehint the annotations.
- The `Optional` annotation will not be inherited from the parent class. This is to ensure you always have a clear overview of what values are required in a dto.
- Validation is NOT done upon constructing the object. But only when accessing the variables. This can be done through the magic \_\_get method `$dto->property` or when outputting the values of the array through the `toArray()` or `all()` methods. You could also call the `validate()` method manually. If the dto is not valid it will throw a `ValidatorException`.
- The `ValidatorException` message will include all the property names and the constraints that have failed on that specific property. For example: `property 'author_name' is required`.
- To implement this functionality the excellent `symfony\validation` library was used. For more info please check  .

### Working with collections

[](#working-with-collections)

If you're working with collections of DTOs, you probably want auto completion and proper type validation on your collections too. This package adds a simple collection implementation, which you can extend from.

```
use \Spatie\DataTransferObject\DataTransferObjectCollection;

class PostCollection extends DataTransferObjectCollection
{
    public function current(): PostData
    {
        return parent::current();
    }
}
```

By overriding the `current` method, you'll get auto completion in your IDE, and use the collections like so.

```
foreach ($postCollection as $postData) {
    $postData-> // … your IDE will provide autocompletion.
}

$postCollection[0]-> // … and also here.
```

Of course you're free to implement your own static constructors:

```
class PostCollection extends DataTransferObjectCollection
{
    public static function create(array $data): PostCollection
    {
        $collection = [];

        foreach ($data as $item)
        {
            $collection[] = PostData::create($item);
        }

        return new self($collection);
    }
}
```

### Automatic casting of nested DTOs

[](#automatic-casting-of-nested-dtos)

If you've got nested DTO fields, data passed to the parent DTO will automatically be casted.

```
class PostData extends DataTransferObject
{
    /** @var \AuthorData */
    public $author;
}
```

`PostData` can now be constructed like so:

```
$postData = new PostData([
    'author' => [
        'name' => 'Foo',
    ],
]);
```

### Automatic casting of nested array DTOs

[](#automatic-casting-of-nested-array-dtos)

Similarly to above, nested array DTOs will automatically be casted.

```
class TagData extends DataTransferObject
{
    /** @var string */
   public $name;
}

class PostData extends DataTransferObject
{
    /** @var \TagData[] */
   public $tags;
}
```

`PostData` will automatically construct tags like such:

```
$postData = new PostData([
    'tags' => [
        ['name' => 'foo'],
        ['name' => 'bar']
    ]
]);
```

### 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();
```

You can also chain these 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.

### Exception handling

[](#exception-handling)

Beside property type validation, you can also be certain that the data transfer object in its whole is always valid. On outputting the data from a data transfer object (through the `all()` & `toArray()` methods and also when you access the properties of the dto e.g. `$dto->name`) , we'll validate whether all required properties are set, if the constraints are met and if each property is of the correct type. If not, a `Larapie\DataTransferObject\Exceptions\ValidatorException` will be thrown.

Likewise, if you're trying to set non-defined properties, you'll get a `Larapie\DataTransferObject\Exceptions\UnknownPropertiesDtoException`.

### Testing

[](#testing)

```
composer test
```

### Changelog

[](#changelog)

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

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

[](#contributing)

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

Credits
-------

[](#credits)

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

License
-------

[](#license)

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

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity18

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 51.6% 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 ~6 days

Total

30

Last Release

2564d ago

Major Versions

0.1.0 → 1.0.02018-10-24

1.8.0 → 2.0.02019-04-15

2.3.0 → 3.0.02019-04-28

### Community

Maintainers

![](https://www.gravatar.com/avatar/7df91709af6a5763e0a798d92645cfa35a20f18444cce401225f5a889c9d63ad?d=identicon)[larapie](/maintainers/larapie)

---

Top Contributors

[![anthonyvancauwenberghe](https://avatars.githubusercontent.com/u/7100315?v=4)](https://github.com/anthonyvancauwenberghe "anthonyvancauwenberghe (126 commits)")[![brendt](https://avatars.githubusercontent.com/u/6905297?v=4)](https://github.com/brendt "brendt (71 commits)")[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (16 commits)")[![larapie](https://avatars.githubusercontent.com/u/48988808?v=4)](https://github.com/larapie "larapie (10 commits)")[![bhulsman](https://avatars.githubusercontent.com/u/612651?v=4)](https://github.com/bhulsman "bhulsman (8 commits)")[![sasa-b](https://avatars.githubusercontent.com/u/18427949?v=4)](https://github.com/sasa-b "sasa-b (3 commits)")[![kevinsmith](https://avatars.githubusercontent.com/u/397904?v=4)](https://github.com/kevinsmith "kevinsmith (2 commits)")[![amitmerchant1990](https://avatars.githubusercontent.com/u/3647841?v=4)](https://github.com/amitmerchant1990 "amitmerchant1990 (1 commits)")[![XavRsl](https://avatars.githubusercontent.com/u/1185840?v=4)](https://github.com/XavRsl "XavRsl (1 commits)")[![brodyandhooper](https://avatars.githubusercontent.com/u/50821617?v=4)](https://github.com/brodyandhooper "brodyandhooper (1 commits)")[![JayBizzle](https://avatars.githubusercontent.com/u/340752?v=4)](https://github.com/JayBizzle "JayBizzle (1 commits)")[![panda-madness](https://avatars.githubusercontent.com/u/6180087?v=4)](https://github.com/panda-madness "panda-madness (1 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")[![sebastiandedeyne](https://avatars.githubusercontent.com/u/1561079?v=4)](https://github.com/sebastiandedeyne "sebastiandedeyne (1 commits)")[![svenluijten](https://avatars.githubusercontent.com/u/11269635?v=4)](https://github.com/svenluijten "svenluijten (1 commits)")

---

Tags

annotationsdata-transfer-objectdtophpvalidationphpspatievalidationannotationsdata-transfer-objectdtolarapie

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[wendelladriel/laravel-validated-dto

Data Transfer Objects with validation for Laravel applications

759569.4k13](/packages/wendelladriel-laravel-validated-dto)[yorcreative/laravel-argonaut-dto

Argonaut is a lightweight Data Transfer Object (DTO) package for Laravel that supports nested casting, recursive serialization, and validation out of the box. Ideal for service layers, APIs, and clean architecture workflows.

1062.8k1](/packages/yorcreative-laravel-argonaut-dto)[friendsofhyperf/validated-dto

The Data Transfer Objects with validation for Hyperf.

1412.9k](/packages/friendsofhyperf-validated-dto)[event4u/data-helpers

Framework-agnostic PHP library for data mapping, DTOs and utilities. Includes DataMapper, SimpleDto/LiteDto, DataAccessor/Mutator/Filter and helper classes (MathHelper, EnvHelper, etc.). Works with Laravel, Symfony/Doctrine or standalone PHP.

1421.5k](/packages/event4u-data-helpers)[fab2s/dt0

Immutable DTOs with bidirectional casting. No framework required. 8x faster than the alternative.

101.6k1](/packages/fab2s-dt0)

PHPackages © 2026

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