Wrapping | laravel-data | Spatie SPATIE Laravel Data =============== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-data](https://spatie.be/docs/laravel-data/v3) 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) - [ Introduction ](https://spatie.be/docs/laravel-data/v3/introduction) - [ Support us ](https://spatie.be/docs/laravel-data/v3/support-us) - [ Requirements ](https://spatie.be/docs/laravel-data/v3/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-data/v3/installation-setup) - [ Third party packages ](https://spatie.be/docs/laravel-data/v3/third-party-packages) - [ Questions and issues ](https://spatie.be/docs/laravel-data/v3/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-data/v3/changelog) - [ About us ](https://spatie.be/docs/laravel-data/v3/about-us) Getting started --------------- - [ Quickstart ](https://spatie.be/docs/laravel-data/v3/getting-started/quickstart) As a DTO -------- - [ Creating a data object ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/creating-a-data-object) - [ Optional properties ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/optional-properties) - [ Nesting ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/nesting) - [ Collections ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/collections) - [ Casts ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/casts) - [ Default values ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/defaults) - [ Computed values ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/computed) - [ From a request ](https://spatie.be/docs/laravel-data/v3/as-a-data-transfer-object/request-to-data-object) As a resource ------------- - [ From data to resource ](https://spatie.be/docs/laravel-data/v3/as-a-resource/from-data-to-resource) - [ Including and excluding properties ](https://spatie.be/docs/laravel-data/v3/as-a-resource/lazy-properties) - [ Wrapping ](https://spatie.be/docs/laravel-data/v3/as-a-resource/wrapping) - [ Transforming data ](https://spatie.be/docs/laravel-data/v3/as-a-resource/transformers) Advanced usage -------------- - [ Eloquent casting ](https://spatie.be/docs/laravel-data/v3/advanced-usage/eloquent-casting) - [ Transforming to TypeScript ](https://spatie.be/docs/laravel-data/v3/advanced-usage/typescript) - [ Working with dates ](https://spatie.be/docs/laravel-data/v3/advanced-usage/working-with-dates) - [ Normalizers ](https://spatie.be/docs/laravel-data/v3/advanced-usage/normalizers) - [ Pipeline ](https://spatie.be/docs/laravel-data/v3/advanced-usage/pipeline) - [ Use with Inertia ](https://spatie.be/docs/laravel-data/v3/advanced-usage/use-with-inertia) - [ Use with Livewire ](https://spatie.be/docs/laravel-data/v3/advanced-usage/use-with-livewire) - [ Creating a cast ](https://spatie.be/docs/laravel-data/v3/advanced-usage/creating-a-cast) - [ Creating a transformer ](https://spatie.be/docs/laravel-data/v3/advanced-usage/creating-a-transformer) - [ Filling properties from route parameters ](https://spatie.be/docs/laravel-data/v3/advanced-usage/filling%20from-route-parameters) - [ Creating a rule inferrer ](https://spatie.be/docs/laravel-data/v3/advanced-usage/creating-a-rule-inferrer) - [ Internal structures ](https://spatie.be/docs/laravel-data/v3/advanced-usage/internal-structures) - [ Custom collections ](https://spatie.be/docs/laravel-data/v3/advanced-usage/custom-collections) - [ Mapping rules ](https://spatie.be/docs/laravel-data/v3/advanced-usage/mapping-rules) - [ Validation attributes ](https://spatie.be/docs/laravel-data/v3/advanced-usage/validation-attributes) - [ Performance ](https://spatie.be/docs/laravel-data/v3/advanced-usage/performance) - [ Commands ](https://spatie.be/docs/laravel-data/v3/advanced-usage/commands) You are viewing the documentation for **an older version** of this package. You can check the version you are using with the following command: ` composer show spatie/laravel-data ` 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::collection(Song::all())->wrap('data'); ``` 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::collection(Song::paginate())->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: ``` use Spatie\LaravelData\Attributes\DataCollectionOf; 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::collection($album->songs)->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); ```