Contrats - Knowledge of Laravel

Qu’est-ce qu’un contrat

Les « Contracts » de Laravel sont un ensemble d’interfaces qui définissent les services centraux fournis par le framework. Par exemple, le contrat Illuminate\Contracts\Queue\Queue définit les méthodes nécessaires pour mettre en file d’attente des jobs, et Illuminate\Contracts\Mail\Mailer définit les méthodes nécessaires pour envoyer des e-mails. Chaque contrat possède une implémentation fournie par le framework. Par exemple, Laravel fournit des implémentations de file pour divers drivers, et un mailer basé sur Symfony Mailer. Tous les contrats Laravel se trouvent dans un dépôt GitHub dédié. Ce dépôt sert de référence rapide aux contrats disponibles et constitue un package isolé utilisable pour construire des packages qui s’intègrent aux services Laravel.

Un contrat n’est qu’une interface. Il fonctionne comme n’importe quelle interface PHP. Laravel fournit une implémentation et l’injecte via le conteneur de services.

Différences entre contrat et façade

Les façades et les fonctions helper permettent d’utiliser facilement les services Laravel sans devoir résoudre un contrat via un type-hint. Dans la plupart des cas, à chaque façade correspond un contrat. Différences majeures :

Aspect	Façade	Contrat
Déclaration de dépendance	Inutile (appelable partout)	Déclarée explicitement dans le constructeur
Tests	Mock via `shouldReceive()`	Remplacement via une bibliothèque de mock standard
Usage principal	Utilisation pratique dans l’application	Développement de packages, gestion explicite des dépendances
Lisibilité	Importation en une ligne	Dépendances visibles dans le constructeur

Les façades n’ont pas besoin d’être déclarées dans le constructeur, alors que les contrats se déclarent explicitement comme dépendances. Certains développeurs préfèrent cette déclaration explicite et utilisent les contrats. D’autres apprécient la commodité des façades. En général, les façades conviennent à la plupart des applications sans problème.

Quand utiliser un contrat

Le choix entre contrats et façades relève de la préférence personnelle ou d’équipe. Les deux permettent d’écrire des applications Laravel robustes et testables. Ils ne s’excluent pas : vous pouvez utiliser les façades dans certaines parties et les contrats dans d’autres. Les contrats sont particulièrement utiles pour :

Construire un package qui s’intègre à plusieurs frameworks PHP — en utilisant le package illuminate/contracts, vous définissez l’intégration avec les services Laravel sans exiger une implémentation concrète dans composer.json.
Rendre explicites les dépendances — regarder le constructeur suffit à voir de quoi la classe dépend.
Remplacer une implémentation — le remplacement via le conteneur de services devient très simple.

Utiliser un contrat

Comment récupérer l’implémentation d’un contrat ? C’est très simple. Contrôleurs, listeners, middlewares, jobs de queue, closures de routes… de nombreux types de classes Laravel sont résolus via le conteneur. Pour obtenir l’implémentation d’un contrat, il suffit de le « type-hinter » dans le constructeur de la classe. Par exemple, ce listener :

<?php

namespace App\Listeners;

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

class CacheOrderInformation
{
    /**
     * Crée un nouveau listener.
     */
    public function __construct(
        protected Factory $redis,
    ) {}

    /**
     * Traite l'événement.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

Lorsque le listener est résolu, le conteneur lit les type-hints du constructeur et injecte la valeur appropriée.

Créer un contrat personnalisé

Créer vos propres contrats clarifie les dépendances entre composants.

Définir l'interface

Créez l’interface dans app/Contracts.

<?php

namespace App\Contracts;

interface PaymentGateway
{
    /**
     * Débite le montant donné.
     */
    public function charge(int $amount, string $token): bool;

    /**
     * Rembourse le paiement.
     */
    public function refund(string $transactionId): bool;
}

Créer une implémentation

Créez la classe qui implémente le contrat.

<?php

namespace App\Services;

use App\Contracts\PaymentGateway;

class StripePaymentGateway implements PaymentGateway
{
    public function charge(int $amount, string $token): bool
    {
        // Traitement du paiement via l'API Stripe...
        return true;
    }

    public function refund(string $transactionId): bool
    {
        // Traitement du remboursement via l'API Stripe...
        return true;
    }
}

Enregistrer le binding dans un service provider

Reliez le contrat à son implémentation dans un service provider.

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

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

Recevoir l'injection via type-hint

Utilisez le type-hint dans le constructeur d’un contrôleur ou d’une autre classe.

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

        // ...
    }
}

Grâce à ce pattern, changer de fournisseur (Stripe vers un autre) revient à modifier un seul binding — sans toucher au contrôleur.

Principaux contrats

Contrats fréquents et leurs façades correspondantes (extrait).

Contrat	Façade correspondante
`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`

La liste complète est disponible dans le dépôt illuminate/contracts.

Prochaines étapes

Façades

Revenez sur le fonctionnement et les tests des façades.

​Qu’est-ce qu’un contrat

​Différences entre contrat et façade

​Quand utiliser un contrat

​Utiliser un contrat

​Créer un contrat personnalisé

​Principaux contrats

​Prochaines étapes

Façades

Qu’est-ce qu’un contrat

Différences entre contrat et façade

Quand utiliser un contrat

Utiliser un contrat

Créer un contrat personnalisé

Principaux contrats

Prochaines étapes