Contratos

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

Introducción

Los "contratos" de Laravel son un conjunto de interfaces que definen los servicios centrales proporcionados por el framework. Por ejemplo, un contrato Illuminate\Contracts\Queue\Queue define los métodos necesarios para encolar trabajos, 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 ofrece una implementación de cola con una variedad de controladores, y una implementación de correo que está alimentada por Symfony Mailer. Todos los contratos de Laravel viven en su propio repositorio de 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 helper de Laravel proporcionan una forma sencilla de utilizar los servicios de Laravel sin necesidad de utilizar type-hinting y resolver contratos del contenedor de servicios. En la mayoría de los casos, cada facade tiene un contrato equivalente. A diferencia de las facades, que no requieren que las incluyas en el constructor de tu clase, los contratos te permiten definir dependencias explícitas para tus clases. Algunos desarrolladores prefieren definir 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 fachadas dependerá del gusto personal y de los gustos de tu equipo de desarrollo. Tanto los contratos como las fachadas se pueden utilizar para crear aplicaciones Laravel robustas y bien probadas. Los contratos y las fachadas no son mutuamente excluyentes. Algunas partes de tus aplicaciones pueden usar fachadas mientras que otras dependen de contratos. Siempre que mantengas las responsabilidades de tu clase enfocadas, notarás muy pocas diferencias prácticas entre el uso de contratos y fachadas. En general, la mayoría de las aplicaciones pueden usar facades sin problemas durante el desarrollo. Si estás creando un paquete que se integra con múltiples frameworks PHP, es posible que desees usar el paquete illuminate/contracts para definir tu integración con los servicios de Laravel sin necesidad de requerir las implementaciones concretas de Laravel en el archivo composer.json de tu paquete.

Cómo Usar Contratos

Entonces, ¿cómo obtienes una implementación de un contrato? En realidad, es bastante simple. Many tipos de clases en Laravel se resuelven a través del contenedor de servicios, incluyendo controladores, oyentes de eventos, middleware, trabajos en cola e incluso funciones anónimas de ruta. Así que, para obtener una implementación de un contrato, solo puedes "sugerir el tipo" de la interfaz en el constructor de la clase que se está resolviendo. Por ejemplo, echa un vistazo a este listener de eventos:

<?php
 
namespace App\Listeners;
 
use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;
 
class CacheOrderInformation
{
    /**
     * Create a new event handler instance.
     */
    public function __construct(
        protected Factory $redis,
    ) {}
 
    /**
     * Handle the event.
     */
    public function handle(OrderWasPlaced $event): void
    {
        // ...
    }
}

Cuando se resuelve el listener del evento, el contenedor de servicios leerá las indicaciones de tipo en el constructor de la clase y inyectará el valor apropiado. Para aprender más sobre cómo registrar cosas en el contenedor de servicios, consulta su documentación.

Referencia de Contrato

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