This mechanism allows you to define how any implementations registered in the future should be initialized.
For example: Imagine that you had a RPC client that connects to some server based on configuration files. And you would want any client code to be able to extend your Client class and register their own implementations, but without burdening them with having to initialize the client with the input from the settings file manually. (By "client code" we mean any code that would use your library, the term "client" is confusing here.)
(I wanted to do a similar thing in my Laravel project because I wanted to define the path to my config (the rpc.client) only once and not every time that I register different Client implementation. I did not want the rest of the application to care about such things).
Example implementation:
class CommunicationsServiceProvider extends ServiceProvider
{
/**
* Register the application services.
*
* @return void
*/
public function register()
{
$this->app->singleton(ClientInterface::class, function(Application $app)
{
return null; // Required to trigger the rebinding event with the second bind.
});
$this->app->rebinding(ClientInterface::class, function(Application $app, $client)
{
$options = $app['config']->get('rpc.client');
/** @var Client $client */
$client->configure($options);
return $client;
});
$this->app->singleton(ClientInterface::class, function(Application $app)
{
$client = new Client ([]); // We intentionally use empty array to demonstrate
// that the config will be properly injected anyway.
return $client;
});
// Note that the callback in the binding() method will be called, so even though
// we initialize the new Client with empty set of settings (we provide the [] into
// the constructor), it will be properly initialized by the rebinding() callback.
So every time anyone registers a new Client implementation (via App::bind()
etc.) the callback defined in rebinding() will be called on the instance.
Conclusion
What I wonder about thought is whether it is a good idea to use the rebinding()
method at all when it is not documented in Laravel docs and is not part of the Container contract (the Illuminate\Contracts\Container\Container
interface) and is only a part of the concrete implementation (the Illuminate\Container\Container
class ).
It seems that for the same usecase you could use the "proper" (documented and present in public API) resolving()
method, which will cause the configure($options)
method to be called every time someone resolves this binding (contrary to this case where it is only called once—when the Client is registered).
Sources
I have first noted this functionality in this tutorial, but honestly I did not properly understand it from the example there and had to experiment with it on my own.
Disclaimer
Please note that I am by no stretches of imagination an expert on this topic. But I have currently been looking into the Laravel IoC and this method so I thought that I might provide some insight.