Stringable "when..." Return Types

[gavg-vaioni]

Illuminate\Support\Stringable contains several "when..." functions (whenContains, whenContainsAll, whenEmpty, whenNotEmpty etc).

These each use the "when" function in the Illuminate\Support\Traits\Conditionable trait.

However, the docblock return types of the Stringable functions don't match the docblock return types of the Conditionable when function.

The "when" function declares its return type as "@return $this|TWhenReturnType" (via @template TWhenReturnType), whereas the Stringable functions declare "@return static"

Conditionable->when

    /**
     * Apply the callback if the given "value" is (or resolves to) truthy.
     *
     * @template TWhenParameter
     * @template TWhenReturnType
     *
     * @param  (\Closure($this): TWhenParameter)|TWhenParameter|null  $value
     * @param  (callable($this, TWhenParameter): TWhenReturnType)|null  $callback
     * @param  (callable($this, TWhenParameter): TWhenReturnType)|null  $default
     * @return $this|TWhenReturnType
     */
    public function when($value = null, callable $callback = null, callable $default = null)
    {
        ....
    }

Stringable->whenEmpty

    /**
     * Execute the given callback if the string is empty.
     *
     * @param  callable  $callback
     * @param  callable|null  $default
     * @return static
     */
    public function whenEmpty($callback, $default = null)
    {
        return $this->when($this->isEmpty(), $callback, $default);
    }

This is a tad annoying in IDEs which use these type declarations as they flag, but it is also misleading as it could be interpreted to mean the stringable "when..." function always returns the Stringable instance rather than the result of the callback.

In other places in Laravel, such as Illuminate\Support\Traits\EnumeratesValues (as used by Illuminate\Support\Arr) "when..." functions, such as "whenEmpty", also return the result of the Conditionable "when" function, but their docblocks match its return types.

EnumeratesValues->whenEmpty

    /**
     * Apply the callback if the collection is empty.
     *
     * @template TWhenEmptyReturnType
     *
     * @param  (callable($this): TWhenEmptyReturnType)  $callback
     * @param  (callable($this): TWhenEmptyReturnType)|null  $default
     * @return $this|TWhenEmptyReturnType
     */
    public function whenEmpty(callable $callback, callable $default = null)
    {
        return $this->when($this->isEmpty(), $callback, $default);
    }

Does anyone know why the Stringable class's "when..." functions might be written differently? Is there some non-obvious justification? Or is this likely a copy-paste mistake when the docblocks were written?

TIA