Laravel Data

https://github.com/spatie/laravel-data
Admin
Laravel Data provides powerful data objects for Laravel, enabling automatic data transformation,...
Tokens:110,474
Snippets:1,041
Trust Score:-
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example JSON blueprint for creating a model

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/from-data-to-resource.md

A JSON example showing the expected structure for creating a new model with null values.

```json
{
    "name": null,
    "artist": null
}
```

--------------------------------

### Context usage examples

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Shows how context is available on all scopes.

```php
new RequestScope('store')   // key='request', context='store'
new ResourceScope('admin')  // key='resource', context='admin'
new EloquentScope()         // key='eloquent', context=null
new Scope('stripe')         // key='stripe', context=null
new Scope('stripe', 'webhook')  // key='stripe', context='webhook'
```

--------------------------------

### Install laravel-data via Composer

Source: https://github.com/spatie/laravel-data/blob/main/README.md

Command to install the package using Composer. Run this in your Laravel project root.

```bash
composer require spatie/laravel-data
```

--------------------------------

### Install laravel-typescript-transformer package

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/typescript.md

Composer command to install the spatie/laravel-typescript-transformer package, required for transforming data objects to TypeScript.

```bash
composer require spatie/laravel-typescript-transformer
```

--------------------------------

### Get first item from DataCollection

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Shows how to get the first item from a DataCollection using the `first` method.

```php
SongData::collect(Song::all(), DataCollection::class)->first(); // SongData object
```

--------------------------------

### Inheritance-based matching example

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Shows how a mapping for ApiScope matches RequestScope and ResourceScope via scopeKeyHierarchy.

```php
#[MapName(SnakeCaseMapper::class, scope: ApiScope::class)]     // matches api, request, resource
#[MapInputName('special', scope: RequestScope::class)]          // only matches request (more specific)
```

--------------------------------

### Example payload for nested data

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/manual-rules.md

Provides an example payload that would be passed to the AlbumData object to demonstrate the relative payload behavior.

```php
[
    'title' => 'Best songs ever made',
    'songs' => [
        ['title' => 'Never Gonna Give You Up'],
        ['title' => 'Heroes', 'artist' => 'David Bowie'],
    ],
];
```

--------------------------------

### Mimes attribute examples

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Shows three ways to specify allowed file extensions: a single string, an array, or multiple arguments.

```php
#[Mimes('jpg')]
public UploadedFile $closure; 
```

```php
#[Mimes(['jpg', 'png'])]
public UploadedFile $closure; 
```

```php
#[Mimes('jpg', 'png')]
public UploadedFile $closure; 
```

--------------------------------

### MimeTypes attribute examples

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Shows three ways to specify allowed MIME types: a single string, an array, or multiple arguments.

```php
#[MimeTypes('video/quicktime')]
public UploadedFile $closure; 
```

```php
#[MimeTypes(['video/quicktime', 'video/avi'])]
public UploadedFile $closure; 
```

```php
#[MimeTypes('video/quicktime', 'video/avi')]
public UploadedFile $closure; 
```

--------------------------------

### Eloquent Song model example

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Shows a minimal Eloquent model class that can be used to create a data object from.

```php
class Song extends Model
{
    // Your model code
}
```

--------------------------------

### One-time include example

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Shows that calling include('songs') affects only that instance, so the second call without include does not include songs.

```php
AlbumData::from(Album::first())->include('songs')->toArray(); // will include songs
AlbumData::from(Album::first())->toArray(); // will not include songs
```

--------------------------------

### Get data object from a Model using getData

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/get-data-from-a-class-quickly.md

Call getData() on a model instance to quickly obtain a data object. The example shows retrieving a Song model and getting its data object.

```php
Song::firstOrFail($id)->getData(); // A SongData object
```

--------------------------------

### Livewire component using Synths with Blade view

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-livewire.md

Example component using a data object without Wireable, including a Blade view with wire:model bindings.

```php
class SongUpdateComponent extends Component
{
    public SongData $data;

    public function mount(public int $id): void
    {
        $this->data = SongData::from(Song::findOrFail($id));
    }

    public function save(): void
    {
        Artist::findOrFail($this->id)->update($this->data->toArray());
    }

    public function render(): string
    {
        return <<<'BLADE'
        <div>
            <h1>Songs</h1>
            <input type="text" wire:model.live="data.title">
            <input type="text" wire:model.live="data.artist">
            <p>Title: {{ $data->title }}</p>
            <p>Artist: {{ $data->artist }}</p>
            <button wire:click="save">Save</button>
        </div>
        BLADE;
    }
}
```

--------------------------------

### Image class example

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

A simple Image class with a constructor accepting file and size properties, used as the target type for a custom local cast.

```php
class Image
{
    public function __construct(
        public string $file,
        public int $size,
    ) {
    }
}
```

--------------------------------

### Controller returning PostData

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Example controller that creates a PostData instance from an array and returns it, which will be transformed to JSON.

```php
public function __invoke()
{
    return PostData::from([
        'title' => 'Hello laravel-data',
        'content' => 'This is an introduction post for the new package',
        'status' => PostStatus::published,
        'image' => [
            'filename' => 'images/8JQtgd0XaPtt9CqkPJ3eWFVV4BAp6JR9ltYAIKqX.png',
            'size' => 16524
        ],
        'published_at' => CarbonImmutable::create(2020, 05, 16),
    ]);
}
```

--------------------------------

### Eloquent cast integration in get()

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Create a factory with EloquentScope and call from() with the payload.

```php
return ($this->dataClass)::factory()
    ->withScope(new EloquentScope())
    ->from($payload);
```

--------------------------------

### Example JSON payload for PostData

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

A sample JSON payload sent to the controller, demonstrating the input data structure with title, content, status, and published_at fields.

```json
{
    "title" : "Hello laravel-data",
    "content" : "This is an introduction post for the new package",
    "status" : "published",
    "published_at" : "2021-09-24T13:31:20+00:00"
}
```

--------------------------------

### Prepare data for pipeline with prepareForPipeline

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/pipeline.md

Use prepareForPipeline to modify the normalized payload before it enters the pipeline. The example shows extracting nested fields into a metadata array using Arr::only.

```php
class SongMetadata
{
    public function __construct(
        public string $releaseYear,
        public string $producer,
    ) {}
}

class SongData extends Data
{
    public function __construct(
        public string $title,
        public SongMetadata $metadata,
    ) {}
    
    public static function prepareForPipeline(array $properties): array
    {
        $properties['metadata'] = Arr::only($properties, ['release_year', 'producer']);
        
        return $properties;
    }
}
```

--------------------------------

### Basic SongData class with constructor

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Defines a simple data object with a constructor using PHP 8.0 promoted properties. This is the starting point for creating data objects.

```php
class SongData extends Data
{
    public function __construct(
        public string $title,
        public string $artist,
    ) {
    }
}
```

--------------------------------

### PostData with WithCast attribute

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Example PostData class using the WithCast attribute to apply the ImageCast to the image property, and the Date attribute to the published_at property.

```php
class PostData extends Data
{
    public function __construct(
        public string $title,
        public string $content,
        public PostStatus $status,
        #[WithCast(ImageCast::class)]
        public ?Image $image,
        #[Date]
        public ?CarbonImmutable $published_at
    ) {
    }
}
```

--------------------------------

### Update config data.php with scoped name mapping strategy

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Add a 'scoped' key to 'name_mapping_strategy' with commented-out Eloquent mapper example.

```php
'name_mapping_strategy' => [
    'input' => null,
    'output' => null,
    'scoped' => [
        // 'eloquent' => [
        //     'input' => \Spatie\LaravelData\Mappers\SnakeCaseMapper::class,
        //     'output' => \Spatie\LaravelData\Mappers\SnakeCaseMapper::class,
        // ],
    ],
],
```

--------------------------------

### Large JSON payload with authors and posts

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Example JSON showing a large payload with authors and their posts, illustrating the problem lazy properties solve.

```json
[
    {
        "name" : "Ruben Van Assche",
        "posts" : [
            {
                "title" : "Hello laravel-data",
                "content" : "This is an introduction post for the new package",
                "status" : "published",
                "image" : "http://laravel-playbox.test/images/8JQtgd0XaPtt9CqkPJ3eWFVV4BAp6JR9ltYAIKqX.png",
                "published_at" : "2021-09-24T13:31:20+00:00"
            }

            // ...
        ]
    },
    {
        "name" : "Freek van der Herten",
        "posts" : [
            {
                "title" : "Hello laravel-event-sourcing",
                "content" : "This is an introduction post for the new package",
                "status" : "published",
                "image" : "http://laravel-playbox.test/images/8JQtgd0XaPtt9CqkPJ3eWFVV4BAp6JR9ltYAIKqX.png"
                "published_at" : "2021-09-24T13:31:20+00:00"
            }

            // ...
        ]
    }

    // ...
]
```

--------------------------------

### Global casts configuration in data.php

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/casts.md

Example of defining a global cast in the data.php config file, mapping DateTimeInterface to the DateTimeInterfaceCast class.

```php
'casts' => [
    DateTimeInterface::class => Spatie\LaravelData\Casts\DateTimeInterfaceCast::class,
],
```

--------------------------------

### JSON output after including title

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Example JSON output resulting from including the 'title' property of posts.

```json
{
    "name" : "Ruben Van Assche",
    "posts" : [
        {
            "title" : "Hello laravel-data"
        }
    ]
}
```

--------------------------------

### NotIn attribute examples

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Shows two ways to specify disallowed values: an array or multiple arguments.

```php
#[NotIn([1, 2, 3, 'a', 'b'])]
public mixed $closure; 
```

```php
#[NotIn(1, 2, 3, 'a', 'b')]
public mixed $closure; 
```

--------------------------------

### Data class implementing Wireable with WireableData trait

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-livewire.md

Required setup for using data classes with Livewire: implement Wireable and use the WireableData trait.

```php
class SongData extends Data implements Wireable
{
    use WireableData;

    public function __construct(
        public string $title,
        public string $artist,
    ) {
    }
}
```

--------------------------------

### Create a data object with named arguments

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/mapping-property-names.md

Instantiate a ContractData object using named arguments. This example shows the constructor call with 'name' and 'recordCompany'.

```php
$contract = new ContractData(
    name: 'Rick Astley',
    recordCompany: 'RCA Records',
);
```

--------------------------------

### Conditional permanent include/exclude/only/except

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Shows how to set the permanent flag on conditional methods. Note the onlyWhen example has a misplaced parenthesis in the source.

```php
AlbumData::from(Album::first())->includeWhen('songs', fn(AlbumData $data) => count($data->songs) > 0, permanent: true);
AlbumData::from(Album::first())->excludeWhen('songs', fn(AlbumData $data) => count($data->songs) > 0, permanent: true);
AlbumData::from(Album::first())->onlyWhen('songs', fn(AlbumData $data) => count($data->songs) > 0), permanent: true);
AlbumData::from(Album::first())->except('songs', fn(AlbumData $data) => count($data->songs) > 0, permanent: true);
```

--------------------------------

### Create individual instances of Singer and Musician

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/abstract-data.md

Demonstrates how to instantiate the subclasses directly using the from method with an array of properties.

```php
Singer::from(['name' => 'Rick Astley', 'voice' => 'tenor']);
Musician::from(['name' => 'Rick Astley', 'instrument' => 'guitar']);
```

--------------------------------

### Route definition for my-account

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Defines a route that returns a UserData object from the first user. Used as the base for the query string examples.

```php
// in web.php

Route::get('my-account', fn() => UserData::from(User::first()));
```

--------------------------------

### Instantiate SongData with constructor

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Creates a new SongData instance using the constructor with positional arguments.

```php
new SongData('Never gonna give you up', 'Rick Astley');
```

--------------------------------

### Enable Livewire Synths in config

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-livewire.md

Configuration option in data.php to enable experimental Livewire Synths, allowing data objects without Wireable.

```php
'livewire' => [
    'enable_synths' => false,
]
```

--------------------------------

### Run the package test suite

Source: https://github.com/spatie/laravel-data/blob/main/README.md

Command to execute the package's test suite using Composer.

```bash
composer test
```

--------------------------------

### Example data object with various property types

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/typescript.md

A PHP data object demonstrating nullable, scalar, array, lazy, optional, and collection properties. This is the input for the TypeScript transformation example.

```php
class DataObject extends Data
{
    public function __construct(
        public null|int $nullable,
        public int $int,
        public bool $bool,
        public string $string,
        public float $float,
        /** @var string[] */
        public array $array,
        public Lazy|string $lazy,
        public Optional|string $optional,
        public SimpleData $simpleData,
        /** @var \Spatie\LaravelData\Tests\Fakes\SimpleData[] */
        public DataCollection $dataCollection,
    )
    {
    }
}
```

```tsx
{
    nullable: number | null;
    int: number;
    bool: boolean;
    string: string;
    float: number;
    array: Array<string>;
    lazy? : string;
    optional? : string;
    simpleData: SimpleData;
    dataCollection: Array<SimpleData>;
}
```

--------------------------------

### Create data object with and without provided values

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/defaults.md

Shows how to instantiate the data object with no arguments or with an array of values. The default values are used when not provided.

```php
SongData::from();
SongData::from(['title' => 'Giving Up On Love', 'date' => CarbonImmutable::create(1988, 4, 15)]);
```

--------------------------------

### Get wrapped array with wrap() and WrapExecutionType::Enabled

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/wrapping.md

Use `wrap('data')` and `transform(wrapExecutionType: WrapExecutionType::Enabled)` to get a wrapped array, overriding the default behavior of `toArray` and `toJson` which never wrap.

```php
SongData::from(Song::first())->wrap('data')->transform(wrapExecutionType: WrapExecutionType::Enabled);
```

--------------------------------

### Get data object without transforming using all method

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/transformers.md

Calls the all method to get an array representation without transforming properties, so Carbon objects remain as objects and nested data objects are not converted to arrays.

```php
ArtistData::from($artist)->all();
```

--------------------------------

### Create ResourceScope class

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Extends ApiScope with key 'resource'.

```php
class ResourceScope extends ApiScope
{
    public static function getScopeKey(): string
    {
        return 'resource';
    }
}
```

--------------------------------

### Data collection inside data object gets wrapped

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/wrapping.md

Shows that a data collection inside a data object gets wrapped when a wrapping key is set, mimicking Laravel resources. The collection is wrapped with 'data' inside the outer object's 'data' key.

```php
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');
```

```json
{
    "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"
                }
            ]
        }
    }
}
```

--------------------------------

### Use AutoInertiaLazy, AutoClosureLazy, and AutoInertiaDeferred attributes

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-inertia.md

Shows how to automatically make properties lazy for Inertia using attributes. The example uses #[AutoInertiaLazy], #[AutoClosureLazy], and #[AutoInertiaDeferred] on individual properties.

```php
use Spatie\LaravelData\Attributes\AutoClosureLazy;
use Spatie\LaravelData\Attributes\AutoInertiaLazy;
use Spatie\LaravelData\Attributes\AutoInertiaDeferred;

class SongData extends Data
{
    public function __construct(
        #[AutoInertiaLazy]
        public Lazy|string $title,
        #[AutoClosureLazy]
        public Lazy|string $artist,
        #[AutoInertiaDeferred]
        public Lazy|string $lyrics,
    ) {
    }
}
```

--------------------------------

### Use SongData::from with request

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/request-to-data-object.md

Shows how to create a data object from a request using the `from` method, which also validates the request data.

```php
class UpdateSongController
{
    public function __invoke(
        Song $model,
        SongRequest $request
    ){
        $model->update(SongData::from($request)->all());
        
        return redirect()->back();
    }
}
```

--------------------------------

### Looping over a DataCollection with foreach

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Shows how to iterate over a DataCollection using a foreach loop.

```php
foreach ($songs as $song){
    echo $song->title;
}
```

--------------------------------

### Group deferred properties with Lazy::inertiaDeferred

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-inertia.md

Shows how to group deferred properties by passing a group name as the second argument to Lazy::inertiaDeferred. The example groups 'artist' and 'lyrics' under the 'details' group. Note: the example contains a syntax error (missing comma after the first Lazy::inertiaDeferred line) as shown in the source.

```php
class SongData extends Data
{
    public function __construct(
        public Lazy|string $title,
        public Lazy|string $artist,
        public Lazy|string $lyrics,
    ) {
    }
    
    public static function fromModel(Song $song): self
    {
        return new self(
            Lazy::inertiaDeferred(fn() => $song->title),
            Lazy::inertiaDeferred(fn() => $song->artist, 'details')
            Lazy::inertiaDeferred(fn() => $song->lyrics, 'details')
        );
    }
}
```

--------------------------------

### Nullable attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the Nullable validation rule to a nullable string property.

```php
#[Nullable]
public ?string $closure; 
```

--------------------------------

### Create a data object with computed property

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/computed.md

Shows how to instantiate SongData using the from method with an array. The computed property is set automatically.

```php
SongData::from(['first_name' => 'Ruben', 'last_name' => 'Van Assche']);
```

--------------------------------

### Create SongData from model using fromModel

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Calls `from` with a model; the package will invoke the custom `fromModel` method instead of the default behavior.

```php
SongData::from(Song::firstOrFail($id));
```

--------------------------------

### Retrieve data object from model

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/eloquent-casting.md

Access the casted attribute to get the data object instance.

```php
Song::findOrFail($id)->artist; // ArtistData object
```

--------------------------------

### StartsWith attribute usage

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Shows three ways to pass arguments to the StartsWith attribute: single string, array, or multiple string arguments.

```php
#[StartsWith('a')]
public string $closure;
```

```php
#[StartsWith(['a', 'b'])]
public string $closure;
```

```php
#[StartsWith('a', 'b')]
public string $closure;
```

--------------------------------

### Filling properties from authenticated user with FromAuthenticatedUser

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/injecting-property-values.md

Shows how to use the FromAuthenticatedUser attribute to fill a property with the authenticated user object. The example defines a SongData class with a user property of type UserData.

```php
class SongData extends Data {
    #[FromAuthenticatedUser]
    public UserData $user;
}
```

--------------------------------

### MultipleOf attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the MultipleOf validation rule with a value of 3 to an integer property.

```php
#[MultipleOf(3)]
public int $closure; 
```

--------------------------------

### Include all lazy properties using wildcard

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Shows how to include all properties of posts using the include method with 'posts.*'.

```php
$postData->include('posts.*')->toJson();
```

--------------------------------

### MinDigits attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the MinDigits validation rule with a value of 2 to an integer property.

```php
#[MinDigits(2)]
public int $closure; 
```

--------------------------------

### Configure reflection discovery base path and root namespace

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/performance.md

Configure base path and root namespace when using reflection discovery with a non-standard directory structure or namespace.

```php
'structure_caching' => [
    'reflection_discovery' => [
        'enabled' => true,
        'base_path' => base_path(),
        'root_namespace' => null,
    ],
],
```

--------------------------------

### Min attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the Min validation rule with a value of 20 to an integer property.

```php
#[Min(20)]
public int $closure; 
```

--------------------------------

### MaxDigits attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the MaxDigits validation rule with a value of 10 to an integer property.

```php
#[MaxDigits(10)]
public int $closure; 
```

--------------------------------

### Max attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the Max validation rule with a value of 20 to an integer property.

```php
#[Max(20)]
public int $closure; 
```

--------------------------------

### Create ContractData from array with mapped keys

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/available-property-mappers.md

Shows how to instantiate the data object using an array with keys that match the mapped names. The keys include snake_case, a custom provided name, StudlyCase, lowercase, and uppercase variations.

```php
ContractData::from([
    'name' => 'Rick Astley',
    'record_company' => 'RCA Records',
    'country field' => 'Belgium',
    'CityName' => 'Antwerp',
    'addressline1' => 'some address line 1',
    'ADDRESSLINE2' => 'some address line 2',
]);
```

--------------------------------

### NotRegex attribute example

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Applies the NotRegex validation rule with a regular expression pattern to a string property.

```php
#[NotRegex('/^.+$/i')]
public string $closure; 
```

--------------------------------

### Create RequestScope class

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Extends ApiScope with key 'request'.

```php
class RequestScope extends ApiScope
{
    public static function getScopeKey(): string
    {
        return 'request';
    }
}
```

--------------------------------

### Example request payload

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/request-to-data-object.md

A JSON payload sent in a POST request to an endpoint, containing the fields `title` and `artist`.

```json
{
    "title" : "Never gonna give you up",
    "artist" : "Rick Astley"
}
```

--------------------------------

### Configure directories for data object discovery

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/performance.md

Specify directories to search for data objects. By default, the app/data directory is searched recursively.

```php
'structure_caching' => [
    'directories' => [
        app_path('Data'),
    ],
],
```

--------------------------------

### Override normalizers method in SongData

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/normalizers.md

Example of overriding the normalizers method on a data object to specify which normalizers to use.

```php
class SongData extends Data
{
    public function __construct(
        // ...
    ) {
    }

    public static function normalizers(): array
    {
        return [
            ModelNormalizer::class,
            ArrayableNormalizer::class,
            ObjectNormalizer::class,
            ArrayNormalizer::class,
            JsonNormalizer::class,
        ];
    }
}
```

--------------------------------

### Define allowedRequestIncludes for favorite_song

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Specifies that the 'favorite_song' property can be included via the query string. This is the first example of the allowedRequestIncludes method.

```php
class UserData extends Data
{
    public static function allowedRequestIncludes(): ?array
    {
        return ['favorite_song'];
    }

    // ...
}
```

--------------------------------

### Publish config file with artisan vendor:publish

Source: https://github.com/spatie/laravel-data/blob/main/docs/installation-setup.md

Publish the package's config file.

```bash
php artisan vendor:publish --provider="Spatie\LaravelData\LaravelDataServiceProvider" --tag="data-config"
```

--------------------------------

### Create a data object with a collection of data objects

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Shows how to define an AlbumData data object with a Collection of SongData objects and populate it using the `from` method. The package automatically converts the array into a collection of data objects.

```php
use App\Data\SongData;
use Illuminate\Support\Collection;

class AlbumData extends Data
{    
    public string $title;
    /** @var Collection<int, SongData> */
    public Collection $songs;
}

AlbumData::from([
    'title' => 'Never Gonna Give You Up',
    'songs' => [
        ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
        ['title' => 'Giving Up on Love', 'artist' => 'Rick Astley'],
    ]
]);
```

--------------------------------

### Create EloquentScope class

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Extends Scope with a fixed key 'eloquent'. Uses late static binding to get the scope key.

```php
class EloquentScope extends Scope
{
    public function __construct(?string $context = null)
    {
        parent::__construct(static::getScopeKey(), $context);
    }

    public static function getScopeKey(): string
    {
        return 'eloquent';
    }
}
```

--------------------------------

### wrap + transform with WrapExecutionType::Enabled

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/wrapping.md

Gets a wrapped array by explicitly setting a wrap key and enabling wrap execution during transformation.

```APIDOC
## wrap + transform with WrapExecutionType::Enabled

### Description
Gets a wrapped array by explicitly setting a wrap key and enabling wrap execution during transformation.

### Method
Method call on a data object instance.

### Endpoint
`SongData::from(Song::first())->wrap('data')->transform(wrapExecutionType: WrapExecutionType::Enabled)`

### Parameters
#### Method Arguments
- **wrapKey** (string) - Required - The key to wrap the data under.
- **wrapExecutionType** (WrapExecutionType) - Required - Set to `WrapExecutionType::Enabled` to enable wrapping.

### Request Example
```php
SongData::from(Song::first())->wrap('data')->transform(wrapExecutionType: WrapExecutionType::Enabled);
```

### Response
Returns an array with the data wrapped under the specified key.

```

--------------------------------

### Using only and except with special keys

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Use special key syntax like `songs.{name, artist}` to select multiple nested properties.

```php
AlbumData::from(Album::first())->only('songs.{name, artist}');
AlbumData::from(Album::first())->except('songs.{name, artist}');
```

--------------------------------

### Generated rules for nested payload

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/manual-rules.md

Shows the resulting validation rules when the example payload is provided, including nested rules for songs.

```php
[
    'title' => ['string', 'required'],
    'songs' => ['present', 'array'],
    'songs.*.title' => ['string', 'required'],
    'songs.*.artist' => ['string', 'nullable'],
    'songs.*' => [NestedRules(...)],
]
```

--------------------------------

### Create data object from model with ArtistData::from

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/model-to-data-object.md

Creates a data object from an Artist model instance using the static from method. The model is fetched with Artist::find(1).

```php
$artist = ArtistData::from(Artist::find(1));
```

--------------------------------

### Parameter placement in mapping attributes

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Shows the constructor signatures for MapInputName, MapOutputName, and MapName.

```php
- `MapInputName`: `__construct(public string|int $input, Scope|string|array|null $scope = null)`
- `MapOutputName`: `__construct(public string|int $output, Scope|string|array|null $scope = null)`
- `MapName`: `__construct(public string|int|NameMapper $input, public string|int|NameMapper|null $output = null, Scope|string|array|null $scope = null)`
```

--------------------------------

### Allow specific properties to be included

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Shows how to allow multiple specific properties (favorite_song and name) to be included via query string.

```php
class UserData extends Data
{
    public static function allowedRequestIncludes(): ?array
    {
        return ['favorite_song', 'name'];
    }
}
```

--------------------------------

### Reproduce the original bug with composer commands

Source: https://github.com/spatie/laravel-data/blob/main/specs/replace-phpdocumentor.md

Run these commands in a temporary directory to reproduce the dependency conflict between reflection-docblock ^5 and 6.0.3 before patching.

```bash
mkdir /tmp/ld-repro && cd /tmp/ld-repro
composer init -n --name=tmp/repro
composer require pestphp/pest:^4.3
composer config repositories.local path /Users/ruben/Spatie/laravel-data
composer require spatie/laravel-data:* --no-interaction
```

--------------------------------

### Allow all properties to be included

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Shows how to allow all properties to be included by returning null from allowedRequestIncludes.

```php
class UserData extends Data
{
    public static function allowedRequestIncludes(): ?array
    {
        return null;
    }
}
```

--------------------------------

### Create SongData with multiple arguments using fromMultiple

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Creates a data object by passing multiple arguments to the `from` method, which invokes the custom `fromMultiple` method.

```php
SongData::from('Never gonna give you up', 'Rick Astley');
```

--------------------------------

### Lazy properties in data class

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-livewire.md

Example of using Lazy properties in a data class, with a note that lazy properties that are not data cannot be queried.

```php
use Spatie\LaravelData\Lazy;

class LazySongData extends Data
{
    public function __construct(
        public Lazy|ArtistData $artist,
        public Lazy|string $title,
    ) {}    
}
```

--------------------------------

### Validate and create with SongData::validateAndCreate

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/introduction.md

Use `validateAndCreate` to validate data and create the object if validation passes. Returns a SongData object when the data is valid.

```php
SongData::validateAndCreate(
    ['title' => 'Never gonna give you up', 'artist' => 'Rick Astley']
); // returns a SongData object
```

--------------------------------

### Create ApiScope base class

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Base class for request/resource scopes. Uses late static binding so subclasses automatically get their own key.

```php
class ApiScope extends Scope
{
    public function __construct(?string $context = null)
    {
        parent::__construct(static::getScopeKey(), $context);
    }

    public static function getScopeKey(): string
    {
        return 'api';
    }
}
```

--------------------------------

### Generated validation rules output (without date rule)

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

The output of getValidationRules() for the example request. Notice the missing 'date' rule on 'published_at'.

```php
array:4 [
  "title" => array:2 [
    0 => "required"
    1 => "string"
  ]
  "content" => array:2 [
    0 => "required"
    1 => "string"
  ]
  "status" => array:2 [
    0 => "required"
    1 => Illuminate\Validation\Rules\Enum {
      #type: "App\Enums\PostStatus"
    }
  ]
  "published_at" => array:1 [
    0 => "nullable"
  ]
]
```

--------------------------------

### Use collectArray to create a SongCollection

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Example usage of the custom collect method. It returns a SongCollection of SongData objects from an array of associative arrays.

```php
SongData::collectArray([
    ['title' => 'Never Gonna Give You Up', 'artist' => 'Rick Astley'],
    ['title' => 'Living on a prayer', 'artist' => 'Bon Jovi'],
]); // returns an SongCollection of SongData objects
```

--------------------------------

### Output with wrapping enabled

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/transformers.md

Shows the resulting array when wrapping is enabled, with the data wrapped under a 'data' key.

```php
[
    'data' => [
        'name' => 'Rick Astley',
        'birth_date' => '06-02-1966',
    ],
]
```

--------------------------------

### Use a different guard with AuthenticatedUserReference

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/using-validation-attributes.md

Pass the guard name to the AuthenticatedUserReference constructor to use a different guard than the default. This example uses the 'api' guard.

```php
class UserData extends Data
{
    public function __construct(
        public string $name,
        #[Unique('users', 'email', ignore: new AuthenticatedUserReference(guard: 'api'))]
        public string $email,
    ) {   
    }
}
```

--------------------------------

### Authorizing a request: SongData with authorize() method

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/introduction.md

Data class with an authorize() method that returns false to throw an AuthorizationException.

```php
class SongData extends Data
{
    public function __construct(
        public string $title,
        public string $artist,
    ) {
    }

    public static function authorize(): bool
    {
        return Auth::user()->name === 'Ruben';
    }
}
```

--------------------------------

### Create author and transform to data object

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

PHP code to create an author, add posts, and transform to AuthorData using fromModel.

```php
$author = Author::create([
    'name' => 'Ruben Van Assche'
]);

$author->posts()->create([        
    [
        'title' => 'Hello laravel-data',
        'content' => 'This is an introduction post for the new package',
        'status' => 'draft',
        'published_at' => null,
    ]
]);

AuthorData::from($author);
```

--------------------------------

### Create PostData from array with nested image

Source: https://github.com/spatie/laravel-data/blob/main/docs/getting-started/quickstart.md

Demonstrates creating a PostData instance from an array, including a nested image array with filename and size keys.

```php
return PostData::from([
    'title' => 'Hello laravel-data',
    'content' => 'This is an introduction post for the new package',
    'status' => PostStatus::published,
    'image' => [
        'filename' => 'images/8JQtgd0XaPtt9CqkPJ3eWFVV4BAp6JR9ltYAIKqX.png',
        'size' => 16524
    ],
    'published_at' => CarbonImmutable::create(2020, 05, 16),
]);
```

--------------------------------

### Scope parameter with instance and class-string

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Shows how to pass scope as an instance or class-string to mapping attributes.

```php
// Instance (when you need context or custom key)
#[MapInputName('display_name', scope: new EloquentScope())]
#[MapInputName('usr_id', scope: new Scope('stripe'))]

// Class-string (cleaner when no context needed)
#[MapInputName('display_name', scope: EloquentScope::class)]
#[MapInputName('displayName', scope: RequestScope::class)]
```

--------------------------------

### Controller returning a collection of data objects

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Shows a controller that returns a collection of SongData objects from all songs.

```php
class SongController
{
    public function index()
    {
        return SongData::collect(Song::all());    
    }
}
```

--------------------------------

### Create a DataCollection using collect

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/collections.md

Creates a DataCollection from a collection of Song models using the `collect` method.

```php
use Spatie\LaravelData\DataCollection;

SongData::collect(Song::all(), DataCollection::class);
```

--------------------------------

### Generate a data object with make:data

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/commands.md

Run this artisan command to create a new data object named PostData in the default App\Data namespace.

```shell
php artisan make:data PostData
```

--------------------------------

### Generated validation rules for default values example

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/introduction.md

The resulting validation rules from the previous validation call. Only the title rule is present because the artist uses its default.

```php
[
    'title' => ['required', 'string'],
]
```

--------------------------------

### Format enum definition

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/casts.md

Defines a string-backed enum named Format with cases cd, vinyl, and cassette. This enum is used as a property type in the SongData example.

```php
enum Format: string {
    case cd = 'cd';
    case vinyl = 'vinyl';
    case cassette = 'cassette';
}
```

--------------------------------

### Create model with null songs and access collection

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/eloquent-casting.md

Create an Artist with a null 'songs' attribute and access the resulting DataCollection. The collection is empty and count returns 0.

```php
$artist = Artist::create([
    'songs' => null
]);

$artist->songs; // DataCollection
$artist->songs->count();// 0
```

--------------------------------

### Create data object with prepared payload

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/pipeline.md

After defining prepareForPipeline, create a data object from an array. The metadata is automatically extracted from the release_year and producer keys.

```php
$songData = SongData::from([
    'title' => 'Never gonna give you up',
    'release_year' => '1987',
    'producer' => 'Stock Aitken Waterman',
]);
```

--------------------------------

### Ignore a specific magical method with ignoreMagicalMethod()

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/factories.md

Use ignoreMagicalMethod('fromString') to ignore a specific magical method. The from() call will not use the ignored method, so the example will not work as expected.

```php
SongData::factory()->ignoreMagicalMethod('fromString')->from('Never gonna give you up'); // Won't work since the magical method is ignored
```

--------------------------------

### Scope parameter with array for multiple scopes

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Shows how to apply one mapping to multiple scopes using an array.

```php
// Single scope
#[MapInputName('display_name', scope: EloquentScope::class)]

// Multiple scopes
#[MapInputName('display_name', scope: [EloquentScope::class, new Scope('legacy')])]
```

--------------------------------

### Append properties with additional() method

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/appending-properties.md

Use the additional() method to add extra properties to the transformed data object. The example adds a 'year' property with a static value.

```php
SongData::from(Song::first())->additional([
    'year' => 1987,
]);
```

```php
[
    'name' => 'Never gonna give you up',
    'artist' => 'Rick Astley',
    'year' => 1987,
]
```

--------------------------------

### MapName attribute for combined input and output mapping

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/mapping-property-names.md

Use the MapName attribute to combine input and output property name mapping. This example uses SnakeCaseMapper for both directions.

```php
#[MapName(SnakeCaseMapper::class)]
class ContractData extends Data
{
    public function __construct(
        public string $name,
        public string $recordCompany,
    ) {
    }
}
```

--------------------------------

### Optional creation with SongData::optional

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Use the optional method to return null instead of throwing an error when the value is null. Underneath, it calls the from method when a value is given.

```php
SongData::optional(null); // returns null
```

--------------------------------

### Create data object from eloquent model

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/normalizers.md

Shows the basic usage of the from method to create a data object from an eloquent model.

```php
SongData::from(Song::findOrFail($id));
```

--------------------------------

### Manually use Optional in a magical creation method

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/optional-properties.md

Shows how to manually create an Optional value using Optional::create() within a static creation method.

```php
class SongData extends Data
{
    public function __construct(
        public string $title,
        public string|Optional $artist,
    ) {
    }
    
    public static function fromTitle(string $title): static
    {
        return new self($title, Optional::create());
    }
}
```

--------------------------------

### Append properties with closure in additional()

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/appending-properties.md

Use a closure in the additional() method to access the underlying data object and compute the property value dynamically. The example generates a slug from the title.

```php
SongData::from(Song::first())->additional([
    'slug' => fn(SongData $songData) => Str::slug($songData->title),
]);
```

```php
[
    'name' => 'Never gonna give you up',
    'artist' => 'Rick Astley',
    'slug' => 'never-gonna-give-you-up',
]
```

--------------------------------

### Group deferred properties with AutoInertiaDeferred attribute

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-inertia.md

Shows how to specify a group name for the AutoInertiaDeferred attribute to group deferred properties. The example groups 'artist' and 'lyrics' under the 'details' group.

```php
class SongData extends Data
{
    public function __construct(
        #[AutoInertiaDeferred()]
        public Lazy|string $title,
        #[AutoInertiaDeferred('details')]
        public Lazy|string $artist,
        #[AutoInertiaDeferred('details')]
        public Lazy|string $lyrics,
    ) {
    }
}
```

--------------------------------

### Same attribute usage

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/validation-attributes.md

Shows how to use the Same attribute with a single field name argument.

```php
#[Same('other_field')]
public string $closure; 
```

--------------------------------

### Livewire component with a data object property

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/use-with-livewire.md

Shows a Livewire component using a SongData object as a public property, initialized in mount() from an Eloquent model.

```php
class Song extends Component
{
    public SongData $song;

    public function mount(int $id)
    {
        $this->song = SongData::from(Song::findOrFail($id));
    }

    public function render()
    {
        return view('livewire.song');
    }
}
```

--------------------------------

### Run static analysis with PHPStan

Source: https://github.com/spatie/laravel-data/blob/main/specs/mapping-scopes.md

Runs PHPStan to ensure static analysis passes.

```bash
./vendor/bin/phpstan analyse
```

--------------------------------

### Use getData in a controller with a FormRequest

Source: https://github.com/spatie/laravel-data/blob/main/docs/advanced-usage/get-data-from-a-class-quickly.md

In a controller, inject the request and call getData() to obtain the data object. The example shows creating a Song from the data and returning the data object.

```php
class SongController
{
    public function __invoke(SongRequest $request): SongData
    {
        $data = $request->getData();
    
        $song = Song::create($data->toArray());
        
        return $data;
    }
}
```

--------------------------------

### Magical fromModel method

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-data-transfer-object/creating-a-data-object.md

Adds a static `fromModel` method to customize creation from an Eloquent model. The method must be static, public, start with 'from', and not be named exactly 'from'.

```php
class SongData extends Data
{
    public function __construct(
        public string $title,
        public string $artist,
    ) {
    }
    
    public static function fromModel(Song $song): self
    {
        return new self("{$song->title} ({$song->year})", $song->artist);
    }
}
```

--------------------------------

### Reference route parameter in validation attribute

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/using-validation-attributes.md

Use RouteParameterReference to ignore the current route parameter in a Unique validation rule. The parameter name 'song' is used to get the current id.

```php
class SongData extends Data
{
    public function __construct(
        public string $title,
        #[Unique('songs', ignore: new RouteParameterReference('song'))]
        public int $id,
    ) {
    }
}
```

--------------------------------

### Include multiple properties with array query

Source: https://github.com/spatie/laravel-data/blob/main/docs/as-a-resource/lazy-properties.md

Shows the URL format for including multiple properties using array syntax in the query string.

```text
https://spatie.be/my-account?include[]=favorite_song&include[]=favorite_movie
```

--------------------------------

### Example data class ArtistData

Source: https://github.com/spatie/laravel-data/blob/main/docs/validation/auto-rule-inferring.md

A data class with typed properties that the package uses to infer validation rules. The properties are string $name, int $age, and nullable string $genre.

```php
class ArtistData extends Data{
    public function __construct(
        public string $name,
        public int $age,
        public ?string $genre,
    ) {
    }
}
```
Tokens:
Raw