跳到内容

合约

简介

Laravel 的“合约”是一组接口,用于定义框架提供的核心服务。例如,Illuminate\Contracts\Queue\Queue 合约定义了队列任务所需的方法,而 Illuminate\Contracts\Mail\Mailer 合约定义了发送电子邮件所需的方法。

每个合约都有框架提供的相应实现。例如,Laravel 提供了一个具有多种驱动程序的队列实现,以及一个由 Symfony Mailer 驱动的邮件程序实现。

所有 Laravel 合约都位于 它们自己的 GitHub 仓库 中。这为所有可用的合约提供了快速参考点,以及一个可以在构建与 Laravel 服务交互的软件包时使用的单一、解耦的软件包。

合约 vs. 外观模式

Laravel 的 外观模式 和辅助函数提供了一种简单的方法来使用 Laravel 的服务,而无需在服务容器之外进行类型提示和解析合约。在大多数情况下,每个外观模式都有一个等效的合约。

与外观模式不同,外观模式不需要你在类的构造函数中引入它们,合约允许你为类定义显式依赖项。一些开发者喜欢以这种方式显式定义他们的依赖项,因此更喜欢使用合约,而另一些开发者则喜欢外观模式的便利性。 一般来说,大多数应用程序可以在开发期间毫无问题地使用外观模式。

何时使用合约

使用合约还是外观模式的决定将取决于个人品味和你的开发团队的品味。合约和外观模式都可以用于创建健壮、经过良好测试的 Laravel 应用程序。合约和外观模式并非互斥。你的应用程序的某些部分可能使用外观模式,而另一些部分则依赖于合约。只要你保持你的类的职责集中,你就会注意到使用合约和外观模式之间几乎没有实际的区别。

一般来说,大多数应用程序可以在开发期间毫无问题地使用外观模式。如果你正在构建一个与多个 PHP 框架集成的软件包,你可能希望使用 illuminate/contracts 软件包来定义你与 Laravel 服务的集成,而无需在你的软件包的 composer.json 文件中引入 Laravel 的具体实现。

如何使用合约

那么,你如何获得合约的实现呢?实际上非常简单。

Laravel 中的许多类型的类都是通过 服务容器 解析的,包括控制器、事件监听器、中间件、队列任务,甚至路由闭包。因此,要获得合约的实现,你只需在正在解析的类的构造函数中“类型提示”接口即可。

例如,看看这个事件监听器

1<?php
2 
3namespace App\Listeners;
4 
5use App\Events\OrderWasPlaced;
6use App\Models\User;
7use Illuminate\Contracts\Redis\Factory;
8 
9class CacheOrderInformation
10{
11 /**
12 * Create a new event handler instance.
13 */
14 public function __construct(
15 protected Factory $redis,
16 ) {}
17 
18 /**
19 * Handle the event.
20 */
21 public function handle(OrderWasPlaced $event): void
22 {
23 // ...
24 }
25}

当事件监听器被解析时,服务容器将读取类的构造函数上的类型提示,并注入适当的值。要了解有关在服务容器中注册内容的更多信息,请查看 其文档

合约参考

此表提供了所有 Laravel 合约及其等效外观模式的快速参考

合约 参考外观模式
Illuminate\Contracts\Auth\Access\Authorizable  
Illuminate\Contracts\Auth\Access\Gate Gate
Illuminate\Contracts\Auth\Authenticatable  
Illuminate\Contracts\Auth\CanResetPassword  
Illuminate\Contracts\Auth\Factory Auth
Illuminate\Contracts\Auth\Guard Auth::guard()
Illuminate\Contracts\Auth\PasswordBroker Password::broker()
Illuminate\Contracts\Auth\PasswordBrokerFactory Password
Illuminate\Contracts\Auth\StatefulGuard  
Illuminate\Contracts\Auth\SupportsBasicAuth  
Illuminate\Contracts\Auth\UserProvider  
Illuminate\Contracts\Broadcasting\Broadcaster Broadcast::connection()
Illuminate\Contracts\Broadcasting\Factory Broadcast
Illuminate\Contracts\Broadcasting\ShouldBroadcast  
Illuminate\Contracts\Broadcasting\ShouldBroadcastNow  
Illuminate\Contracts\Bus\Dispatcher Bus
Illuminate\Contracts\Bus\QueueingDispatcher Bus::dispatchToQueue()
Illuminate\Contracts\Cache\Factory 缓存
Illuminate\Contracts\Cache\Lock  
Illuminate\Contracts\Cache\LockProvider  
Illuminate\Contracts\Cache\Repository Cache::driver()
Illuminate\Contracts\Cache\Store  
Illuminate\Contracts\Config\Repository Config
Illuminate\Contracts\Console\Application  
Illuminate\Contracts\Console\Kernel Artisan
Illuminate\Contracts\Container\Container App
Illuminate\Contracts\Cookie\Factory Cookie
Illuminate\Contracts\Cookie\QueueingFactory Cookie::queue()
Illuminate\Contracts\Database\ModelIdentifier  
Illuminate\Contracts\Debug\ExceptionHandler  
Illuminate\Contracts\Encryption\Encrypter Crypt
Illuminate\Contracts\Events\Dispatcher Event
Illuminate\Contracts\Filesystem\Cloud Storage::cloud()
Illuminate\Contracts\Filesystem\Factory Storage
Illuminate\Contracts\Filesystem\Filesystem Storage::disk()
Illuminate\Contracts\Foundation\Application App
Illuminate\Contracts\Hashing\Hasher Hash
Illuminate\Contracts\Http\Kernel  
Illuminate\Contracts\Mail\Mailable  
Illuminate\Contracts\Mail\Mailer 邮件
Illuminate\Contracts\Mail\MailQueue Mail::queue()
Illuminate\Contracts\Notifications\Dispatcher Notification
Illuminate\Contracts\Notifications\Factory Notification
Illuminate\Contracts\Pagination\LengthAwarePaginator  
Illuminate\Contracts\Pagination\Paginator  
Illuminate\Contracts\Pipeline\Hub  
Illuminate\Contracts\Pipeline\Pipeline Pipeline
Illuminate\Contracts\Queue\EntityResolver  
Illuminate\Contracts\Queue\Factory Queue
Illuminate\Contracts\Queue\Job  
Illuminate\Contracts\Queue\Monitor Queue
Illuminate\Contracts\Queue\Queue Queue::connection()
Illuminate\Contracts\Queue\QueueableCollection  
Illuminate\Contracts\Queue\QueueableEntity  
Illuminate\Contracts\Queue\ShouldQueue  
Illuminate\Contracts\Redis\Factory Redis
Illuminate\Contracts\Routing\BindingRegistrar Route
Illuminate\Contracts\Routing\Registrar Route
Illuminate\Contracts\Routing\ResponseFactory Response
Illuminate\Contracts\Routing\UrlGenerator URL
Illuminate\Contracts\Routing\UrlRoutable  
Illuminate\Contracts\Session\Session Session::driver()
Illuminate\Contracts\Support\Arrayable  
Illuminate\Contracts\Support\Htmlable  
Illuminate\Contracts\Support\Jsonable  
Illuminate\Contracts\Support\MessageBag  
Illuminate\Contracts\Support\MessageProvider  
Illuminate\Contracts\Support\Renderable  
Illuminate\Contracts\Support\Responsable  
Illuminate\Contracts\Translation\Loader  
Illuminate\Contracts\Translation\Translator Lang
Illuminate\Contracts\Validation\Factory Validator
Illuminate\Contracts\Validation\ValidatesWhenResolved  
Illuminate\Contracts\Validation\ValidationRule  
Illuminate\Contracts\Validation\Validator Validator::make()
Illuminate\Contracts\View\Engine  
Illuminate\Contracts\View\Factory View
Illuminate\Contracts\View\View View::make()

Laravel 是构建最高效的方式,用于
构建、部署和监控软件。