[9.x] Allow for null handling in custom casts

[jnoordsij]

This is a breaking change to how custom casts are handled. Currently, when null is provided to a property that has a custom cast, all array keys present in the response of the set method are automatically set to null regardless of what the set method does.

While a reasonable default, I think it should be better to leave it to the set implementation to choose how to deal with null values being set. I haven't been able to think of any easy solution to keep the old 'default' behavior, hence a breaking change.

Note that the first part of this PR should be non-breaking and is part of #38004.

[taylorotwell]

To help understand the breaking changes here, could you write an example migration guide / upgrade guide for this new functionality - what would people with existing casts need to do to all of their casts?

[jnoordsij]

I think this is almost more of a bugfix rather than a breaking change. The example from the docs shows that the current behavior might be quite confusing to some (including me).

Example (from the docs): you have a model User with an address property (which consists of address_line_one and address_line_two in your attributes/database), which has a corresponding Address cast. Within the set method, a check is done to ensure the provided $value is an instance of AddressModel.

You try to set $user->address = null, then the following happens:

• Current situation: the attributes address_line_one and address_line_two are set to null without further warning or notice
• After this PR (which I think would be the expected behavior for most): an InvalidArgumentException is thrown

To migrate your current casts, you should add some clause to handle the case where $value is null, if it isn't properly handled yet. For our example you should add the following within the set method of your cast class if you want to keep the old behavior:

if (is_null($value)) {
    // do your null handling here, e.g.
    return [
        'address_line_one' => null,
        'address_line_two' => null,
    ];
}