[8.x] Add forwardDecoratedCallTo

[inxilpro]

This PR adds an additional method to ForwardsCalls to allow for easy fluent calls to decorated objects. This pattern is used in the Relation class as well as in the DecoratesQueryBuilder trait that will be introduced in Laravel 9. Under the hood, this essentially performs:

public function __call($method, $parameters)
{
  $result = $this->forwardCallTo($this->decorated, $method, $parameters);

  // If the underlying call was fluent, make this call fluent as well
  if ($result === $this->decorated) {
    return $this;
  }

  return $result;
}

This is a nice solution, because we continue to receive our proxy object until we make a call that isn't fluent on the underlying decorated object.

There are a handful of places that could be updated to use this new method. Because these are mild breaking changes, I'll introduce them in 9.x PR should this PR get merged. These are:

• Illuminate\Events\NullDispatcher
• Illuminate\Http\Resources\DelegatesToResource
• Illuminate\Mail\Message
• Illuminate\Pagination\AbstractPaginator and AbstractCursorPaginator

In each of these cases, I believe the expected behavior of any delegated fluent call would be to receive the proxy object, whereas right now you would receive the underlying object.

For example, in the case of Illuminate\Mail\Message:

// Works because you happen to call from() first
$message->from('[email protected]')->addPart('hello', 'text/plain');

// Fails because you call from() second, and `addPart()` returned the underlying Swift_Message
$message->addPart('hello', 'text/plain')->from('[email protected]');

[macropay-solutions]

@inxilpro Is there a reason this did not made it also into the eloquent builder? see #56664

[inxilpro]

@inxilpro Is there a reason this did not made it also into the eloquent builder? see #56664

Ultimately Taylor decided it was too big a change.

[macropay-solutions]

@inxilpro we opened a discussion here #56680

[macropay-solutions]

@inxilpro

        if (in_array($method, $this->passthru)) {
            return $this->toBase()->{$method}(...$parameters); // toBase is applying scopes
        }

        $this->forwardCallTo($this->query, $method, $parameters); // no scopes

Maybe the scopes were the reason here...
For "terminal/final/non-chaining" functions the scopes are applied while for where etc they should not.

#56680 (reply in thread)