[9.x] Chained forwarding

[michael-rubel]

About

This PR introduces a new version of LEC package with code niceties and new features.

Instead of relying on the naming conventions, we can now explicitly define the classes we want to forward, and much to say, we can now chain it. 🔥

How it works?

We can enable the forwarding and define which class to assign in case of missing methods or properties in the base class.

Define the forwarding:

Forwarding::enable()
    ->from(UserService::class)
    ->to(UserRepository::class)
    ->from(UserRepository::class)
    ->to(UserModel::class);

Make a proxy:

$proxy = call(UserService::class);

Call an existing method:

$proxy->existingMethod();

// Returns result from the `UserService::class`

Call a non-existing method:

$proxy->nonExistingMethod();

// Returns result from the `UserRepository::class`, because of forwarding defined above.

Call a non-existing method, but that doesn't exist also in UserRepository::class:

$proxy->nonExistingInRepositoryMethod();

// Returns result from the `UserModel::class`, because of chained forwarding.

So, why?

• In the first call, we received the result from UserService, because the method exists and it is expected.
• In the next call, the proxy managed to replace the internal call instance with UserRepository, because of the forwarding defined before.
• In the final call, the proxy swapped the internal instance to UserModel, because the method also missing in UserRepository (previous instance).

Use cases?

Still, I'm too lazy to think where to put a query. I may do that in the model, but then move it to the service if additional logic arrives. Then all calls stay untouched. I can manage forwardings at any time and without relying on naming conventions. Separation of concerns matters. 🙂

Caveats

Always take attention to which call instance you are working currently when calling methods, accessing, or assigning properties. If some of them don't exist, the proxy will swap an instance and you'll lose the internal state. I'm thinking about storing a previous instance or warning a developer in such a case, we'll see if it fits reality.

[michael-rubel]

Property assignment forwarding is removed, cause it doesn't make much sense to forward that. If you need to perform a property assignment, just create a new instance of CallProxy. If you'll try to interact with the same property after a state swap, the exception will be thrown to avoid working on an unexpected instance which I believe improves the developer experience.

Forwarding::enable()
    ->from(UserService::class)
    ->to(UserRepository::class);

$proxy = call(UserService::class);

$proxy->property = true; // `UserService::class`
$proxy->property; // Returns `true`

$proxy->methodMissingInServiceButExistInRepository(); // `UserRepository::class`.
$proxy->property; // `InstanceInteractionException` is thrown.