Original PR: https://github.com/spatie/laravel-data/pull/127 (was closed due to the deletion of the v2 branch)

This PR is a second take at https://github.com/spatie/laravel-data/pull/119, that does not replace the default behavior but supports the newly configurable one.

It depends on https://github.com/spatie/typescript-transformer/pull/30 and https://github.com/spatie/laravel-typescript-transformer/pull/15. Both of these should be merged before this PR (tests will not pass anyway).

What's important:

• The #[Optional] attribute from typescript-transformer is taken into account
• The new transform_null_to_optional option from laravel-typescript-transformer is taken into account
• The current behavior does not change unless one of the above is true

Example:

use Spatie\TypeScriptTransformer\Attributes\Optional;

class UserData
{
    public function __construct(
        #[Optional]
        public int $id,
        public string $first_name,
    ) {
    }
}

interface UserData {
  id?: number
  first_name: string
}

The Optional attribute above would not be necessary if config/typescript-transformer.php's transform_null_to_optional is set to true (which is false by default to preserve current behavior).

This PR attempts to solve the problem identified by @medvinator in #256 which is something our team has also run into. If you want to dynamically build validation rules depending on the payload it's very difficult at the moment as the data object receives the full payload and doesn't know the path to its data.

E.g. a data object inside a collection won't know that the path to its data is collection.2.example and this makes rule generation very difficult to work with at the moment.

This PR approaches this problem by building the validation rules for each set of data. There's some pros and cons to this approach. The pros are that you can now build validation rules using the data relative to the object. However, collections with many many objects inside them will generate rules like:

collection.0.example, collection.1.example, collection.2.example etc.

In addition, if there's no data inside the collection no rule will be generated for the child field. E.g. no collection.*.example

I'm not sure of the best way to approach that problem and for our team the overheard in rule generation wouldn't be an issue and is worth the dynamic validation functionality.

This PR probably requires more tests and some code improvements, but I thought I'd create it to see what your thoughts are and start the discussion 😄

Thanks for creating an amazing package!

This PR is a second take at https://github.com/spatie/laravel-data/pull/119, that does not replace the default behavior but supports the newly configurable one.

It depends on https://github.com/spatie/typescript-transformer/pull/30 and https://github.com/spatie/laravel-typescript-transformer/pull/15. Both of these should be merged before this PR (tests will not pass anyway).

What's important:

• The #[Optional] attribute from typescript-transformer is taken into account
• The new transform_null_to_optional option from laravel-typescript-transformer is taken into account
• The current behavior does not change unless one of the above is true

Example:

use Spatie\TypeScriptTransformer\Attributes\Optional;

class UserData
{
    public function __construct(
        #[Optional]
        public int $id,
        public string $first_name,
    ) {
    }
}

interface UserData {
  id?: number
  first_name: string
}

The Optional attribute above would not be necessary if config/typescript-transformer.php's transform_null_to_optional is set to true (which is false by default to preserve current behavior).

cc @rubenvanassche

Using Win 11 / WSL 2 (Ubuntu) / PHP 8.1.12.

Test usage:

$tmp = json_decode($employeesJson, true)[0];
$data = Employee::from($tmp);
rd($tmp, $data);

👍 works

use Spatie\LaravelData\Attributes\MapInputName;
use Spatie\LaravelData\Data;

class EmployeeData extends Data
{
    public function __construct(
        #[MapInputName('Id')]                   public ?int $id = null,
        #[MapInputName('ReferenceId')]          public ?string $referenceId = null,
        #[MapInputName('OrganizationalUnitId')] public ?int $organizationalUnitId = null,
        #[MapInputName('Active')]               public ?bool $active = null,
    ) { }
}
/* Ray output
array:32 [▼
  "Id" => 69
  "ReferenceId" => "552"
  "OrganizationalUnitId" => 123011821
  "Active" => true
]
App\Data\EmployeeData {#3342 ▼
  +id: 69
  +referenceId: "552"
  +organizationalUnitId: 123011821
  +active: true
}
*/

👎doesn't

use Spatie\LaravelData\Attributes\MapInputName;
use Spatie\LaravelData\Data;
use Spatie\LaravelData\Mappers\CamelCaseMapper;

#[MapInputName(CamelCaseMapper::class)]
class EmployeeData extends Data
{
    public function __construct(
        public ?int $id = null,
        public ?string $referenceId = null,
        public ?int $organizationUnitId = null,
        public ?bool $active = null,
    ) { }
}
/* Ray output
array:32 [▼
  "Id" => 69
  "ReferenceId" => "552"
  "OrganizationalUnitId" => 123011821
  "Active" => true
]
App\Data\EmployeeData {#3342 ▼
  +id: null
  +referenceId: null
  +organizationalUnitId: null
  +active: null
}
*/

Perhaps I just misunderstood the intended usage or something...

This PR adds a way to transform something into a DTO without using the custom transform methods.

I often need to transform models but modify some of their properties during the process. For instance, a model using HashIDs should not have its id used in the DTO, but its HashID.

Currently, I use a custom from method, and I call toArray() on the model:

public static function fromDummyModel(DummyModel $model): static
{
    return static::from([
        ...$model->toArray(),
        'id' => $model->getRouteKey()
    ]);
}

The issue is that this will not take nested DTOs into account. If my model has a relation, and that relation is setup as a DTO, the custom creation methods for these nested DTOs are never called, because the relations are serialized in the first toArray call.

To fix that, this PR adds a throughPipeline method that will pass the given value through the transform pipeline while ignoring custom transform methods. This method can be called inside a custom transform method, fixing the issues above.

public static function fromDummyModel(DummyModel $model)
{
    return static::from([
        ...self::throughPipeline($model)->toArray(),
        'id' => $model->getRouteKey(),
    ]);
}

If you have a better name than throughPipeline, feel free to change it. I couldn't come up with a better idea. 😅

This pull request contains changes for migrating your test suite from PHPUnit to Pest automated by the Pest Converter.

Before merging, you need to:

• Checkout the shift-64030 branch
• Review all of the comments below for additional changes
• Run composer update to install Pest with your dependencies
• Run vendor/bin/pest to verify the conversion

Hi there,

First, love Laravel Data. Thanks 🙏

I've ran into an issue while testing. Here's my DTO with 6 required attributes:

class UserRegisterData extends Data
{
public function __construct(
        #[Max(50),
        Min(3),
        ]
        public string $firstname,
        public string $lastname,
        #[Unique('accounts'),
        Email('strict')]
        public string $email,
        #[Password(12, true, true, true, true)]
        public string $password,
        #[Size(2)]
        public string $country,
        public bool $optin_news,
    ) {
    }
}

Then I create my DTO doing

        $data = UserRegisterData::validateAndCreate($input);

If I pass only 5 attributes, like

 [
  "email" => "[email protected]"
  "firstname" => "John"
  "lastname" => "Doe"
  "password" => "&(§jjd==51254AAa"
  "optin_news" => false
]

It fails with a 422 error, which is expected behavior.

But If I don't pass optin_news:

[
  "firstname" => "John"
  "lastname" => "Doe"
  "email" => "[email protected]"
  "password" => "&(§jjd==51254AAa"
  "country" => "fr"
]

I got a 500:

Could not create `Domain\Shared\DataTransferObjects\UserRegisterData`: the constructor requires 6 parameters, 5 given.Parameters given: firstname, lastname, email, password, country.

I don't get why and how I should do to get a normal validation error when this arg is missing?

Thanks :)

Hey!

After the latest update to the laravel-data version 2.0.16, for some reason I need to declare an extra prepareForPiplenie static method.

Is this a bug or an undocumented breaking change?

Thanks

This PR is the same as https://github.com/spatie/laravel-data/pull/120, except it targets the v2 branch and makes a breaking change by updating the configuration format.

I realized that when serializing a date, having multiple formats didn't make sense. So I updated the configuration to have a from and to option, where from is an array of supported input date formats, and to the format to which a date will be serialized into.

Initial PR text:

This PR adds support for multiple date formats, instead of just one. When working with multiple applications (web front-end, APIs, etc), it's easier to accept multiple instead of requiring a specific one.

This change is fully backwards-compatible, but allows the date_format configuration option to be an array.

The DateTimeInterfaceCast will now loop through the configured formats and use the first one that doesn't fail. If all of them fail, it will throw as usual.

Additionnally, I added the most-commonly used formats as the defaults: ATOM, ISO8601, and Y-m-d H:i:s (the same but without the period).

Partially related: https://github.com/php/php-src/pull/8322

This PR adds support for conditionally omitting properties from a DTO. Please refer to https://github.com/spatie/laravel-data/discussions/111 for the context. It also partially addresses https://github.com/spatie/laravel-data/discussions/5, and https://github.com/spatie/laravel-data/discussions/84 (v2) since it's on the "consider" list.

An excludeWhen and an except method have been added through a trait, which makes it possible to either define how to exclude properties conditionnally, or to exclude them at runtime.

The documentation has been updated too.

Examples

Omitting properties conditionally:

class UserData extends Data
{
    public function __construct(
        public int $id,
        public string $name,
    ) {
    }
    
    public function excludeWhen(): array
    {
        return [
          'id' => !auth()->user()?->is_admin
        ];
    }
}

Omitting properties at runtime:

UserData::from($user)->exclude('id', 'password');

I have a use case that I want to use a custom transformer targeting a data class- can we re-order this logic to run the auto data/data collection after looking for custom transformers?

While I wanted to extend the class and implement the fix for #311 in my own implementation of the class (and DI'ing it), overriding the method, I noticed these functions were defined private, so I was unable access them in my class.

When using custom validation rules with regex and "|" character, we end up with this error message : preg_match(): No ending delimiter '/' found

in this example, each rule will fail :

use App\Support\DataTransfertObjects\Data;

class TestData extends Data
{
    public function __constructor(
        public readonly string $name
        public readonly string $other
    ) {}

    public static function rules()
    {
        return [
            'name' => 'required|regex:/test|ok/',
            'other' => ['required', 'regex:/test|ok/']
        ];
    }
}

This PR add support for regex rule with "|" character. But there is a constraint : users must provide custom rules as array. This is ok :

[
     'name' => ['required', 'regex:/test|ok/']
]

but not this :

[
     'name' => 'required|regex:/test|ok/'
]

That's why i added a note in the documentation.

An attempt to fix the issue described in https://github.com/spatie/laravel-data/issues/309 I'm not really confident that I put the fix in the right place though; maybe it belongs inside the DataClassValidationRulesResolver instead.

Consider a CreateAddressData object defined as follows:

class CreateAddressData extends Data {
  public function __construct(
    public readonly string $street,
    public readonly string $nbr,
    public readonly string $postal_code,
    public readonly string $city,
    public readonly string $cc
  ) {
  }

  public static function rules() {
    return [
      'street' => 'required|min:1|max:80',
      'nbr' => 'required|max:20',  
      'postal_code' => 'required|min:4|max:20',
      'city' => 'required|min:1|max:50',
      'cc' => 'required|size:2',
    ];
  }
}

And we have a CreatePersonData with the following definition:

class CreatePersonData extends Data {
  public function __construct(
    public readonly string $first_name,
    public readonly string $last_name,
    public readonly string $email,
    public readonly ?CreateAddressData $address // Please note the address is OPTIONAL
  ) {
  }

  public static function rules() {
    return [
      'first_name' => 'required|min:1|max:50',
      'last_name' => 'required|min:1|max:50',
      'email' => 'required|email:rfc',
      'address' => '', // No validation rules for the address, as it's considered optional!
    ];
  }

The idea being that a person can optionally have an address, but when an address is given, the properties are correctly being validated...

The following code however throws a validation exception saying The address.street field is required. (and 4 more errors):

  CreatePersonData::validate(
    [
      'first_name' => $value,
      'last_name' => fake()->lastName(),
      'email' => fake()->email(),
    ]
  );

Shouldn't the nested data object only be validated when it is required in the containing data object or when it's optional and provided as part of the containing object?

I haven't checked the code yet (will do asap though), but Im only guessing you are merging the validation rules from the nested objects into the rules array for the containing one, but we should probably loop-validate instead, no?

Having a SlotLoadItem beeing a Data and a SlotLoadCollection beeing a DataCollection, I would expect that defining

protected $casts = [
        'slots' => SlotLoadCollection::class . ':' . SlotLoadItem::class,
];

gives me a SlotLoadCollection when fetching $model->slots. Currently, it gives me a DataCollection.

This PR fixes it.

I'm not sure if changing DataCollectionEloquentCast constructor signature is considered as a breaking change but IMHO it should not cause too much trouble.