[11.x] Adds Model::casts() method and named static methods for built-in casters

[nunomaduro]

Depends on: #47235.

This pull request is originally created from ideas of #46649, does not have any breaking change, and it enables the usage of an new Model::casts() method and named static methods for built-in casters.

class User extends Model
{
    /**
     * The attributes that should be cast.
     */
    protected function casts(): array
    {
        return [
            'options' => AsCollection::using(OptionCollection::class),
                      // AsEncryptedCollection::using(OptionCollection::class),
                      // AsEnumArrayObject::using(OptionEnum::class),
                      // AsEnumCollection::using(OptionEnum::class),
        ];
    }
}

Note that, by enabling the casts() method, developers can easily use named static methods on the built-in casters. In addition, they may add their own named static methods to their own casters if they want. As syntax, just like AsCollection::using(OptionCollection::class) is not supported when using properties.

For convenience, support for "array" syntax, on the property and method, was also added on this pull request, so developers can also use this syntax:

    protected $casts = [
        'carOptions' => [AsCollection::class, OptionCollection::class],
    ];

    protected function casts(): array
    {
        return [
            'bookOptions' => [AsCollection::class, OptionCollection::class],
        ];
    }

Finally, some technical details: as already mentioned, this pull request does not introduce any breaking changes. Also, there are no performance drawbacks as the merging of the method and property occurs during class instantiation.

In addition, when an attribute is defined both on the property and method, the method one takes priority.

[innocenzi]

unless there is an Model has a "casts" relation, witch is very unlikely

I'm not so sure about that, it totally sounds like a possible relation name. In the previous PR, that was my main concern with the idea of having a method for allowing named constructors.

Maybe we can check the return type of the casts method, and use it for the casts feature if it's array, and otherwise ignore it? Though that might hurt performance.

That point put apart, LGTM. I'm really looking forward to the array syntax. 👍

[taylorotwell]

@innocenzi I'm not sure if a breaking change on casts method needs to be worried about. For example, imagine the following scenario on current 10.x without even merging this PR:

The someOtherMethod method would throw an error, because you would be referencing the casts property and not the casts relationship. So, defining a casts relationship on a model is already semi-broken on 10.x and can lead to unreliable behavior and errors. Any reference to the relationship $this->casts such as $this->casts->map would break and throw an error.

[innocenzi]

@taylorotwell I see, interesting. Seems like we can go forward with casts() then. 👍

[nunomaduro]

@taylorotwell Rebased to Laravel 11.x.

[oleynikd]

Using laravel/framework v10.48.9
If I use new casts() method to cast attributes in my Model:

protected function casts(): array
{
    return [
        'starts_at' => 'datetime',
    ];
}

Then my starts_at is still a string:

php artisan tinker
MyModel::first()->starts_at
= "2024-04-24 21:19:09"

But if I use $casts property to cast attributes in my model:

protected $casts = [
    'starts_at' => 'datetime',
];

Then everythig works as expected:

php artisan tinker
MyModel::first()->starts_at
= Illuminate\Support\Carbon @1713993549 {#5208
    date: 2024-04-24 21:19:09.0 UTC (+00:00),
  }

Am I doing something wrong?

[driesvints]

@oleynikd this was merged into 11.x not 10.x