Service-Container - Knowledge of Laravel

Was ist der Service-Container

Der Service-Container von Laravel ist ein Mechanismus zur Verwaltung von Klassenabhängigkeiten und zur Durchführung von Dependency Injection. Dependency Injection bedeutet, dass die von einer Klasse benötigten Abhängigkeiten über den Konstruktor oder gegebenenfalls über Setter-Methoden in die Klasse „injiziert” werden. Sehen Sie sich das folgende Beispiel an:

<?php

namespace App\Http\Controllers;

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

class PodcastController extends Controller
{
    /**
     * Neue Controller-Instanz erzeugen
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * Informationen zum angegebenen Podcast anzeigen
     */
    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

In diesem Beispiel muss der PodcastController einen Podcast von einer Datenquelle wie Apple Music beziehen. Dazu wird ein Dienst injiziert, der Podcasts abrufen kann. Durch das Injizieren des Dienstes lässt sich beim Testen ein Mock (eine Dummy-Implementierung) des AppleMusic-Dienstes leicht einsetzen.

Ein tiefes Verständnis des Service-Containers ist beim Aufbau großer Laravel-Anwendungen unerlässlich. Es hilft auch dabei, zum Laravel-Core selbst beizutragen.

Zero-Configuration-Auflösung

Wenn eine Klasse nur von anderen konkreten Klassen (keinen Interfaces) abhängt, müssen Sie dem Container nicht mitteilen, wie sie aufzulösen ist. Nehmen Sie zum Beispiel folgenden Code in routes/web.php an:

<?php

class Service
{
    // ...
}

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

In diesem Beispiel wird die Klasse innerhalb der Routendatei definiert – dies dient nur zu Demonstrationszwecken. In einer echten Anwendung sollten Service-Klassen im Verzeichnis app/Services definiert werden.

Beim Aufruf dieser Route löst Laravel die Service-Klasse automatisch auf und injiziert sie in den Route-Handler. Sie profitieren also von Dependency Injection, ohne eine Konfigurationsdatei anlegen zu müssen. Bei vielen Klassen, die Sie in einer Laravel-Anwendung schreiben – etwa Controller, Event-Listener oder Middleware – werden Abhängigkeiten automatisch über den Container injiziert.

Bindings

Einfache Bindings

Die meisten Bindings werden innerhalb von Service-Providern registriert. In einem Service-Provider können Sie über die Eigenschaft $this->app auf den Container zugreifen.

bind

Mit der bind-Methode registrieren Sie ein Binding, indem Sie einen Klassen- oder Interface-Namen zusammen mit einer Closure übergeben:

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));
});

Die Closure erhält als Argument den Container selbst und kann darüber Unterabhängigkeiten auflösen. Wenn Sie den Container außerhalb eines Service-Providers verwenden möchten, nutzen Sie die App-Fassade:

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

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

Klassen, die nicht von einem Interface abhängen, müssen nicht an den Container gebunden werden. Der Container kann solche Objekte automatisch über Reflection auflösen.

singleton

Die singleton-Methode bindet eine Klasse oder ein Interface so, dass sie nur ein einziges Mal aufgelöst wird. Ist ein Singleton einmal aufgelöst, gibt der Container bei jedem weiteren Aufruf dieselbe Instanz zurück.

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));
});

Mit der singletonIf-Methode registrieren Sie ein Singleton-Binding nur dann, wenn für den angegebenen Typ noch kein Binding registriert wurde.

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

Singleton-Attribut

Alternativ können Sie eine Klasse oder ein Interface mit dem Attribut #[Singleton] versehen, um dem Container mitzuteilen, dass sie nur ein einziges Mal aufgelöst werden soll.

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

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

Scoped Singletons binden

Die scoped-Methode bindet eine Klasse oder ein Interface so, dass sie innerhalb eines Laravel-Request-/Job-Lebenszyklus nur ein einziges Mal aufgelöst wird. Sie ähnelt der singleton-Methode, allerdings werden mit scoped registrierte Instanzen jedes Mal verworfen, wenn die Laravel-Anwendung einen neuen „Lebenszyklus” beginnt – etwa wenn ein Laravel Octane-Worker einen neuen Request verarbeitet oder ein Queue-Worker einen neuen Job bearbeitet.

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));
});

Mit der scopedIf-Methode registrieren Sie ein Scoped-Binding nur dann, wenn für den angegebenen Typ noch kein Binding registriert wurde.

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

Scoped-Attribut

Alternativ können Sie eine Klasse oder ein Interface mit dem Attribut #[Scoped] versehen, um dem Container mitzuteilen, dass sie innerhalb eines Request-/Job-Lebenszyklus nur ein einziges Mal aufgelöst werden soll.

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

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

instance

Eine bereits existierende Objektinstanz können Sie über die instance-Methode an den Container binden. Bei nachfolgenden Aufrufen des Containers wird stets diese Instanz zurückgegeben.

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

$service = new Transistor(new PodcastParser);

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

Interfaces an Implementierungen binden

Eine der leistungsstärksten Funktionen des Service-Containers ist die Möglichkeit, ein Interface an eine bestimmte Implementierung zu binden. Angenommen, es existiert das Interface EventPusher und die Implementierung RedisEventPusher:

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

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

Dadurch injiziert der Container in jede Klasse, die eine Implementierung von EventPusher benötigt, den RedisEventPusher. Sie müssen dann lediglich das Interface EventPusher als Type-Hint im Konstruktor angeben:

use App\Contracts\EventPusher;

/**
 * Neue Klasseninstanz erzeugen
 */
public function __construct(
    protected EventPusher $pusher,
) {}

Wenn Sie von Interfaces abhängen, müssen Sie Ihren Code nicht anpassen, wenn Sie die Implementierung austauschen. Das erleichtert das Testen und spätere Änderungen erheblich.

Bind-Attribut

Laravel bietet außerdem das praktische Bind-Attribut. Indem Sie ein Interface mit diesem Attribut versehen, teilen Sie Laravel mit, welche Implementierung automatisch injiziert werden soll, wenn dieses Interface angefordert wird. Bei Verwendung des Bind-Attributs ist keine zusätzliche Registrierung in einem Service-Provider erforderlich. Darüber hinaus können Sie mehrere Bind-Attribute auf einem Interface platzieren, um je nach Umgebung unterschiedliche Implementierungen injizieren zu lassen.

<?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
{
    // ...
}

Für Bindings, die von einer beliebigen Bedingung abhängen, können Sie das BindWhen-Attribut verwenden. Der Closure kann der Container übergeben werden, und sie gibt true zurück, wenn das Binding angewendet werden soll. Die Attribute Bind und BindWhen werden in der Reihenfolge ihrer Deklaration ausgewertet.

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

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

Das BindWhen-Attribut erfordert PHP 8.5 oder höher.

In Kombination mit dem Singleton- oder Scoped-Attribut können Sie außerdem festlegen, ob das Container-Binding nur ein einziges Mal oder einmal pro Request/Job aufgelöst werden soll.

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

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

Kontextuelle Bindings

Manchmal möchten Sie zwei Klassen, die dasselbe Interface verwenden, jeweils unterschiedliche Implementierungen injizieren. Nehmen Sie etwa an, zwei Controller hängen von unterschiedlichen Implementierungen des Contracts Illuminate\Contracts\Filesystem\Filesystem ab. Laravel stellt für die Definition dieses Verhaltens eine einfache, fluent Schnittstelle bereit.

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\UploadController;
use App\Http\Controllers\VideoController;
use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Support\Facades\Storage;

$this->app->when(PhotoController::class)
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('local');
    });

$this->app->when([VideoController::class, UploadController::class])
    ->needs(Filesystem::class)
    ->give(function () {
        return Storage::disk('s3');
    });

An when() können Sie eine Klasse oder ein Array von Klassen übergeben. Mit needs() geben Sie das Zielinterface an, mit give() die Closure, die zur Auflösung verwendet wird. Auf diese Weise können Sie – auch wenn dasselbe Filesystem-Interface per Type-Hint angegeben ist – pro Controller unterschiedliche Disks injizieren.

Kontextuelle Attribute

Da kontextuelle Bindings häufig verwendet werden, um Treiber- oder Konfigurationsimplementierungen zu injizieren, stellt Laravel verschiedene Kontext-Attribute bereit, damit Sie kontextuelle Bindings nicht manuell in einem Service-Provider definieren müssen. Zum Beispiel können Sie mit dem Storage-Attribut eine bestimmte Storage-Disk injizieren.

<?php

namespace App\Http\Controllers;

use Illuminate\Container\Attributes\Storage;
use Illuminate\Contracts\Filesystem\Filesystem;

class PhotoController extends Controller
{
    public function __construct(
        #[Storage('local')] protected Filesystem $filesystem
    ) {
        // ...
    }
}

Neben dem Storage-Attribut bietet Laravel die Attribute Auth, Cache, Config, Context, DB, Give, Log, RequestAttribute, RouteParameter und Tag.

<?php

namespace App\Http\Controllers;

use App\Contracts\UserRepository;
use App\Models\Organization;
use App\Models\Photo;
use App\Repositories\DatabaseRepository;
use Illuminate\Container\Attributes\Auth;
use Illuminate\Container\Attributes\Cache;
use Illuminate\Container\Attributes\Config;
use Illuminate\Container\Attributes\Context;
use Illuminate\Container\Attributes\DB;
use Illuminate\Container\Attributes\Give;
use Illuminate\Container\Attributes\Log;
use Illuminate\Container\Attributes\RequestAttribute;
use Illuminate\Container\Attributes\RouteParameter;
use Illuminate\Container\Attributes\Tag;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Database\Connection;
use Psr\Log\LoggerInterface;

class PhotoController extends Controller
{
    public function __construct(
        #[Auth('web')] protected Guard $auth,
        #[Cache('redis')] protected Repository $cache,
        #[Config('app.timezone')] protected string $timezone,
        #[Context('uuid')] protected string $uuid,
        #[Context('ulid', hidden: true)] protected string $ulid,
        #[DB('mysql')] protected Connection $connection,
        #[Give(DatabaseRepository::class)] protected UserRepository $users,
        #[Log('daily')] protected LoggerInterface $log,
        #[RequestAttribute('organization')] protected Organization $organization,
        #[RouteParameter] protected Photo $photo,
        #[Tag('reports')] protected iterable $reports,
    ) {
        // ...
    }
}

Das Attribut RouteParameter löst den Routenparameter auf, dessen Name mit dem Namen der Eigenschaft übereinstimmt. Bei Bedarf können Sie den Namen des Routenparameters auch explizit angeben, etwa #[RouteParameter('photo')]. Das Attribut RequestAttribute löst Eingabewerte der aktuellen Request-Instanz auf. Möchten Sie einen Schlüssel referenzieren, der vom Eigenschaftsnamen abweicht, geben Sie ihn explizit an, z. B. #[RequestAttribute('user_organization')].

Das Attribut Give verwenden Sie, wenn Sie beim Auflösen eines Interfaces zu einer konkreten Klasse anstelle der gewöhnlichen automatischen Auflösung per Type-Hint eine bestimmte Implementierung angeben möchten.

Automatische Auflösung (DI per Type-Hint)

Wenn der Service-Container Klassen wie Controller, Event-Listener oder Middleware auflöst, berücksichtigt er die Type-Hints des Konstruktors und injiziert die Abhängigkeiten automatisch.

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Neue Controller-Instanz erzeugen
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

Solange UserRepository nicht von einem Interface abhängt, ist keine Registrierung im Container notwendig. Sobald die entsprechende Route aufgerufen wird, löst der Container die Abhängigkeit automatisch auf und injiziert sie in den Controller.

Auflösen aus dem Container

Methode `make`

Mit der make-Methode können Sie eine Klasseninstanz aus dem Container auflösen:

use App\Services\Transistor;

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

Falls Abhängigkeiten der Klasse nicht vom Container aufgelöst werden können, lassen sich über die Methode makeWith zusätzliche Argumente übergeben:

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

Automatische Injection

In der Praxis rufen Sie die make-Methode selten direkt auf. Bei Klassen, die vom Container aufgelöst werden – etwa Controller, Event-Listener oder Middleware – reicht es aus, Type-Hints im Konstruktor anzugeben; der Container übernimmt die Injection dann automatisch.

Fassaden und der Container

Die Fassaden von Laravel bieten eine statische Schnittstelle zu Objekten im Container. So ruft beispielsweise Cache::get() intern den Cache-Dienst aus dem Container ab und delegiert den Aufruf an ihn.

use Illuminate\Support\Facades\Cache;

// Aufruf über die Fassade
Cache::get('key');

// Äquivalenter Aufruf direkt über den Container
app('cache')->get('key');

Fassaden sind komfortable Wrapper um den Container. Beim Testen lassen sie sich außerdem durch Mocks ersetzen.

use Illuminate\Support\Facades\Cache;

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

Konstruktor-Injection – ein praktisches Beispiel

Betrachten wir ein typisches Muster aus einer realen Anwendung.

Interface definieren

<?php

namespace App\Contracts;

interface PaymentGateway
{
    public function charge(int $amount, string $token): bool;
}

Implementierung erstellen

<?php

namespace App\Services;

use App\Contracts\PaymentGateway;

class StripePaymentGateway implements PaymentGateway
{
    public function charge(int $amount, string $token): bool
    {
        // Zahlung über die Stripe-API abwickeln...
        return true;
    }
}

Im Service-Provider binden

use App\Contracts\PaymentGateway;
use App\Services\StripePaymentGateway;

$this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);

Injection im Controller entgegennehmen

<?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
        );

        // ...
    }
}

Mit diesem Muster genügt es, das Binding an einer einzigen Stelle zu ändern, wenn Sie den Zahlungsdienst zum Beispiel von Stripe auf einen anderen Anbieter umstellen möchten.

Nächste Schritte

Service-Provider

Erfahren Sie, wie Sie mit Service-Providern Bindings registrieren.

​Was ist der Service-Container

​Zero-Configuration-Auflösung

​Bindings

​Einfache Bindings

​bind

​singleton

​Singleton-Attribut

​Scoped Singletons binden

​Scoped-Attribut

​instance

​Interfaces an Implementierungen binden

​Bind-Attribut

​Kontextuelle Bindings

​Kontextuelle Attribute

​Automatische Auflösung (DI per Type-Hint)

​Auflösen aus dem Container

​Methode make

​Automatische Injection

​Fassaden und der Container

​Konstruktor-Injection – ein praktisches Beispiel

​Nächste Schritte

Service-Provider

Was ist der Service-Container

Zero-Configuration-Auflösung

Bindings

Einfache Bindings

bind

singleton

Singleton-Attribut

Scoped Singletons binden

Scoped-Attribut

instance

Interfaces an Implementierungen binden

Bind-Attribut

Kontextuelle Bindings

Kontextuelle Attribute

Automatische Auflösung (DI per Type-Hint)

Auflösen aus dem Container

Methode `make`

Automatische Injection

Fassaden und der Container

Konstruktor-Injection – ein praktisches Beispiel

Nächste Schritte