From data to resource | laravel-data | Spatie SPATIE Laravel Data =============== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-data](https://spatie.be/docs/laravel-data/v4) As-a-resource From data to resource Version v4 v3 v2 v1 Other versions for crawler [v4](https://spatie.be/docs/laravel-data/v4) [v3](https://spatie.be/docs/laravel-data/v3) [v2](https://spatie.be/docs/laravel-data/v2) [v1](https://spatie.be/docs/laravel-data/v1) - [ Introduction ](https://spatie.be/docs/laravel-data/v4/introduction) - [ Support us ](https://spatie.be/docs/laravel-data/v4/support-us) - [ Requirements ](https://spatie.be/docs/laravel-data/v4/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-data/v4/installation-setup) - [ Third party packages ](https://spatie.be/docs/laravel-data/v4/third-party-packages) - [ Questions and issues ](https://spatie.be/docs/laravel-data/v4/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-data/v4/changelog) - [ About us ](https://spatie.be/docs/laravel-data/v4/about-us) Getting started --------------- - [ Quickstart ](https://spatie.be/docs/laravel-data/v4/getting-started/quickstart) As a DTO -------- - [ Creating a data object ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/creating-a-data-object) - [ Nesting ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/nesting) - [ Collections ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/collections) - [ Abstract Data ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/abstract-data) - [ Casts ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/casts) - [ Optional properties ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/optional-properties) - [ Mapping property names ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/mapping-property-names) - [ Default values ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/defaults) - [ Computed values ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/computed) - [ From a request ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/request-to-data-object) - [ From a model ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/model-to-data-object) - [ Injecting property values ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/injecting-property-values) - [ Factories ](https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/factories) Validation ---------- - [ Introduction ](https://spatie.be/docs/laravel-data/v4/validation/introduction) - [ Auto rule inferring ](https://spatie.be/docs/laravel-data/v4/validation/auto-rule-inferring) - [ Using validation attributes ](https://spatie.be/docs/laravel-data/v4/validation/using-validation-attributes) - [ Manual rules ](https://spatie.be/docs/laravel-data/v4/validation/manual-rules) - [ Working with the validator ](https://spatie.be/docs/laravel-data/v4/validation/working-with-the-validator) - [ Nesting Data ](https://spatie.be/docs/laravel-data/v4/validation/nesting-data) - [ Skipping validation ](https://spatie.be/docs/laravel-data/v4/validation/skipping-validation) As a resource ------------- - [ From data to array ](https://spatie.be/docs/laravel-data/v4/as-a-resource/from-data-to-array) - [ From data to resource ](https://spatie.be/docs/laravel-data/v4/as-a-resource/from-data-to-resource) - [ Mapping property names ](https://spatie.be/docs/laravel-data/v4/as-a-resource/mapping-property-names) - [ Appending properties ](https://spatie.be/docs/laravel-data/v4/as-a-resource/appending-properties) - [ Wrapping ](https://spatie.be/docs/laravel-data/v4/as-a-resource/wrapping) - [ Including and excluding properties ](https://spatie.be/docs/laravel-data/v4/as-a-resource/lazy-properties) - [ Transforming data ](https://spatie.be/docs/laravel-data/v4/as-a-resource/transformers) Advanced usage -------------- - [ Eloquent casting ](https://spatie.be/docs/laravel-data/v4/advanced-usage/eloquent-casting) - [ Transforming to TypeScript ](https://spatie.be/docs/laravel-data/v4/advanced-usage/typescript) - [ Working with dates ](https://spatie.be/docs/laravel-data/v4/advanced-usage/working-with-dates) - [ Normalizers ](https://spatie.be/docs/laravel-data/v4/advanced-usage/normalizers) - [ Pipeline ](https://spatie.be/docs/laravel-data/v4/advanced-usage/pipeline) - [ Creating a cast ](https://spatie.be/docs/laravel-data/v4/advanced-usage/creating-a-cast) - [ Creating a transformer ](https://spatie.be/docs/laravel-data/v4/advanced-usage/creating-a-transformer) - [ Creating a rule inferrer ](https://spatie.be/docs/laravel-data/v4/advanced-usage/creating-a-rule-inferrer) - [ Use with Inertia ](https://spatie.be/docs/laravel-data/v4/advanced-usage/use-with-inertia) - [ Use with Livewire ](https://spatie.be/docs/laravel-data/v4/advanced-usage/use-with-livewire) - [ Internal structures ](https://spatie.be/docs/laravel-data/v4/advanced-usage/internal-structures) - [ Mapping rules ](https://spatie.be/docs/laravel-data/v4/advanced-usage/mapping-rules) - [ Validation attributes ](https://spatie.be/docs/laravel-data/v4/advanced-usage/validation-attributes) - [ Get data from a class quickly ](https://spatie.be/docs/laravel-data/v4/advanced-usage/get-data-from-a-class-quickly) - [ Performance ](https://spatie.be/docs/laravel-data/v4/advanced-usage/performance) - [ Commands ](https://spatie.be/docs/laravel-data/v4/advanced-usage/commands) - [ Traits and interfaces ](https://spatie.be/docs/laravel-data/v4/advanced-usage/traits-and-interfaces) - [ In Packages ](https://spatie.be/docs/laravel-data/v4/advanced-usage/in-packages) - [ Available property mappers ](https://spatie.be/docs/laravel-data/v4/advanced-usage/available-property-mappers) From data to resource ===================== ### On this page 1. [ Transforming empty objects ](#content-transforming-empty-objects) 2. [ Response status code ](#content-response-status-code) 3. [ Resource classes ](#content-resource-classes) A data object will automatically be transformed to a JSON response when returned in a controller: ``` class SongController { public function show(Song $model) { return SongData::from($model); } } ``` The JSON then will look like this: ``` { "name": "Never gonna give you up", "artist": "Rick Astley" } ``` ### Collections Returning a data collection from the controller like this: ``` SongData::collect(Song::all()); ``` Will return a collection automatically transformed to JSON: ``` [ { "name": "Never Gonna Give You Up", "artist": "Rick Astley" }, { "name": "Giving Up on Love", "artist": "Rick Astley" } ] ``` ### Paginators It is also possible to provide a paginator: ``` SongData::collect(Song::paginate()); ``` The data object is smart enough to create a paginated response from this with links to the next, previous, last, ... pages: ``` { "data" : [ { "name" : "Never Gonna Give You Up", "artist" : "Rick Astley" }, { "name" : "Giving Up on Love", "artist" : "Rick Astley" } ], "meta" : { "current_page": 1, "first_page_url": "https://spatie.be/?page=1", "from": 1, "last_page": 7, "last_page_url": "https://spatie.be/?page=7", "next_page_url": "https://spatie.be/?page=2", "path": "https://spatie.be/", "per_page": 15, "prev_page_url": null, "to": 15, "total": 100 } } ``` Transforming empty objects -------------------------------------------------------------------------------------------------------------------------------------- When creating a new model, you probably want to provide a blueprint to the frontend with the required data to create a model. For example: ``` { "name": null, "artist": null } ``` You could make each property of the data object nullable like this: ``` class SongData extends Data { public function __construct( public ?string $title, public ?string $artist, ) { } // ... } ``` This approach would work, but as soon as the model is created, the properties won't be `null`, which doesn't follow our data model. So it is considered a bad practice. That's why in such cases, you can return an empty representation of the data object: ``` class SongsController { public function create(): array { return SongData::empty(); } } ``` Which will output the following JSON: ``` { "name": null, "artist": null } ``` The `empty` method on a data object will return an array with default empty values for the properties in the data object. It is possible to change the default values within this array by providing them in the constructor of the data object: ``` class SongData extends Data { public function __construct( public string $title = 'Title of the song here', public string $artist = "An artist", ) { } // ... } ``` Now when we call `empty`, our JSON looks like this: ``` { "name": "Title of the song here", "artist": "An artist" } ``` You can also pass defaults within the `empty` call: ``` SongData::empty([ 'name' => 'Title of the song here', 'artist' => 'An artist' ]); ``` Or filter the properties that should be included in the empty response: ``` SongData::empty(only: ['name']); // Will only return the `name` property SongData::empty(except: ['name']); // Will return the `artist` property ``` Response status code -------------------------------------------------------------------------------------------------------------------- When a resource is being returned from a controller, the status code of the response will automatically be set to `201 CREATED` when Laravel data detects that the request's method is `POST`. In all other cases, `200 OK` will be returned. Resource classes -------------------------------------------------------------------------------------------------------- To make it a bit more clear that a data object is a resource, you can use the `Resource` class instead of the `Data` class: ``` use Spatie\LaravelData\Resource; class SongResource extends Resource { public function __construct( public string $title, public string $artist, ) { } } ``` These resource classes have as an advantage that they won't validate data or check authorization, They are only used to transform data which makes them a bit faster.