Casts | laravel-data | Spatie SPATIE Laravel Data =============== spatie.be/open-source [Docs](https://spatie.be/docs) [Laravel-data](https://spatie.be/docs/laravel-data/v2) 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/v2/introduction) - [ Support us ](https://spatie.be/docs/laravel-data/v2/support-us) - [ Requirements ](https://spatie.be/docs/laravel-data/v2/requirements) - [ Installation & setup ](https://spatie.be/docs/laravel-data/v2/installation-setup) - [ Questions and issues ](https://spatie.be/docs/laravel-data/v2/questions-issues) - [ Changelog ](https://spatie.be/docs/laravel-data/v2/changelog) - [ About us ](https://spatie.be/docs/laravel-data/v2/about-us) Getting started --------------- - [ Quickstart ](https://spatie.be/docs/laravel-data/v2/getting-started/quickstart) As a DTO -------- - [ Creating a data object ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/creating-a-data-object) - [ Optional properties ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/optional-properties) - [ Nesting ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/nesting) - [ Collections ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/collections) - [ Casts ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/casts) - [ From a request ](https://spatie.be/docs/laravel-data/v2/as-a-data-transfer-object/request-to-data-object) As a resource ------------- - [ From data to resource ](https://spatie.be/docs/laravel-data/v2/as-a-resource/from-data-to-resource) - [ Including and excluding properties ](https://spatie.be/docs/laravel-data/v2/as-a-resource/lazy-properties) - [ Wrapping ](https://spatie.be/docs/laravel-data/v2/as-a-resource/wrapping) - [ Transforming data ](https://spatie.be/docs/laravel-data/v2/as-a-resource/transformers) Advanced usage -------------- - [ Eloquent casting ](https://spatie.be/docs/laravel-data/v2/advanced-usage/eloquent-casting) - [ Transforming to TypeScript ](https://spatie.be/docs/laravel-data/v2/advanced-usage/typescript) - [ Working with dates ](https://spatie.be/docs/laravel-data/v2/advanced-usage/working-with-dates) - [ Normalizers ](https://spatie.be/docs/laravel-data/v2/advanced-usage/normalizers) - [ Pipeline ](https://spatie.be/docs/laravel-data/v2/advanced-usage/pipeline) - [ Use with Inertia ](https://spatie.be/docs/laravel-data/v2/advanced-usage/use-with-inertia) - [ Use with Livewire ](https://spatie.be/docs/laravel-data/v2/advanced-usage/use-with-livewire) - [ Creating a cast ](https://spatie.be/docs/laravel-data/v2/advanced-usage/creating-a-cast) - [ Creating a transformer ](https://spatie.be/docs/laravel-data/v2/advanced-usage/creating-a-transformer) - [ Creating a rule inferrer ](https://spatie.be/docs/laravel-data/v2/advanced-usage/creating-a-rule-inferrer) - [ Internal structures ](https://spatie.be/docs/laravel-data/v2/advanced-usage/internal-structures) - [ Validation attributes ](https://spatie.be/docs/laravel-data/v2/advanced-usage/validation-attributes) 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 ` 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) 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` from our [enum package](https://github.com/spatie/enum) and looks like this: ``` /** * @method static self cd() * @method static self vinyl() * @method static self cassette() */ class Format extends Enum{ } ``` 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(string, int's, 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, class: 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, ) { } } ``` Creating your own casts ----------------------------------------------------------------------------------------------------------------------------- It is possible to create your casts. You can read more about this in the [advanced chapter](/docs/laravel-data/v2/advanced-usage/creating-a-cast).