Transforming data | 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 Transforming data 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 ` Transforming data ================= ### On this page 1. [ Local transformers ](#content-local-transformers) 2. [ Global transformers ](#content-global-transformers) 3. [ Getting a data object without transforming ](#content-getting-a-data-object-without-transforming) 4. [ Getting a data object (on steroids) ](#content-getting-a-data-object-on-steroids) Each property of a data object should be transformed into a usable type to communicate via JSON. No complex transformations are required for the default types (string, bool, int, float, enum and array), but special types like `Carbon` or a Laravel Model will need extra attention. Transformers are simple classes that will convert a complex type to something simple like a `string` or `int`. For example, we can transform a `Carbon` object to `16-05-1994`, `16-05-1994T00:00:00+00` or something completely different. There are two ways you can define transformers: locally and globally. Local transformers -------------------------------------------------------------------------------------------------------------- When you want to transform a specific property, you can use an attribute with the transformer you want to use: ``` class ArtistData extends Data{ public function __construct( public string $name, #[WithTransformer(DateTimeInterfaceTransformer::class)] public Carbon $birth_date ) { } } ``` The `DateTimeInterfaceTransformer` is shipped with the package and will transform objects of type `Carbon`, `CarbonImmutable`, `DateTime` and `DateTimeImmutable` to a string. The format used for converting the date to string can be set in the `data.php` config file. It is also possible to manually define a format: ``` class ArtistData extends Data{ public function __construct( public string $name, #[WithTransformer(DateTimeInterfaceTransformer::class, format: 'm-Y')] public Carbon $birth_date ) { } } ``` Next to a `DateTimeInterfaceTransformer` the package also ships with an `ArrayableTransformer` that transforms an `Arrayable` object to an array. It is possible to create transformers for your specific types. You can find more info [here](/docs/laravel-data/v3/advanced-usage/creating-a-transformer). Global transformers ----------------------------------------------------------------------------------------------------------------- Global transformers are defined in the `data.php` config file and are used when no local transformer for a property was added. By default, there are two transformers: ``` use Illuminate\Contracts\Support\Arrayable; use Spatie\LaravelData\Transformers\ArrayableTransformer; use Spatie\LaravelData\Transformers\DateTimeInterfaceTransformer; /* * Global transformers will take complex types and transform them into simple * types. */ 'transformers' => [ DateTimeInterface::class => DateTimeInterfaceTransformer::class, Arrayable::class => ArrayableTransformer::class, ], ``` The package will look through these global transformers and tries to find a suitable transformer. You can define transformers for: - a **specific implementation** (e.g. CarbonImmutable) - an **interface** (e.g. DateTimeInterface) - a **base class** (e.g. Enum) Getting a data object without transforming -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- It is possible to get an array representation of a data object without transforming the properties. This means `Carbon` objects won't be transformed into strings. And also, nested data objects and `DataCollection`s won't be transformed into arrays. You can do this by calling the `all` method on a data object like this: ``` ArtistData::from($artist)->all(); ``` Getting a data object (on steroids) ------------------------------------------------------------------------------------------------------------------------------------------------------------- Internally the package uses the `transform` method for operations like `toArray`, `all`, `toJson` and so on. This method is highly configurable: ``` ArtistData::from($artist)->transform( bool $transformValues = true, WrapExecutionType $wrapExecutionType = WrapExecutionType::Disabled, bool $mapPropertyNames = true, ); ``` - **$transformValues** when enabled transformers will be used to transform properties, also data objects and collections will be transformed - **$wrapExecutionType** allows you to set if wrapping is `Enabled` or `Disabled` - **$mapPropertyNames** uses defined mappers to rename properties when enabled