Service container

Explica el mecanismo de inyección de dependencias del service container de Laravel y los fundamentos de los bindings.

​

Qué es el service container

El service container de Laravel es el mecanismo para gestionar las dependencias de las clases y realizar la inyección de dependencias. Inyectar dependencias significa «inyectar» en la clase las dependencias que necesita a través del constructor o, en algunos casos, mediante métodos setter.

Fíjate en el siguiente ejemplo.

<?php

namespace App\Http\Controllers;

use App\Services\AppleMusic;
use Illuminate\View\View;

class PodcastController extends Controller
{
    /**
     * Crea una nueva instancia del controlador
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * Muestra la información del podcast indicado
     */
    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

En este ejemplo, PodcastController necesita obtener podcasts desde una fuente de datos como Apple Music. Por eso inyectamos un servicio capaz de obtener podcasts. Al inyectarlo, en las pruebas podemos sustituir con facilidad AppleMusic por un mock (una implementación falsa).

Entender el service container en profundidad es imprescindible para construir aplicaciones Laravel grandes. También ayuda a contribuir al propio núcleo de Laravel.

​

Resolución sin configuración

Si tu clase solo depende de otras clases concretas (no de interfaces), no necesitas indicarle al container cómo resolverlas. Por ejemplo, imagina que escribes el siguiente código en routes/web.php.

<?php

class Service
{
    // ...
}

Route::get('/', function (Service $service) {
    dd($service::class);
});

Este ejemplo define la clase dentro del archivo de rutas con fines de demostración. En una aplicación real, define las clases de servicio en el directorio app/Services.

Al acceder a esta ruta, Laravel resuelve automáticamente la clase Service y la inyecta en el handler. No hace falta preparar ningún archivo de configuración para beneficiarse de la inyección de dependencias.

En la mayoría de las clases que escribes en una aplicación Laravel —controladores, listeners de eventos, middlewares, etc.—, las dependencias se inyectan automáticamente a través del container.

​

Bindings

​

Bindings básicos

La mayoría de los bindings se registran en los service providers. Dentro de un service provider puedes acceder al container mediante la propiedad $this->app.

​

bind

Con el método bind registras un binding pasando el nombre de una clase o interfaz y un closure.

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->bind(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

El closure puede recibir el propio container como argumento. Puedes usarlo para resolver sub-dependencias.

Si necesitas manipular el container fuera de un service provider, usa la fachada App.

use App\Services\Transistor;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\App;

App::bind(Transistor::class, function (Application $app) {
    // ...
});

Las clases que no dependen de una interfaz no necesitan registrarse en el container. El container puede resolverlas automáticamente usando reflection.

​

singleton

El método singleton vincula la clase o interfaz de modo que se resuelva una sola vez. Una vez resuelto el singleton, todas las llamadas posteriores al container devuelven la misma instancia.

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->singleton(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

Con singletonIf puedes registrar el binding singleton solo si aún no existe uno para el tipo indicado.

$this->app->singletonIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

​

Atributo Singleton

Puedes indicarle al container que la clase o interfaz debe resolverse una sola vez añadiendo el atributo #[Singleton].

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

#[Singleton]
class Transistor
{
    // ...
}

​

Bindings de singleton con scope

El método scoped vincula la clase o interfaz para que se resuelva una sola vez dentro del ciclo de vida de la petición/job de Laravel. Es similar a singleton, pero las instancias registradas con scoped se descartan cada vez que la aplicación Laravel inicia un nuevo «ciclo de vida», como cuando un worker de Laravel Octane atiende una nueva petición o cuando un worker de cola procesa un nuevo job.

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->scoped(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

Con scopedIf puedes registrar el binding con scope solo si aún no existe uno para el tipo indicado.

$this->app->scopedIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

​

Atributo Scoped

También puedes indicarle al container que resuelva una sola vez por ciclo de petición/job añadiendo el atributo #[Scoped].

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

#[Scoped]
class Transistor
{
    // ...
}

​

instance

También puedes vincular al container una instancia de objeto ya existente con el método instance. En las llamadas posteriores al container se devolverá siempre esa instancia.

use App\Services\Transistor;
use App\Services\PodcastParser;

$service = new Transistor(new PodcastParser);

$this->app->instance(Transistor::class, $service);

​

Vincular una interfaz a una implementación

Una de las funcionalidades más potentes del service container es la posibilidad de vincular una interfaz a una implementación concreta. Por ejemplo, imagina que tienes la interfaz EventPusher y la implementación RedisEventPusher.

use App\Contracts\EventPusher;
use App\Services\RedisEventPusher;

$this->app->bind(EventPusher::class, RedisEventPusher::class);

Con esto, el container inyectará RedisEventPusher en cualquier clase que necesite una implementación de EventPusher. Basta con hacer un type hint de la interfaz EventPusher en el constructor.

use App\Contracts\EventPusher;

/**
 * Crea una nueva instancia de la clase
 */
public function __construct(
    protected EventPusher $pusher,
) {}

Al depender de interfaces, cambiar la implementación no requiere modificar el código. Esto facilita las pruebas y los cambios futuros.

​

Atributo Bind

Laravel también ofrece el útil atributo Bind. Añadiéndolo a una interfaz, indicas a Laravel qué implementación inyectar automáticamente cuando se solicita esa interfaz. Con Bind no necesitas registrar nada adicional en un service provider.

Además, colocando varios atributos Bind sobre la interfaz, puedes configurar la inyección de implementaciones distintas por entorno.

<?php

namespace App\Contracts;

use App\Services\FakeEventPusher;
use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;

#[Bind(RedisEventPusher::class)]
#[Bind(FakeEventPusher::class, environments: ['local', 'testing'])]
interface EventPusher
{
    // ...
}

Para bindings que dependan de condiciones arbitrarias puedes usar el atributo BindWhen. Al closure se le puede pasar el container y debe devolver true cuando quieras aplicar el binding. Los atributos Bind y BindWhen se evalúan en el orden en que se declaran.

use App\Services\BetaEventPusher;
use Illuminate\Container\Attributes\BindWhen;
use Laravel\Pennant\Feature;

#[BindWhen(BetaEventPusher::class, static fn () => Feature::active('beta-events'))]
interface EventPusher
{
    // ...
}

Para usar el atributo BindWhen se requiere PHP 8.5 o superior.

Además, combinándolos con los atributos Singleton o Scoped, puedes especificar que ese binding se resuelva una sola vez o una sola vez por petición/job.

use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;
use Illuminate\Container\Attributes\Singleton;

#[Bind(RedisEventPusher::class)]
#[Singleton]
interface EventPusher
{
    // ...
}

​

Resolución automática (DI por type hint)

El service container inyecta automáticamente las dependencias mirando los type hints del constructor al resolver clases como controladores, listeners de eventos o middlewares.

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Crea una nueva instancia del controlador
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

Si UserRepository no depende de una interfaz, no hay que registrarlo en el container. Basta con acceder a la ruta correspondiente y el container resolverá automáticamente la dependencia y la inyectará en el controlador.

​

Resolver desde el container

​

Método make

Con el método make puedes resolver una instancia de clase desde el container.

use App\Services\Transistor;

$transistor = app()->make(Transistor::class);

Si las dependencias de la clase no pueden resolverse en el container, con makeWith puedes pasar argumentos adicionales.

$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);

​

Inyección automática

En la práctica rara vez llamarás directamente a make. Basta con añadir type hints al constructor de las clases que resuelve el container (controladores, listeners de eventos, middlewares, etc.) y las inyectará automáticamente.

​

Relación entre fachadas y container

Las fachadas de Laravel ofrecen una interfaz estática a los objetos dentro del container. Por ejemplo, Cache::get() internamente obtiene el servicio Cache desde el container y lo invoca.

use Illuminate\Support\Facades\Cache;

// Llamada usando la fachada
Cache::get('key');

// Llamada equivalente usando directamente el container
app('cache')->get('key');

Las fachadas son envoltorios cómodos del container. En las pruebas puedes sustituir la fachada por un mock.

use Illuminate\Support\Facades\Cache;

Cache::shouldReceive('get')
    ->once()
    ->with('key')
    ->andReturn('value');

​

Ejemplo práctico de inyección por constructor

Veamos un patrón típico en una aplicación real.

1. Define la interfaz

   <?php
   
   namespace App\Contracts;
   
   interface PaymentGateway
   {
       public function charge(int $amount, string $token): bool;
   }
   
2. Crea la clase de implementación

   <?php
   
   namespace App\Services;
   
   use App\Contracts\PaymentGateway;
   
   class StripePaymentGateway implements PaymentGateway
   {
       public function charge(int $amount, string $token): bool
       {
           // Procesamiento del pago usando la API de Stripe...
           return true;
       }
   }
   
3. Vincúlala en el service provider

   use App\Contracts\PaymentGateway;
   use App\Services\StripePaymentGateway;
   
   $this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
   
4. Recibe la inyección en el controlador

   <?php
   
   namespace App\Http\Controllers;
   
   use App\Contracts\PaymentGateway;
   use Illuminate\Http\Request;
   
   class OrderController extends Controller
   {
       public function __construct(
           protected PaymentGateway $payment,
       ) {}
   
       public function store(Request $request)
       {
           $this->payment->charge(
               $request->amount,
               $request->payment_token
           );
   
           // ...
       }
   }
   

Con este patrón, cambiar el servicio de pago de Stripe a otro proveedor requiere modificar un solo binding.

​

Próximos pasos

Service providers

Aprende a registrar bindings mediante service providers.