Differentiate explicit null from default using __UNSET__ in whenLoaded method

[HichemTab-tech]

Fixes #55374.

Description

Due to the PHP 8 named arguments feature, we encountered an ambiguity issue. Previously, when calling methods like whenLoaded, explicitly passing a null argument was indistinguishable from omitting the argument completely. This ambiguity could cause unexpected results, like unintentionally returning the entire related entity instead of the intended null value.

For example, before this fix, the following call:

'value' => $this->whenLoaded('entity', $this->resource->entity->comment),

would incorrectly return the whole 'entity' object if comment was null in the database (and that's because of the changes intriduced in #51342 because of null verification)

{
  "value": {
    // entity object returned instead of null
  }
}

To resolve this ambiguity clearly and effectively, we've introduced a sentinel default value ('__UNSET__') to reliably identify if an argument was explicitly provided as null or simply omitted.

Changes

• Before:

  protected function whenLoaded($relationship, $value = null, $default = null)

  (Cannot distinguish an explicitly provided null from omitted parameter)

• After:

  protected function whenLoaded($relationship, $value = '__UNSET__', $default = null)

  (Clearly distinguish an explicitly provided null from omitted parameter)

Impact of this Change

With this fix, explicitly passing null will behave correctly and predictably:

• Calling whenLoaded('relation', null) explicitly returns null as intended.
• Improves internal logic by clearly differentiating between omitted parameters and explicitly provided null.

Now, the example above returns the correct result:

{
  "value": null
}

[AndrewMast]

Just as a note, a string like __UNSET__ hasn't been used before in the Laravel framework. Because of this, it will probably be denied. Usually, new stdClass is used to determine if a method is returning the default value (see Collection::contains).

[AndrewMast]

Maybe an alternative to if ($value === null) could be if (func_num_args() === 1), so if someone passes in null for $value, it won't trigger it.

[HichemTab-tech]

Maybe an alternative to if ($value === null) could be if (func_num_args() === 1), so if someone passes in null for $value, it won't trigger it.

Well unfortunately no, with named arguments of php 8 if we call the third argument without the second like this :

whenLoaded('relation', default: null)

The func_num_args still returns 3 :/

[HichemTab-tech]

Just as a note, a string like __UNSET__ hasn't been used before in the Laravel framework. Because of this, it will probably be denied. Usually, new stdClass is used to determine if a method is returning the default value (see Collection::contains).

yes the problem here is we may have the model property cast to stdClass, so we would still fall in the case where we dont know if the stdClass is provided or unspecified by default

$this->whenLoaded('entity', $this->resource->entity->comment),

protected $casts = [
    'comment' => 'object',
];

So in this case the comment would be stdClass (I think).

[taylorotwell]

Potential breaking change.

[HichemTab-tech]

Potential breaking change.

Sorry @taylorotwell but i believe there is no action required by users at all in this case (no breaking change for users at least), this PR will just fix the problem caused by #51342 please check the PR mentioned and the related issue #55374