Pipeline | laravel-data | Spatie

 SPATIE

  Laravel Data
===============

spatie.be/open-source

  [Docs](https://spatie.be/docs)  [Laravel-data](https://spatie.be/docs/laravel-data/v2)  Advanced-usage  Pipeline

 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                                                                                                                                                                                                                                    `

Pipeline
========

###  On this page

1. [ Preparing data for the pipeline ](#content-preparing-data-for-the-pipeline)
2. [ Extending the pipeline within your data class ](#content-extending-the-pipeline-within-your-data-class)

The data pipeline allows you to configure how data objects are constructed from a payload. In the previous chapter we saw that a data object created from a payload will be first normalized into an array. This array the is passed into the pipeline.

The pipeline exists of multiple pipes which will transform the normalized data into a collection of property values which can be passed to the data object constructor.

By default, the pipeline exists of the following pipes:

- **AuthorizedDataPipe** checks if the user is authorized to perform the request
- **MapPropertiesDataPipe** maps the names of properties
- **ValidatePropertiesDataPipe** validates the properties
- **DefaultValuesDataPipe** adds default values for properties when they are not set
- **CastPropertiesDataPipe** casts the values of properties

Each result of the previous pipe is passed on into the next pipe, you can define the pipes on an individual data object as such:

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

    public static function pipeline(): DataPipeline
    {
        return DataPipeline::create()
            ->into(static::class)
            ->through(AuthorizedDataPipe::class)
            ->through(MapPropertiesDataPipe::class)
            ->through(ValidatePropertiesDataPipe::class)
            ->through(DefaultValuesDataPipe::class)
            ->through(CastPropertiesDataPipe::class);
    }
}
```

Each pipe implements the `DataPipe` interface and should return a `Collection` of properties:

```
interface DataPipe
{
    public function handle(mixed $payload, DataClass $class, Collection $properties): Collection;
}
```

The `handle` method has several arguments:

- **payload** the non normalized payload
- **class** the `DataClass` object for the data object [more info](/docs/laravel-data/v2/advanced-usage/internal-structures)
- **properties** the key-value properties which will be used to construct the data object

When using a magic creation methods, the pipeline is not being used (since you manually overwrite how a data object is constructed). Only when you pass in a request object a minimal version of the pipeline is used to authorize and validate the request.

Preparing data for the pipeline
-----------------------------------------------------------------------------------------------------------------------------------------------------

Sometimes you need to make some changes to the payload after it has been normalized, but before they are sent into the data pipeline. You can do this using the `prepareForPipeline` method as follows:

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

class Song extends Data
{
    public function __construct(
        public string $title,
        public SongMetadata $metadata,
    ) {}

    public static function prepareForPipeline(Collection $properties) : Collection
    {
        $properties->put('metadata', $properties->only(['release_year', 'producer']));

        return $properties;
    }
}
```

Now it is possible to create a data object as follows:

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

Extending the pipeline within your data class
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Sometimes you want to send your payload first through a certain pipe without creating a whole new pipeline, this can be done as such:

```
class Song extends Data
{
    public static function pipeline(): DataPipeline
    {
        return parent::pipeline()->firstThrough(GuessCasingForKeyDataPipe::class);
    }
}
```