Contratos

• Introducción
  • Contratos Vs. Facades
• Cuándo Usar Contratos
• Cómo Usar Contratos
• Referencia de Contratos

Introducción

Los "contratos" de Laravel son un conjunto de interfaces que definen los servicios fundamentales proporcionados por el framework. Por ejemplo, un contrato Illuminate\Contracts\Queue\Queue define los métodos necesarios para poner trabajos en cola, mientras que el contrato Illuminate\Contracts\Mail\Mailer define los métodos necesarios para enviar correos electrónicos.

Cada contrato tiene una implementación correspondiente proporcionada por el framework. Por ejemplo, Laravel proporciona una implementación de cola con una variedad de controladores y una implementación de correo que está impulsada por Symfony Mailer.

Todos los contratos de Laravel se encuentran en su propio repositorio en GitHub. Esto proporciona un punto de referencia rápido para todos los contratos disponibles, así como un paquete único y desacoplado que se puede utilizar al construir paquetes que interactúan con los servicios de Laravel.

Contratos Vs. Facades

Las facades y las funciones auxiliares de Laravel proporcionan una forma sencilla de utilizar los servicios de Laravel sin necesidad de declarar tipos y resolver contratos desde el contenedor de servicios. En la mayoría de los casos, cada facade tiene un contrato equivalente.

A diferencia de las facades, que no requieren ser declaradas en el constructor de su clase, los contratos le permiten definir dependencias explícitas para sus clases. Algunos desarrolladores prefieren definir explícitamente sus dependencias de esta manera y, por lo tanto, prefieren usar contratos, mientras que otros desarrolladores disfrutan de la conveniencia de las facades. En general, la mayoría de las aplicaciones pueden usar facades sin problemas durante el desarrollo.

Cuándo Usar Contratos

La decisión de usar contratos o facades dependerá del gusto personal y de los gustos de su equipo de desarrollo. Tanto los contratos como las facades se pueden utilizar para crear aplicaciones Laravel robustas y bien probadas. Los contratos y las facades no son mutuamente excluyentes. Algunas partes de sus aplicaciones pueden usar facades, mientras que otras dependen de contratos. Si mantiene enfocadas las responsabilidades de su clase, notará muy pocas diferencias prácticas entre el uso de contratos y facades.

En general, la mayoría de las aplicaciones pueden usar facades sin problemas durante el desarrollo. Si está construyendo un paquete que se integra con múltiples frameworks de PHP, es posible que desee utilizar el paquete illuminate/contracts para definir su integración con los servicios de Laravel sin la necesidad de requerir las implementaciones concretas de Laravel en el archivo composer.json de su paquete.

Cómo Usar Contratos

Entonces, ¿cómo obtiene una implementación de un contrato? Es bastante simple.

Muchos tipos de clases en Laravel se resuelven a través del contenedor de servicios, incluidos controladores, escuchadores de eventos, middleware, trabajos en cola e incluso cierres de rutas. Entonces, para obtener una implementación de un contrato, simplemente puede "declarar" la interfaz en el constructor de la clase que se está resolviendo.

Por ejemplo, eche un vistazo a este escuchador de eventos:

<?php
 
namespace App\Listeners;
 
use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;
 
class CacheOrderInformation
{
    /**
     * Crea una nueva instancia del controlador de eventos.
     */
    public function __construct(
        protected Factory $redis,
    ) {}
 
    /**
     * Maneja el evento.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

Cuando se resuelve el escuchador de eventos, el contenedor de servicios leerá las declaraciones de tipos en el constructor de la clase e inyectará el valor apropiado. Para obtener más información sobre cómo registrar cosas en el contenedor de servicios, consulte su documentación.

Referencia de Contratos

Esta tabla proporciona una referencia rápida de todos los contratos de Laravel y sus facades equivalentes: