Casts | 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-data-transfer-object Casts 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) Casts ===== ### On this page 1. [ Local casts ](#content-local-casts) 2. [ Global casts ](#content-global-casts) 3. [ Creating your own casts ](#content-creating-your-own-casts) 4. [ Casting arrays or collections of non-data types ](#content-casting-arrays-or-collections-of-non-data-types) We extend our example data object just a little bit: ``` class SongData extends Data { public function __construct( public string $title, public string $artist, public DateTime $date, public Format $format, ) { } } ``` The `Format` property here is an `Enum` and looks like this: ``` enum Format: string { case cd = 'cd'; case vinyl = 'vinyl'; case cassette = 'cassette'; } ``` When we now try to construct a data object like this: ``` SongData::from([ 'title' => 'Never gonna give you up', 'artist' => 'Rick Astley', 'date' => '27-07-1987', 'format' => 'vinyl', ]); ``` And get an error because the first two properties are simple PHP types(strings, ints, floats, booleans, arrays), but the following two properties are more complex types: `DateTime` and `Enum`, respectively. These types cannot be automatically created. A cast is needed to construct them from a string. There are two types of casts, local and global casts. Local casts ----------------------------------------------------------------------------------------- Local casts are defined within the data object itself and can be added using attributes: ``` class SongData extends Data { public function __construct( public string $title, public string $artist, #[WithCast(DateTimeInterfaceCast::class)] public DateTime $date, #[WithCast(EnumCast::class)] public Format $format, ) { } } ``` Now it is possible to create a data object like this without exceptions: ``` SongData::from([ 'title' => 'Never gonna give you up', 'artist' => 'Rick Astley', 'date' => '27-07-1987', 'format' => 'vinyl', ]); ``` It is possible to provide parameters to the casts like this: ``` #[WithCast(EnumCast::class, type: Format::class)] public Format $format ``` Global casts -------------------------------------------------------------------------------------------- Global casts are not defined on the data object but in your `data.php` config file: ``` 'casts' => [ DateTimeInterface::class => Spatie\LaravelData\Casts\DateTimeInterfaceCast::class, ], ``` When the data object can find no local cast for the property, the package will look through the global casts and tries to find a suitable cast. You can define casts for: - a **specific implementation** (e.g. CarbonImmutable) - an **interface** (e.g. DateTimeInterface) - a **base class** (e.g. Enum) As you can see, the package by default already provides a `DateTimeInterface` cast, this means we can update our data object like this: ``` class SongData extends Data { public function __construct( public string $title, public string $artist, public DateTime $date, #[WithCast(EnumCast::class)] public Format $format, ) { } } ``` Tip: we can also remove the `EnumCast` since the package will automatically cast enums because they're a native PHP type, but this made the example easy to understand. Creating your own casts ----------------------------------------------------------------------------------------------------------------------------- It is possible to create your casts. You can read more about this in the [advanced chapter](/docs/laravel-data/v4/advanced-usage/creating-a-cast). Casting arrays or collections of non-data types ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We've already seen how collections of data can be made of data objects, the same is true for all other types if correctly typed. Let say we have an array of DateTime objects: ``` class ReleaseData extends Data { public string $title; /** @var array */ public array $releaseDates; } ``` By enabling the `cast_and_transform_iterables` feature in the `data` config file (this feature will be enabled by default in laravel-data v5): ``` 'features' => [ 'cast_and_transform_iterables' => true, ], ``` We now can create a `ReleaseData` object with an array of strings which will be cast into an array DateTime objects: ``` ReleaseData::from([ 'title' => 'Never Gonna Give You Up', 'releaseDates' => [ '1987-07-27T12:00:00Z', '1987-07-28T12:00:00Z', '1987-07-29T12:00:00Z', ], ]); ``` For this feature to work, a cast should not only implement the `Cast` interface but also the `IterableItemCast`. The signatures of the `cast` and `castIterableItem` methods are exactly the same, but they're called on different times. When casting a property like a DateTime from a string, the `cast` method will be used, when transforming an iterable property like an array or Laravel Collection where the iterable item is typed using an annotation, then each item of the provided iterable will trigger a call to the `castIterableItem` method.