Allow casters to parse null values and provide default or Injected values

[Robertbaelde]

In my project I'm using the ObjectHydrator in order to parse api calls to commands and queries.

One caster that would really improve DX would be a "AuthenticatedUser" caster, providing the UserId that is authenticated in the session.

In code, usage of it would look like this:

/** @implements Query<array<Organization>> */
#[ApiQuery]
final readonly class GetUserOrganisations implements Query
{
    public function __construct(
        #[AuthenticatedUser]
        public UserId $userId,
        public int $limit = 10,
    ) {}
}

And the "caster" itself would look something like this:

#[Attribute(Attribute::TARGET_PARAMETER)]
final readonly class AuthenticatedUser implements PropertyCaster
{
    public function cast(mixed $value, ObjectMapper $hydrator): mixed
    {
        $user = \Auth::user();
        if($user === null) {
            throw new \Exception("User not authenticated");
        }

        return UserId::fromString($user->id);
    }
}

In order for this to work, we need to skip the null check before casters are triggered, and allow casters to process a value of null. This PR enables that.

Technically we could discuss if providing the Authenticated User ID is a "caster". However I wouldn't know what else to call it, and it seems a bit heavy to introduce a lot of code to support this simple use-case. Open to suggestions though!

Note, this is a breaking change, since current casters might not expect to handle null as value.
See the change I had to make to src/PropertyCasters/CastToDateTimeImmutable.php as example.

[frankdejonge]

Sorry for the long delay... but: unless I'm mistaken, this introduces a behavioural breaking change for existing casters that do not expect to receive a null value. We could introduce an interface that ... when it' null we only go into the caster if the marker interface is present on the caster. WDYT?