Contratos
Introdução
Os "contratos" do Laravel são um conjunto de interfaces que definem os principais serviços oferecidos pelo framework. Por exemplo, um contrato Illuminate\Contracts\Queue\Queue define os métodos necessários para o agendamento de tarefas em filas, enquanto o contrato Illuminate\Contracts\Mail\Mailer define os métodos necessários para envio de e-mail.
Cada contrato tem uma correspondente implementação fornecida pela estrutura. Por exemplo, o Laravel oferece uma implementação de fila com vários drivers e uma implementação do mailer que é alimentada pelo Gerenciador de email do Symfony.
Todos os contratos do Laravel estão no seu próprio repositório GitHub. Isso fornece um ponto de referência rápido para todos os contratos disponíveis, bem como um único pacote desacoplado que pode ser utilizado ao criar pacotes que interagem com serviços do Laravel.
Contratos versus facades
As Facades e as funções de auxílio do Laravel fornecem uma forma simples de utilizar os serviços do Laravel sem a necessidade de apontar tipos e resolver contratos para fora do container de serviço. Na maioria dos casos, cada Facade tem um contrato equivalente.
Ao contrário do que ocorre com as facades, que não exigem que você os inclua no construtor de sua classe, os contratos permitem que você defina dependências explícitas para suas classes. Alguns desenvolvedores preferem definir essas dependências de maneira explícita e, portanto, preferem usar contratos; outros consideram a facilidade das facades mais conveniente. Em geral, a maioria dos aplicativos pode usar facades sem problemas durante o desenvolvimento
Quando usar contratos
A decisão de usar contratos ou facades dependerá do seu gosto pessoal e dos gostos da sua equipe de desenvolvimento. Tanto os contratos como as facades podem ser utilizadas para criar aplicações Laravel robustas e bem testadas. Os contratos e facades não são mutuamente exclusivos. Algumas partes das suas aplicações poderão usar facades enquanto outras dependem de contratos. Desde que mantenham as responsabilidades da sua classe focadas, irá notar poucas diferenças práticas entre a utilização de contratos e facades.
Em geral, a maioria das aplicações podem usar facade sem problemas durante o desenvolvimento. Se você estiver construindo um pacote que se integra com vários frameworks PHP poderá utilizar o pacote illuminate/contracts para definir a sua integração com os serviços de Laravel, não tendo necessidade de requerer as implementações concretas do Laravel no ficheiro composer.json do seu pacote.
Como usar os contratos
Então, como você obtém uma implementação de um contrato? Na verdade, é bem simples.
Muitos tipos de classes no Laravel são resolvidos pelo conjunto de serviços, incluindo controladores, ouvintes de eventos, middlewares e até tarefas agendadas. Para obter uma implementação de um contrato, você pode simplesmente "dar pistas" da interface no construtor da classe que será resolvida.
Por exemplo, veja este ouvinte de evento:
<?php
namespace App\Listeners;
use App\Events\OrderWasPlaced;
use App\Models\User;
use Illuminate\Contracts\Redis\Factory;
class CacheOrderInformation
{
/**
* Crie uma nova instância do manipulador de eventos.
*/
public function __construct(
protected Factory $redis,
) {}
/**
* Lidar com o evento.
*/
public function handle(OrderWasPlaced $event): void
{
// ...
}
}Quando o ouvinte de eventos for resolvido, o contêiner de serviços irá ler as indicações de tipo no construtor da classe e injectar o valor apropriado. Para saber mais sobre como registrar elementos no contêiner de serviços, confira a documentação na seção container.
Referência do contrato
Esta tabela é uma referência rápida para todos os contratos de Laravel e suas equivalentes facade: