You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: contracts.md
+49-41Lines changed: 49 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,42 +1,43 @@
1
-
# Laravel 的接口契约
1
+
# Laravel 接口契约 Contracts
2
2
3
-
-[Introduction](#introduction)
3
+
-[简介](#introduction)
4
4
-[Contracts Vs. Facades](#contracts-vs-facades)
5
-
-[When To Use Contracts](#when-to-use-contracts)
6
-
-[Loose Coupling](#loose-coupling)
7
-
-[Simplicity](#simplicity)
8
-
-[How To Use Contracts](#how-to-use-contracts)
9
-
-[Contract Reference](#contract-reference)
5
+
-[何时使用 contracts](#when-to-use-contracts)
6
+
-[低耦合](#loose-coupling)
7
+
-[简单性](#simplicity)
8
+
-[如何使用 Contracts](#how-to-use-contracts)
9
+
-[Contract 参考](#contract-reference)
10
10
11
11
<aname="introduction"></a>
12
-
## Introduction
12
+
## 简介
13
13
14
-
Laravel's Contracts are a set of interfaces that define the core services provided by the framework. For example, a `Illuminate\Contracts\Queue\Queue` contract defines the methods needed for queueing jobs, while the `Illuminate\Contracts\Mail\Mailer` contract defines the methods needed for sending e-mail.
Each contract has a corresponding implementation provided by the framework. For example, Laravel provides a queue implementation with a variety of drivers, and a mailer implementation that is powered by [SwiftMailer](http://swiftmailer.org/).
All of the Laravel contracts live in [their own GitHub repository](https://github.com/illuminate/contracts). This provides a quick reference point for all available contracts, as well as a single, decoupled package that may be utilized by package developers.
Laravel's [facades](/docs/{{version}}/facades)and helper functions provide a simple way of utilizing Laravel's services without needing to type-hint and resolve contracts out of the service container. In most cases, each facade has an equivalent contract.
Unlike facades, which do not require you to require them in your class' constructor, contracts allow you to define explicit dependencies for your classes. Some developers prefer to explicitly define their dependencies in this way and therefore prefer to use contracts, while other developers enjoy the convenience of facades.
> {tip} Most applications will be fine regardless of whether you prefer facades or contracts. However, if you are building a package, you should strongly consider using contracts since they will be easier to test in a package context.
As discussed elsewhere, much of the decision to use contracts or facades will come down to personal taste and the tastes of your development team. Both contracts and facades can be used to create robust, well-tested Laravel applications. As long as you are keeping your class' responsibilities focused, you will notice very few practical differences between using contracts and facades.
However, you may still have several questions regarding contracts. For example, why use interfaces at all? Isn't using interfaces more complicated? Let's distill the reasons for using interfaces to the following headings: loose coupling and simplicity.
35
36
36
37
<aname="loose-coupling"></a>
37
-
### Loose Coupling
38
+
### 低耦合
38
39
39
-
First, let's review some code that is tightly coupled to a cache implementation. Consider the following:
40
+
首先，让我们回顾一些与缓存实现紧密耦合的代码。如下：
40
41
41
42
<?php
42
43
@@ -45,12 +46,12 @@ First, let's review some code that is tightly coupled to a cache implementation.
45
46
class Repository
46
47
{
47
48
/**
48
-
* The cache instance.
49
+
* 缓存实例。
49
50
*/
50
51
protected $cache;
51
52
52
53
/**
53
-
* Create a new repository instance.
54
+
* 创建一个仓库实例。
54
55
*
55
56
* @param \SomePackage\Cache\Memcached $cache
56
57
* @return void
@@ -61,7 +62,7 @@ First, let's review some code that is tightly coupled to a cache implementation.
61
62
}
62
63
63
64
/**
64
-
* Retrieve an Order by ID.
65
+
* 按照Id检索订单。
65
66
*
66
67
* @param int $id
67
68
* @return Order
@@ -74,11 +75,11 @@ First, let's review some code that is tightly coupled to a cache implementation.
74
75
}
75
76
}
76
77
77
-
In this class, the code is tightly coupled to a given cache implementation. It is tightly coupled because we are depending on a concrete Cache class from a package vendor. If the API of that package changes our code must change as well.
78
+
在这个类中，代码跟给定的缓存实现紧密耦合。因为我们依赖于一个具体的 Cache 类从一个软件包供应商。如果该包的 API 更改，我们的代码也必须更改。
78
79
79
-
Likewise, if we want to replace our underlying cache technology (Memcached) with another technology (Redis), we again will have to modify our repository. Our repository should not have so much knowledge regarding who is providing them data or how they are providing it.
**Instead of this approach, we can improve our code by depending on a simple, vendor agnostic interface:**
82
+
**比起上面的做法，我们可以使用一个简单，和扩展包无关的接口来改进代码：**
82
83
83
84
<?php
84
85
@@ -89,12 +90,12 @@ Likewise, if we want to replace our underlying cache technology (Memcached) with
89
90
class Repository
90
91
{
91
92
/**
92
-
* The cache instance.
93
+
* 缓存实例。
93
94
*/
94
95
protected $cache;
95
96
96
97
/**
97
-
* Create a new repository instance.
98
+
* 创建一个仓库实例。
98
99
*
99
100
* @param Cache $cache
100
101
* @return void
@@ -105,23 +106,24 @@ Likewise, if we want to replace our underlying cache technology (Memcached) with
105
106
}
106
107
}
107
108
108
-
Now the code is not coupled to any specific vendor, or even Laravel. Since the contracts package contains no implementation and no dependencies, you may easily write an alternative implementation of any given contract, allowing you to replace your cache implementation without modifying any of your cache consuming code.
When all of Laravel's services are neatly defined within simple interfaces, it is very easy to determine the functionality offered by a given service. **The contracts serve as succinct documentation to the framework's features.**
In addition, when you depend on simple interfaces, your code is easier to understand and maintain. Rather than tracking down which methods are available to you within a large, complicated class, you can refer to a simple, clean interface.
116
118
117
119
<aname="how-to-use-contracts"></a>
118
-
## How To Use Contracts
120
+
## 如何使用 Contracts
119
121
120
-
So, how do you get an implementation of a contract? It's actually quite simple.
122
+
那么，如何获取一个 contract 实现呢？这其实很简单。
121
123
122
-
Many types of classes in Laravel are resolved through the [service container](/docs/{{version}}/container), including controllers, event listeners, middleware, queued jobs, and even route Closures. So, to get an implementation of a contract, you can just "type-hint" the interface in the constructor of the class being resolved.
@@ -134,12 +136,12 @@ For example, take a look at this event listener:
134
136
class CacheOrderInformation
135
137
{
136
138
/**
137
-
* The Redis database implementation.
139
+
* Redis 数据库实现。
138
140
*/
139
141
protected $redis;
140
142
141
143
/**
142
-
* Create a new event handler instance.
144
+
* 创建事件处理器实例。
143
145
*
144
146
* @param Database $redis
145
147
* @return void
@@ -150,7 +152,7 @@ For example, take a look at this event listener:
150
152
}
151
153
152
154
/**
153
-
* Handle the event.
155
+
* 处理事件。
154
156
*
155
157
* @param OrderWasPlaced $event
156
158
* @return void
@@ -161,12 +163,13 @@ For example, take a look at this event listener:
161
163
}
162
164
}
163
165
164
-
When the event listener is resolved, the service container will read the type-hints on the constructor of the class, and inject the appropriate value. To learn more about registering things in the service container, check out [its documentation](/docs/{{version}}/container).
0 commit comments