> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Contracts

> Erläutert die Rolle der Laravel-Contracts, den Unterschied zu Facades, die Injektion per Type-Hint sowie das Erstellen eigener Contracts.

## Was ist ein Contract?

Die „Contracts" von Laravel sind ein Satz von Interfaces, die die Kernservices des Frameworks definieren. So beschreibt zum Beispiel der Contract `Illuminate\Contracts\Queue\Queue` die Methoden, die zum Einreihen von Jobs benötigt werden, und `Illuminate\Contracts\Mail\Mailer` die Methoden zum Versenden von E-Mails.

Für jeden Contract existiert eine entsprechende Implementierung im Framework. Laravel bringt beispielsweise Queue-Implementierungen für verschiedene Treiber sowie einen Mailer auf Basis des [Symfony Mailers](https://symfony.com/doc/current/mailer.html) mit.

Alle Laravel-Contracts liegen in einem [eigenen GitHub-Repository](https://github.com/illuminate/contracts). Dieses dient als Schnellreferenz für alle verfügbaren Contracts und stellt ein einzelnes, entkoppeltes Paket dar, das Sie bei der Entwicklung von Paketen für die Zusammenarbeit mit Laravel-Services verwenden können.

<Info>
  Ein Contract ist nichts anderes als ein Interface. Er funktioniert exakt wie ein normales PHP-Interface. Laravel liefert die Implementierung dazu und injiziert sie über den Service Container.
</Info>

## Unterschied zwischen Contract und Facade

[Facades](/de/facades) und Helferfunktionen bieten einen bequemen Zugriff auf Laravel-Services, ohne dass Sie Contracts aus dem Service Container per Type-Hint auflösen müssen. In den meisten Fällen gibt es zu jeder Facade einen passenden Contract.

Die wichtigsten Unterschiede zwischen Facades und Contracts:

| Aspekt                       | Facade                                   | Contract                                             |
| ---------------------------- | ---------------------------------------- | ---------------------------------------------------- |
| Deklaration der Abhängigkeit | Nicht nötig (überall aufrufbar)          | Explizit im Konstruktor                              |
| Testen                       | Mit `shouldReceive()` mocken             | Mit üblichen Mocking-Bibliotheken ersetzen           |
| Typischer Einsatz            | Einfache Nutzung innerhalb der Anwendung | Paketentwicklung, explizites Abhängigkeitsmanagement |
| Lesbarkeit                   | Ein Import genügt                        | Abhängigkeiten sofort im Konstruktor sichtbar        |

<Tip>
  Facades müssen im Konstruktor nicht angefordert werden, während Contracts als explizite Abhängigkeit im Konstruktor definiert werden können. Manche Entwicklerinnen und Entwickler bevorzugen dieses explizite Definieren von Abhängigkeiten und setzen daher auf Contracts. Andere schätzen den Komfort der Facades. **Für die meisten Anwendungen sind Facades in der Entwicklung problemlos ausreichend.**
</Tip>

## Wann sollten Sie Contracts einsetzen?

Ob Contract oder Facade – das ist eine Frage des persönlichen Stils bzw. der Teamvorlieben. Beide Ansätze ermöglichen robuste, testbare Laravel-Anwendungen. Contracts und Facades schließen sich nicht aus. Sie können in einem Teil der Anwendung Facades verwenden und in einem anderen auf Contracts setzen.

Besonders sinnvoll sind Contracts in folgenden Fällen:

* **Wenn Sie ein Paket entwickeln, das mit mehreren PHP-Frameworks zusammenarbeitet** – über das Paket `illuminate/contracts` können Sie die Interaktion mit Laravel-Services definieren, ohne in Ihrer `composer.json` konkrete Laravel-Implementierungen zu fordern.
* **Wenn Sie Abhängigkeiten explizit machen möchten** – anhand des Konstruktors ist auf einen Blick ersichtlich, wovon eine Klasse abhängt.
* **Wenn Sie Implementierungen austauschen möchten** – der Wechsel zu einer anderen Implementierung über den Service Container gelingt so besonders einfach.

## Verwendung von Contracts

Wie bekommen Sie eine Contract-Implementierung? Ganz einfach.

Viele Klassenarten in Laravel – Controller, Event Listener, Middleware, Queue-Jobs, Route-Closures – werden über den Service Container aufgelöst. Um eine Contract-Implementierung zu erhalten, geben Sie das Interface einfach als Type-Hint im Konstruktor der jeweiligen Klasse an.

```mermaid theme={null}
flowchart LR
    A["Service Provider<br>bind(Interface, Impl)"] --> B["Service Container<br>Bindung registriert"]
    C["Konstruktor<br>Type-Hint: Interface"] --> B
    B --> D["Automatische Injektion<br>Interface wird aufgelöst"]
    D --> E["Instanz der konkreten Klasse<br>austauschbar"]
```

Sehen Sie sich zum Beispiel den folgenden Event Listener an.

```php theme={null}
<?php

namespace App\Listeners;

use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;

class CacheOrderInformation
{
    /**
     * Erstelle den Event Listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Verarbeite das Event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}
```

Wird der Event Listener aufgelöst, liest der Service Container die Type-Hints des Konstruktors aus und injiziert passende Werte.

## Eigene Contracts erstellen

Mit eigenen Contracts können Sie die Abhängigkeiten zwischen den Bestandteilen Ihrer Anwendung klar herausarbeiten.

<Steps>
  <Step title="Interface definieren">
    Legen Sie im Verzeichnis `app/Contracts` ein Interface an.

    ```php theme={null}
    <?php

    namespace App\Contracts;

    interface PaymentGateway
    {
        /**
         * Den angegebenen Betrag belasten.
         */
        public function charge(int $amount, string $token): bool;

        /**
         * Eine Zahlung erstatten.
         */
        public function refund(string $transactionId): bool;
    }
    ```
  </Step>

  <Step title="Implementierungsklasse erstellen">
    Erstellen Sie eine Klasse, die den Contract implementiert.

    ```php theme={null}
    <?php

    namespace App\Services;

    use App\Contracts\PaymentGateway;

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

        public function refund(string $transactionId): bool
        {
            // Erstattung über die Stripe-API ...
            return true;
        }
    }
    ```
  </Step>

  <Step title="Im Service Provider binden">
    Verknüpfen Sie Contract und Implementierung in einem [Service Provider](/de/service-providers).

    ```php theme={null}
    use App\Contracts\PaymentGateway;
    use App\Services\StripePaymentGateway;

    $this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);
    ```
  </Step>

  <Step title="Per Type-Hint injizieren lassen">
    Geben Sie den Contract im Konstruktor eines Controllers oder einer anderen Klasse als Type-Hint an.

    ```php theme={null}
    <?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
            );

            // ...
        }
    }
    ```
  </Step>
</Steps>

Wollen Sie den Zahlungsdienstleister später von `Stripe` auf einen anderen Anbieter umstellen, genügt eine Anpassung an einer einzigen Stelle – der Bindung. Die Controller-Logik bleibt unverändert.

## Übersicht wichtiger Contracts

Ausschnitt einer Zuordnung häufig genutzter Contracts zu ihren Facades:

| Contract                                        | Facade                |
| ----------------------------------------------- | --------------------- |
| `Illuminate\Contracts\Auth\Access\Gate`         | `Gate`                |
| `Illuminate\Contracts\Auth\Factory`             | `Auth`                |
| `Illuminate\Contracts\Bus\Dispatcher`           | `Bus`                 |
| `Illuminate\Contracts\Cache\Factory`            | `Cache`               |
| `Illuminate\Contracts\Cache\Repository`         | `Cache::driver()`     |
| `Illuminate\Contracts\Config\Repository`        | `Config`              |
| `Illuminate\Contracts\Console\Kernel`           | `Artisan`             |
| `Illuminate\Contracts\Container\Container`      | `App`                 |
| `Illuminate\Contracts\Encryption\Encrypter`     | `Crypt`               |
| `Illuminate\Contracts\Events\Dispatcher`        | `Event`               |
| `Illuminate\Contracts\Filesystem\Factory`       | `Storage`             |
| `Illuminate\Contracts\Filesystem\Filesystem`    | `Storage::disk()`     |
| `Illuminate\Contracts\Hashing\Hasher`           | `Hash`                |
| `Illuminate\Contracts\Mail\Mailer`              | `Mail`                |
| `Illuminate\Contracts\Notifications\Dispatcher` | `Notification`        |
| `Illuminate\Contracts\Queue\Factory`            | `Queue`               |
| `Illuminate\Contracts\Queue\Queue`              | `Queue::connection()` |
| `Illuminate\Contracts\Queue\ShouldQueue`        | —                     |
| `Illuminate\Contracts\Redis\Factory`            | `Redis`               |
| `Illuminate\Contracts\Routing\ResponseFactory`  | `Response`            |
| `Illuminate\Contracts\Routing\UrlGenerator`     | `URL`                 |
| `Illuminate\Contracts\Session\Session`          | `Session::driver()`   |
| `Illuminate\Contracts\Translation\Translator`   | `Lang`                |
| `Illuminate\Contracts\Validation\Factory`       | `Validator`           |
| `Illuminate\Contracts\View\Factory`             | `View`                |

Eine vollständige Übersicht aller Contracts finden Sie im Repository [illuminate/contracts](https://github.com/illuminate/contracts).

## Nächste Schritte

<Card title="Facades" icon="layer-group" href="/de/facades">
  Vertiefen Sie die Funktionsweise von Facades und wie Sie sie testen.
</Card>


## Related topics

- [Support Contracts (Arrayable / Jsonable / Htmlable / Responsable)](/de/advanced/support-contracts.md)
- [Einen eigenen Provider für das AI SDK erstellen](/de/advanced/ai-sdk-custom-provider.md)
- [Upgrade von Laravel 10 auf 11](/de/blog/upgrade-10-to-11.md)
- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)
- [Upgrade-Anleitung von Laravel 12 auf 13](/de/blog/upgrade-12-to-13.md)