Wrapping | 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 Wrapping 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) Wrapping - [ 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) Wrapping ======== ### On this page 1. [ Wrapping collections ](#content-wrapping-collections) 2. [ Nested wrapping ](#content-nested-wrapping) 3. [ Disabling wrapping ](#content-disabling-wrapping) 4. [ Getting a wrapped array ](#content-getting-a-wrapped-array) By default, when a data object is transformed into JSON in your controller, it looks like this: ``` { "name" : "Never gonna give you up", "artist" : "Rick Astley" } ``` It is possible to wrap a data object: ``` SongData::from(Song::first())->wrap('data'); ``` Now the JSON looks like this: ``` { "data" : { "name" : "Never gonna give you up", "artist" : "Rick Astley" } } ``` Data objects and collections will only get wrapped when you're sending them as a response and never when calling `toArray` or `toJson` on it. It is possible to define a default wrap key inside a data object: ``` class SongData extends Data { public function defaultWrap(): string { return 'data'; } // ... } ``` Or you can set a global wrap key inside the `data.php` config file: ``` /* * Data objects can be wrapped into a key like 'data' when used as a resource, * this key can be set globally here for all data objects. You can pass in * `null` if you want to disable wrapping. */ 'wrap' => 'data', ``` Wrapping collections -------------------------------------------------------------------------------------------------------------------- Collections can be wrapped just like data objects: ``` SongData::collect(Song::all(), DataCollection::class)->wrap('data'); ``` Notice here, for now we only support wrapping `DataCollections`, `PaginatedDataCollections` and `CursorPaginatedDataCollections` on the root level. Wrapping won't work for Laravel Collections or arrays (for now) since the package cannot interfere. Nested properties with such types can be wrapped though (see further). The JSON will now look like this: ``` { "data" : [ { "name" : "Never Gonna Give You Up", "artist" : "Rick Astley" }, { "name" : "Giving Up on Love", "artist" : "Rick Astley" } ] } ``` It is possible to set the data key in paginated collections: ``` SongData::collect(Song::paginate(), PaginatedDataCollection::class)->wrap('paginated_data'); ``` Which will let the JSON look like this: ``` { "paginated_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 } } ``` Nested wrapping ----------------------------------------------------------------------------------------------------- A data object included inside another data object will never be wrapped even if a wrap is set: ``` class UserData extends Data { public function __construct( public string $title, public string $email, public SongData $favorite_song, ) { } public static function fromModel(User $user): self { return new self( $user->title, $user->email, SongData::create($user->favorite_song)->wrap('data') ); } } UserData::from(User::first())->wrap('data'); ``` ``` { "data" : { "name" : "Ruben", "email" : "ruben@spatie.be", "favorite_song" : { "name" : "Never Gonna Give You Up", "artist" : "Rick Astley" } } } ``` A data collection inside a data object will get wrapped when a wrapping key is set (in order to mimic Laravel resources): ``` use Spatie\LaravelData\Attributes\DataCollectionOf; use Spatie\LaravelData\DataCollection; class AlbumData extends Data { public function __construct( public string $title, #[DataCollectionOf(SongData::class)] public DataCollection $songs, ) { } public static function fromModel(Album $album): self { return new self( $album->title, SongData::collect($album->songs, DataCollection::class)->wrap('data') ); } } AlbumData::from(Album::first())->wrap('data'); ``` The JSON will look like this: ``` { "data" : { "title" : "Whenever You Need Somebody", "songs": { "data" : [ { "name" : "Never Gonna Give You Up", "artist" : "Rick Astley" }, { "name" : "Giving Up on Love", "artist" : "Rick Astley" } ] } } } ``` Disabling wrapping -------------------------------------------------------------------------------------------------------------- Whenever a data object is wrapped due to the default wrap method or a global wrap key, it is possible to disable wrapping on a data object/collection: ``` SongData::from(Song::first())->withoutWrapping(); ``` Getting a wrapped array ----------------------------------------------------------------------------------------------------------------------------- By default, `toArray` and `toJson` will never wrap a data object or collection, but it is possible to get a wrapped array: ``` SongData::from(Song::first())->wrap('data')->transform(wrapExecutionType: WrapExecutionType::Enabled); ``` A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)