PHPackages knobik/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. knobik/data-transfer-object ActiveLibrary[Utility & Helpers](/categories/utility) knobik/data-transfer-object =========================== Data transfer objects with batteries included 1.9.0(7y ago)09MITPHPPHP ^7.1 Since Oct 18Pushed 7y ago1 watchersCompare [ Source](https://github.com/knobik/data-transfer-object)[ Packagist](https://packagist.org/packages/knobik/data-transfer-object)[ Docs](https://github.com/knobik/data-transfer-object)[ RSS](/packages/knobik-data-transfer-object/feed)WikiDiscussions master Synced 2d ago READMEChangelogDependencies (2)Versions (25)Used By (0) Data transfer objects with batteries included ============================================= [](#data-transfer-objects-with-batteries-included) based on [![Latest Version on Packagist](https://camo.githubusercontent.com/692f7efac17f2c85af8843b3ef0548ac58071cef2c20f2c005a92f0c5f13ca3b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f646174612d7472616e736665722d6f626a6563742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/data-transfer-object)[![Build Status](https://camo.githubusercontent.com/e38fc9ea509184203f953733abbe78d2500f951ab19d29c999094e1dc8c1eef9/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f7370617469652f646174612d7472616e736665722d6f626a6563742f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/spatie/data-transfer-object)[![Quality Score](https://camo.githubusercontent.com/89e5c558c618ba3fffc990b10d79ce9f129012c1164cb1e3234ca3f183aff96b/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f7370617469652f646174612d7472616e736665722d6f626a6563742e7376673f7374796c653d666c61742d737175617265)](https://scrutinizer-ci.com/g/spatie/data-transfer-object)[![StyleCI](https://camo.githubusercontent.com/0196fbbce95084a9c9813b400d7ae5e2d8fe51670c14306b2382648496911507/68747470733a2f2f6769746875622e7374796c6563692e696f2f7265706f732f3135333633323231362f736869656c643f6272616e63683d6d6173746572)](https://github.styleci.io/repos/153632216)[![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 ``` 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. ### 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'] ] ]); ``` **Attention**: For nested type casting to work your Docblock definition needs to be a Fully Qualified Class Name (`\App\DTOs\TagData[]` instead of `TagData[]` and an use statement at the top) ### Immutability [](#immutability) If you want your data object to be never changeable (this is a good idea in some cases), you can make them immutable: ``` $postData = PostData::immutable([ 'tags' => [ ['name' => 'foo'], ['name' => 'bar'] ] ]); ``` Trying to change a property of `$postData` after it's constructed, will result in a `DataTransferObjectError`. ### 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 constructing a data transfer object, we'll validate whether all required (non-nullable) properties are set. If not, a `Spatie\DataTransferObject\DataTransferObjectError` will be thrown. Likewise, if you're trying to set non-defined properties, you'll get a `DataTransferObjectError`. ### 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. ### 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, Samberstraat 69D, 2060 Antwerp, Belgium. We publish all received postcards [on our company website](https://spatie.be/en/opensource/postcards). Credits ------- [](#credits) - [Brent Roose](https://github.com/brendt) - [All Contributors](../../contributors) Our `Arr` class contains functions copied from Laravels `Arr` helper. Support us ---------- [](#support-us) Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource). Does your business depend on our contributions? Reach out and support us on [Patreon](https://www.patreon.com/spatie). All pledges will be dedicated to allocating workforce on maintenance and new awesome stuff. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 29 — LowBetter than 57% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community16 Small or concentrated contributor base Maturity67 Established project with proven stability Bus Factor2 2 contributors hold 50%+ of commits 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 ~8 days Recently: every ~31 days Total 22 Last Release 2638d ago Major Versions 0.1.0 → 1.0.02018-10-24 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/795254?v=4)[knobik](/maintainers/knobik)[@knobik](https://github.com/knobik) --- Top Contributors [![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (16 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)")[![piotrgrabowskielastique](https://avatars.githubusercontent.com/u/47775107?v=4)](https://github.com/piotrgrabowskielastique "piotrgrabowskielastique (2 commits)")[![kevinsmith](https://avatars.githubusercontent.com/u/397904?v=4)](https://github.com/kevinsmith "kevinsmith (2 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)")[![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)") --- Tags spatiedata-transfer-objectknobik ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/knobik-data-transfer-object/health.svg) ``` [![Health](https://phpackages.com/badges/knobik-data-transfer-object/health.svg)](https://phpackages.com/packages/knobik-data-transfer-object) ``` ### Alternatives [spatie/laravel-package-tools Tools for creating Laravel packages 948138.7M8.9k](/packages/spatie-laravel-package-tools)[spatie/laravel-data Create unified resources and data transfer objects 1.8k33.0M882](/packages/spatie-laravel-data)[spatie/macroable A trait to dynamically add methods to a class 72962.7M72](/packages/spatie-macroable)[spatie/regex A sane interface for php's built in preg\_\* functions 1.1k18.9M68](/packages/spatie-regex)[spatie/enum PHP Enums 84931.4M74](/packages/spatie-enum)[spatie/laravel-collection-macros A set of useful Laravel collection macros 1.9k6.2M39](/packages/spatie-laravel-collection-macros) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)