# 表单验证
- [简介](#introduction)
- [快速验证](#validation-quickstart)
- [定义路由](#quick-defining-the-routes)
- [创建路由器](#quick-creating-the-controller)
- [编写验证逻辑](#quick-writing-the-validation-logic)
- [显示验证错误信息](#quick-displaying-the-validation-errors)
- [可选字段注意事项](#a-note-on-optional-fields)
- [验证表单请求](#form-request-validation)
- [创建表单请求验证](#creating-form-requests)
- [表单请求授权验证](#authorizing-form-requests)
- [自定义验证错误信息](#customizing-the-error-messages)
- [自定义验证属性](#customizing-the-validation-attributes)
- [手动创建验证器](#manually-creating-validators)
- [自动转跳](#automatic-redirection)
- [命名错误包](#named-error-bags)
- [验证后钩子](#after-validation-hook)
- [处理错误信息](#working-with-error-messages)
- [自定义验证错误信息](#custom-error-messages)
- [可用验证规则](#available-validation-rules)
- [按条件添加验证规则](#conditionally-adding-rules)
- [验证数组](#validating-arrays)
- [自定义验证规则](#custom-validation-rules)
- [使用验证规则对象](#using-rule-objects)
- [使用闭包](#using-closures)
- [使用扩展](#using-extensions)
## 简介
Laravel 提供了几种不同的方法来验证传入应用程序的数据。默认情况下,Laravel 的控制器基类使用 `ValidatesRequests` Trait,它提供了一种方便的方法去使用各种强大的验证规则来验证传入的 HTTP 请求。
## 快速验证
要了解 Laravel 强大的验证功能,让我们看一个验证表单并将错误消息显示回给用户的完整示例。
### 定义路由
首先,让我们假设在 `routes/web.php` 文件中定义了下面这些路由:
Route::get('post/create', 'PostController@create');
Route::post('post', 'PostController@store');
显然,`GET` 路由会显示一个供用户创建一个新的博客帖子的表单,而 POST 路由会将新的博客文章存储在数据库中。
### 创建路由器
下面让我们一起来看看处理这些路由的控制器, `store` 方法暂时留空。
### 编写验证器逻辑
现在我们开始在 `store` 方法中编写逻辑来验证新的博客文章。为此,我们将使用 `Illuminate\Http\Request` 对象提供的 `validate` 方法 。如果验证通过,代码就可以正常的运行。如果验证失败,则会抛出异常,并自动将对应的错误响应返回给用户。在典型的 HTTP 请求的情况下,会生成一个重定向响应,而对于 AJAX 请求则会发送 JSON 响应。
让我们接着回到 `store` 方法来深入理解 `validate` 方法:
/**
* 保存一篇新的博客文章。
*
* @param Request $request
* @return Response
*/
public function store(Request $request)
{
$validatedData = $request->validate([
'title' => 'required|unique:posts|max:255',
'body' => 'required',
]);
// 博客文章验证通过
}
如你所见,我们将所需的验证规则传递至 `validate` 方法中。另外再提醒一次,如果验证失败,会自动生成一个对应的响应。如果验证通过,那我们的控制器将会继续正常运行。
#### 首次验证失败后停止运行
如果你希望在某个属性第一次验证失败后停止运行验证规则,你需要附加 `bail` 规则到该属性:
$request->validate([
'title' => 'bail|required|unique:posts|max:255',
'body' => 'required',
]);
在这个例子中,如果 `title` 字段没有通过 `unique` 规则,那么程序就不会继续检查 `max` 规则。规则会按照分配的顺序来验证。
#### 关于数组数据的注意实现
如果你的 HTTP 请求包含一个 「嵌套」 参数(即数组),那你可以在验证规则中通过 「点」 语法来指定这些参数。
$request->validate([
'title' => 'required|unique:posts|max:255',
'author.name' => 'required',
'author.description' => 'required',
]);
### 显示验证错误信息
如果传入的请求参数未通过给定的验证规则呢?正如前面所提到的,Laravel 会自动把用户重定向到之前的位置。另外,所有的验证错误信息会被自动 [存储到 `session` 中](/docs/{{version}}/session#flash-data)。
重申一次,我们不必在 `GET` 路由中将错误消息显式绑定到视图。因为 Lavarel 会检查在 Session 数据中的错误信息,并自动将其绑定到视图(如果这个视图文件存在)。而其中的变量 `$errors` 是 `Illuminate\Support\MessageBag` 的一个实例。要获取关于这个对象的更多信息,请 [ 查阅这个文档 ](#working-with-error-messages)。
> {tip} `$errors` 变量被 `Web` 中间件组提供的 `Illuminate\View\Middleware\ShareErrorsFromSession` 中间件绑定到视图中。 **当这个中间件被应用后,在你的视图中就可以获取到 `$error` 变量**, 可以使一直假定 `$errors` 变量存在并且可以安全地使用。
在上面的例子中,当验证失败的时候,用户将会被重定向到控制器的 `create` 方法,使我们能在视图中显示错误信息:
创建文章
@if ($errors->any())
@foreach ($errors->all() as $error)
- {{ $error }}
@endforeach
@endif
### 关于可选字段的注意事项
默认情况下,在 Laravel 应用的全局中间件堆栈 `App\Http\Kernel` 类中包含了 `TrimStrings` 和 `ConvertEmptyStringsToNull` 中间件。因此,如果你不希望验证程序将 `null` 值视为无效的话,那就需要将「可选」的请求字段标记为 `nullable`,举个例子:
$request->validate([
'title' => 'required|unique:posts|max:255',
'body' => 'required',
'publish_at' => 'nullable|date',
]);
在这个例子里,我们指定 `publish_at` 字段可以为 `null` 或者一个有效的日期格式。如果 `nullable` 的修饰词没有被添加到规则定义中,验证器会认为 `null` 是一个无效的日期格式。
#### AJAX 请求 & 验证
在这个例子中,我们使用传统的表单将数据发送到应用程序。但实际情况中,很多程序都会使用 AJAX 来发送请求。当我们对 AJAX 的请求中使用 `validate` 方法时,Laravel 并不会生成一个重定向响应,而是会生成一个包含所有验证错误信息的 JSON 响应。这个 JSON 响应会包含一个 HTTP 状态码 422 被发送出去。
## 验证表单请求
### 创建表单请求验证
面对更复杂的验证情境中,你可以创建一个「表单请求」来处理更为复杂的逻辑。表单请求是包含验证逻辑的自定义请求类。可使用 Artisan 命令 `make:request` 来创建表单请求类:
php artisan make:request StoreBlogPost
新生成的类保存在 `app/Http/Requests` 目录下。如果这个目录不存在,运行 `make:request` 命令时它会被创建出来。让我们添加一些验证规则到 `rules` 方法中:
/**
* 获取适用于请求的验证规则。
*
* @return array
*/
public function rules()
{
return [
'title' => 'required|unique:posts|max:255',
'body' => 'required',
];
}
> {tip} 你可以向 `rules` 方法传入所需的任何依赖项。他们会自动被 Laravel 提供的[ 服务容器 ](/docs/{{version}}/container)自动解析。
验证规则是如何运行的呢?你所需要做的就是在控制器方法中类型提示传入的请求。在调用控制器方法之前验证传入的表单请求,这意味着你不需要在控制器中写任何验证逻辑:
/**
* 存储传入的博客文章。
*
* @param StoreBlogPost $request
* @return Response
*/
public function store(StoreBlogPost $request)
{
// 传入的请求通过验证...
// 获取通过验证的数据...
$validated = $request->validated();
}
如果验证失败,就会生成一个让用户返回到先前的位置的重定向响应。这些错误也会被闪存到 `session` 中,以便这些错误都可以在页面中显示出来。如果传入的请求是 AJAX,会向用户返回具有 422 状态代码和验证错误信息的 JSON 数据的 HTTP 响应。
#### 添加表单请求后钩子
如果你想在表单请求「之后」添加钩子,可以使用 `withValidator` 方法。这个方法接收一个完整的验证构造器,允许你在验证结果返回之前调用任何方法:
/**
* 配置验证器实例。
*
* @param \Illuminate\Validation\Validator $validator
* @return void
*/
public function withValidator($validator)
{
$validator->after(function ($validator) {
if ($this->somethingElseIsInvalid()) {
$validator->errors()->add('field', 'Something is wrong with this field!');
}
});
}
### 表单请求授权验证
表单请求类内也包含了 `authorize` 方法。在这个方法中,你可以检查经过身份验证的用户确定其是否具有更新给定资源的权限。比方说,你可以判断用户是否拥有更新文章评论的权限:
/**
* 判断用户是否有权限做出此请求。
*
* @return bool
*/
public function authorize()
{
$comment = Comment::find($this->route('comment'));
return $comment && $this->user()->can('update', $comment);
}
由于所有的表单请求都是继承了 Laravel 中的请求基类,所以我们可以使用 `user` 方法去获取当前认证登录的用户。同时请注意上述例子中对 `route` 方法的调用。这个方法允许你在被调用的路由上获取其定义的 URI 参数,譬如下面例子中的 `{comment}` 参数:
Route::post('comment/{comment}');
如果 `authorize` 方法返回 `false`,则会自动返回一个包含 403 状态码的 HTTP 响应,也不会运行控制器的方法。
如果你打算在应用程序的其它部分处理授权逻辑,只需从 `authorize` 方法返回 `true`:
/**
* 判断用户是否有权限进行此请求。
*
* @return bool
*/
public function authorize()
{
return true;
}
> {tip} 你可以向 `authorize` 方法传入所需的任何依赖项。他们会自动被 Laravel 提供的[ 服务容器 ](/docs/{{version}}/container)自动解析。
### 自定义错误消息
你可以通过重写表单请求的 `messages` 方法来自定义错误消息。此方法应返回属性 / 规则对及其对应错误消息的数组:
/**
* 获取已定义验证规则的错误消息。
*
* @return array
*/
public function messages()
{
return [
'title.required' => 'A title is required',
'body.required' => 'A message is required',
];
}
### 自定义验证属性
如果你希望将验证消息的 `:attribute` 部分替换为自定义属性名称,则可以重写 `attributes` 方法来指定自定义名称。此方法应返回属性 / 名称对的数组:
/**
* 获取验证错误的自定义属性。
*
* @return array
*/
public function attributes()
{
return [
'email' => 'email address',
];
}
## 手动创建验证器
如果你不想在请求上使用 `validate` 方法,你可以通过 `Validator` [facade](/docs/{{version}}/facades) 手动创建一个验证器示例。
用 `Validator` [facade](/docs/{{version}}/facades) 上的 `make` 方法创建一个验证器示例:
all(), [
'title' => 'required|unique:posts|max:255',
'body' => 'required',
]);
if ($validator->fails()) {
return redirect('post/create')
->withErrors($validator)
->withInput();
}
// Store the blog post...
}
}
传给 `make` 方法的第一个参数是需要验证的数据。第二个参数则是该数据的验证规则。
如果验证失败,则可以使用 `withErrors` 方法把错误消息闪存到 Session 。使用这个方法进行重定向后, `$errors` 变量会自动和视图共享,你可以把这些消息显示给用户。 `withErrors` 方法接收验证器、`MessageBag` 或 PHP `Array` 。
### 自动重定向
如果你想手动创建验证器实例,又想使用 `validates` 方法提供的自动重定向,那么你可以在现有的验证器示例上调用 `validate` 方法。如果验证失败,用户将会自动重定向。在 AJAX 请求中,则会返回 JSON 格式的响应。
Validator::make($request->all(), [
'title' => 'required|unique:posts|max:255',
'body' => 'required',
])->validate();
### 命名错误包
如果你一个页面中有多个表单,你可以通过命名错误包来检索特定表单的错误消息。只需给 `withErrors` 方法传递一个名字作为第二个参数
return redirect('register')
->withErrors($validator, 'login');
然后你就可以从 `$errors` 变量中获取指定表单的错误消息:
{{ $errors->login->first('email') }}
### 验证后钩子
验证器还允许你添加在验证成功之后允许的回调函数,以便你进行下一步的验证,甚至在消息集合中添加更多的错误消息。使用它只需在验证实例上使用 `after` 方法:
$validator = Validator::make(...);
$validator->after(function ($validator) {
if ($this->somethingElseIsInvalid()) {
$validator->errors()->add('field', 'Something is wrong with this field!');
}
});
if ($validator->fails()) {
//
}
## 处理错误消息
在 `Validator` 实例上调用 `errors` 方法后,你会得到一个 `Illuminate\Support\MessageBag` 实例,它拥有各种方便的方法处理错误信息。自动提供给所有视图的 `$ errors` 变量,也是 `MessageBag` 类的一个实例。
#### 查看特定字段的第一个错误信息
要查看特定字段的第一个错误消息,可以使用 `first` 方法:
$errors = $validator->errors();
echo $errors->first('email');
#### 查看特定字段的所有错误消息
如果你需要获取指定字段的所有错误消息的数组,则可以使用 `get` 方法:
foreach ($errors->get('email') as $message) {
//
}
如果要验证表单的数组字段,你可以使用 `*` 来获取每个数组元素的所有错误消息:
foreach ($errors->get('attachments.*') as $message) {
//
}
#### 查看所有字段的所有错误消息
如果你想要得到所有字段的所有错误消息,可以使用 `all` 方法:
foreach ($errors->all() as $message) {
//
}
#### 判断特定字段是否含有错误消息
`has` 方法可以被用来判断给定的字段是否存在错误信息:
if ($errors->has('email')) {
//
}
### 自定义错误消息
如果有需要的话,你也可以使用自定义错误消息取代默认值进行验证。有几种方法可以指定自定义消息。首先,你可以将自定义消息作为第三个参数传递给 `Validator::make` 方法:
$messages = [
'required' => 'The :attribute field is required.',
];
$validator = Validator::make($input, $rules, $messages);
在这个例子中,`:attribute` 占位符会被验证字段的实际名称取代。除此之外,你还可以在验证消息中使用其它占位符。例如:
$messages = [
'same' => 'The :attribute and :other must match.',
'size' => 'The :attribute must be exactly :size.',
'between' => 'The :attribute value :input is not between :min - :max.',
'in' => 'The :attribute must be one of the following types: :values',
];
#### 为给定属性指定自定义消息
有时候你可能只想为特定的字段自定义错误消息。只需在属性名称后使用「点」语法来指定验证的规则即可:
$messages = [
'email.required' => 'We need to know your e-mail address!',
];
#### 在语言文件中指定自定义消息
在大多数情况下,您可能会在语言文件中指定自定义消息,而不是直接将它们传递给`Validator`。为此,需要把你的消息放置于 `resources/lang/xx/validation.php` 语言文件内的 `custom` 数组中。
'custom' => [
'email' => [
'required' => 'We need to know your e-mail address!',
],
],
#### 在语言文件中指定自定义属性
如果你希望将验证消息的 `:attribute` 占位符替换为自定义属性名称,你可以在 `resources/lang/xx/validation.php` 语言文件的 `attributes` 数组中指定自定义名称:
'attributes' => [
'email' => 'email address',
],
#### 在语言文件中指定自定义值
有时可能需要将验证消息的 `:value` 占位符替换为值的自定义文字。例如,如果 `payment_type` 的值为 `cc`,使用以下验证规则,该规则指定需要信用卡号:
$request->validate([
'credit_card_number' => 'required_if:payment_type,cc'
]);
如果此验证规则失败,则会产生以下错误消息:
当payment type为cc时,credit card number 不能为空。
您可以通过定义 `values` 数组,在 `validation` 语言文件中指定自定义值表示,而不是显示 `cc` 作为支付类型值:
'values' => [
'payment_type' => [
'cc' => '信用卡'
],
],
现在,如果验证规则失败,它将产生以下消息:
当payment type 为信用卡时,credit card number不能为空。
## 可用验证规则
以下是所有可用验证规则及其功能的列表:
[Accepted](#rule-accepted)
[Active URL](#rule-active-url)
[After (Date)](#rule-after)
[After Or Equal (Date)](#rule-after-or-equal)
[Alpha](#rule-alpha)
[Alpha Dash](#rule-alpha-dash)
[Alpha Numeric](#rule-alpha-num)
[Array](#rule-array)
[Bail](#rule-bail)
[Before (Date)](#rule-before)
[Before Or Equal (Date)](#rule-before-or-equal)
[Between](#rule-between)
[Boolean](#rule-boolean)
[Confirmed](#rule-confirmed)
[Date](#rule-date)
[Date Equals](#rule-date-equals)
[Date Format](#rule-date-format)
[Different](#rule-different)
[Digits](#rule-digits)
[Digits Between](#rule-digits-between)
[Dimensions (Image Files)](#rule-dimensions)
[Distinct](#rule-distinct)
[E-Mail](#rule-email)
[Exists (Database)](#rule-exists)
[File](#rule-file)
[Filled](#rule-filled)
[Greater Than](#rule-gt)
[Greater Than Or Equal](#rule-gte)
[Image (File)](#rule-image)
[In](#rule-in)
[In Array](#rule-in-array)
[Integer](#rule-integer)
[IP Address](#rule-ip)
[JSON](#rule-json)
[Less Than](#rule-lt)
[Less Than Or Equal](#rule-lte)
[Max](#rule-max)
[MIME Types](#rule-mimetypes)
[MIME Type By File Extension](#rule-mimes)
[Min](#rule-min)
[Not In](#rule-not-in)
[Not Regex](#rule-not-regex)
[Nullable](#rule-nullable)
[Numeric](#rule-numeric)
[Present](#rule-present)
[Regular Expression](#rule-regex)
[Required](#rule-required)
[Required If](#rule-required-if)
[Required Unless](#rule-required-unless)
[Required With](#rule-required-with)
[Required With All](#rule-required-with-all)
[Required Without](#rule-required-without)
[Required Without All](#rule-required-without-all)
[Same](#rule-same)
[Size](#rule-size)
[Starts With](#rule-starts-with)
[String](#rule-string)
[Timezone](#rule-timezone)
[Unique (Database)](#rule-unique)
[URL](#rule-url)
[UUID](#rule-uuid)
#### accepted
验证字段必须是 _yes_, _on_, _1_,或 _true_。这在确认「服务条款」是否同意时相当有用。
#### active_url
根据 PHP函数 `dns_get_record`,验证字段必须具有有效的A或AAAA记录。
#### after:_date_
验证字段必须是给定日期之后的值。日期值将传递到 PHP函数 `strtotime`:
'start_date' => 'required|date|after:tomorrow'
您可以指定另一个要与日期进行比较的字段,而不是传递要由 `strtotime` 处理的日期字符串:
'finish_date' => 'required|date|after:start_date'
#### after\_or\_equal:_date_
验证字段必须是在给定日期之后或与此日期相同的值。更多信息,请参阅 [after](#rule-after) 规则。
#### alpha
验证字段必须完全由字母构成。
#### alpha_dash
验证字段可能包含字母、数字,以及破折号 ( - ) 和下划线 ( _ )。
#### alpha_num
验证字段必须是完全是字母、数字。
#### array
验证的字段必须是一个 PHP 数组。
#### bail
在第一次验证失败后停止运行验证规则。
#### before:_date_
验证字段必须是在给定日期之前。这个日期值将会被传递给 PHP 的 `strtotime` 函数来计算。
#### before\_or\_equal:_date_
验证字段必须是在给定日期之前或与之相同的日期。这个日期值将会被传递给 PHP 的 `strtotime` 函数来计算。
#### between:_min_,_max_
验证字段的大小必须在给定的 _min_ 和 _max_ 之间。字符串、数字、数组和文件的计算方式都使用 [`size`](#rule-size) 方法。
#### boolean
验证的字段必须可以转换为 Boolean类型。 可接受的输入为 `true`, `false`, `1`, `0`, `"1"`, 和 `"0"`。
#### confirmed
验证字段必须具有匹配字段 `foo_confirmation`。例如,验证字段为 `password` ,输入中必须存在与之匹配的 `password_confirmation` 字段。
#### date
根据 PHP函数 `strtotime`,验证字段必须是有效的日期。
#### date_equals:_date_
验证字段必须等于给定日期。日期将传递到 PHP 函数 `strtotime`。
#### date_format:_format_
验证字段必须匹配给定的日期格式。当验证某个字段的时候,你应该 **只使用** `date` 或者 `date_format` ,而不是同时使用。
#### different:_field_
验证字段必须具有与 _field_ 不同的值。
#### digits:_value_
验证字段必须为 _numeric_ ,且必须具有_value_的确切长度。
#### digits_between:_min_,_max_
验证的字段的长度必须在给定的 _min_ 和 _max_ 之间。
#### dimensions
验证中的文件必须是图片,并且符合指定的规则约束:
'avatar' => 'dimensions:min_width=100,min_height=200'
可用的约束为: _min\_width_, _max\_width_, _min\_height_, _max\_height_, _width_, _height_, _ratio_。
_ratio_ 限制应该表示为宽度除以高度。 这可以通过使用像 `3/2` 的表达式 或者一个浮点数,像 `1.5` 来指定:
'avatar' => 'dimensions:ratio=3/2'
由于此规则需要多个参数,你可以使用 `Rule::dimensions` 方法流畅地构造规则:
use Illuminate\Validation\Rule;
Validator::make($data, [
'avatar' => [
'required',
Rule::dimensions()->maxWidth(1000)->maxHeight(500)->ratio(3 / 2),
],
]);
#### distinct
当验证数组时,验证字段不得包含任何重复值。
'foo.*.id' => 'distinct'
#### email
验证字段必须为正确格式的电子邮件地址。
#### exists:_table_,_column_
验证字段必须存在于给定的数据库表中。
#### Exists 规则基本用法
'state' => 'exists:states'
如果未指定 `column` 选项,则将使用字段名称。
#### 指定自定义的表字段
'state' => 'exists:states,abbreviation'
有时,你可能需要指定要用于「exists」查询的特定数据库连接。你可以使用「点」语法将连接名称添加到表名称前来完成此操作:
'email' => 'exists:connection.staff,email'
如果您想自定义验证规则执行的查询,您可以使用 `Rule` 类来流畅地定义规则。在下面的例子中,我们还以数组的形式指定验证规则,而不是使用 `|` 字符来分隔它们:
use Illuminate\Validation\Rule;
Validator::make($data, [
'email' => [
'required',
Rule::exists('staff')->where(function ($query) {
$query->where('account_id', 1);
}),
],
]);
#### file
验证的字段必须是成功上传的文件。
#### filled
验证字段存在时不得为空。
#### gt:_field_
验证字段必须大于给定的 _field_。两个字段必须是相同的类型。字符串、数字、数组和文件都使用 `size` 进行相同的评估。
#### gte:_field_
验证字段必须大于或等于给定的 _field_。两个字段必须是相同的类型。字符串、数字、数组和文件都使用 `size` 进行相同的评估。
#### image
验证的文件必须是图片 (jpeg, png, bmp, gif, 或 svg)
#### in:_foo_,_bar_,...
验证字段必须包含在给定的值列表中。由于此规则通常要求您 `implode` 数组,因此可以使用 `Rule :: in` 方法流畅地构造规则:
use Illuminate\Validation\Rule;
Validator::make($data, [
'zones' => [
'required',
Rule::in(['first-zone', 'second-zone']),
],
]);
#### in_array:_anotherfield_
验证的字段必须存在于另一个字段 _anotherfield_ 的值中。
#### integer
验证的字段必须是整数。
#### ip
验证的字段必须是 IP 地址。
#### ipv4
验证的字段必须是 IPv4 地址。
#### ipv6
验证的字段必须是 IPv6 地址。
#### json
验证的字段必须是有效的 JSON 字符串。
#### lt:_field_
验证中的字段必须小于给定的字段。这两个字段必须是相同的类型。字符串、数值、数组和文件大小的计算方式与 `size` 方法进行评估。
#### lte:_field_
验证中的字段必须小于或等于给定的_字段_。这两个字段必须是相同的类型。字符串、数值、数组和文件大小的计算方式与 `size` 方法进行评估。
#### max:_value_
验证中的字段必须小于或等于 _value_。字符串、数字、数组或是文件大小的计算方式都用 [`size`](https://learnku.com/docs/laravel/5.7/validation/1372#rule-size) 方法进行评估。
#### mimetypes:_text/plain_,...
验证的文件必须与给定 MIME 类型之一匹配:
'video' => 'mimetypes:video/avi,video/mpeg,video/quicktime'
要确定上传文件的 MIME 类型,会读取文件的内容来判断 MIME 类型,这可能与客户端提供的 MIME 类型不同。
#### mimes:_foo_,_bar_,...
验证的文件必须具有与列出的其中一个扩展名相对应的 MIME 类型。
#### MIME 规则基本用法
'photo' => 'mimes:jpeg,bmp,png'
即使你可能只需要验证指定扩展名,但此规则实际上会验证文件的 MIME 类型,其通过读取文件的内容以猜测它的 MIME 类型。
可以在以下链接中找到完整的 MIME 类型列表及其相应的扩展名:
[https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types](https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types)
#### min:_value_
验证中的字段必须具有最小值。字符串、数字、数组或是文件大小的计算方式都用 [`size`](#rule-size) 方法进行评估。
#### not_in:_foo_,_bar_,...
验证的字段不能包含在给定的值列表中。`Rule::notIn` 方法可以用来构建规则:
use Illuminate\Validation\Rule;
Validator::make($data, [
'toppings' => [
'required',
Rule::notIn(['sprinkles', 'cherries']),
],
]);
#### not_regex:_pattern_
验证中的字段必须与给定的正则表达式不匹配。
在内部,此规则使用 PHP `preg_match` 函数。输入的值应遵循 `preg_match` 函数所需的相同格式,因此也包括有效的分隔符。例如:`'email' => 'not_regex:/^.+$/i'`。
**注意:** 当使用 `regex`/`not_regex` 模式时,可能需要在数组中指定规则,而不是使用管道分隔符,尤其是在正则表达式包含管道字符的情况下。
#### nullable
验证的字段可以为 `null`。这在验证基本数据类型时特别有用,例如可以包含空值的字符串和整数。
#### numeric
验证的字段必须是数字。
#### present
验证的字段必须存在于输入数据中,但可以为空。
#### regex:_pattern_
验证的字段必须与给定的正则表达式匹配。
在内部,此规则使用 PHP `preg_match` 函数。输入的值应遵循 `preg_match` 函数所需的相同格式,因此也包括有效的分隔符。例如:`'email' => 'regex:/^.+@.+$/i'`。
**注意:** 当使用 `regex` 规则时,你必须使用数组,而不是使用 `|` 分隔符,特别是如果正则表达式包含 `|` 字符。
#### required
验证的字段必须存在于输入数据中,而不是空。如果满足以下条件之一,则字段被视为「空」:
- 值为 `null`。
- 值为空字符串。
- 值为空数组或空 `Countable` 对象。
- 值为无路径的上传文件。
#### required_if:_anotherfield_,_value_,...
如果 _anotherfield_ 字段等于任一 _value_,验证的字段必须出现且不为空 。
如果你想为 `required_if` 规则构造一个更复杂的条件,你可以使用 `Rule::requiredIf` 方法。此方法接受布尔值或闭包。当传递一个闭包时,应返回 `true` 或 `false` 以确认是否需要验证字段:
use Illuminate\Validation\Rule;
Validator::make($request->all(), [
'role_id' => Rule::requiredIf($request->user()->is_admin),
]);
Validator::make($request->all(), [
'role_id' => Rule::requiredIf(function () use ($request) {
return $request->user()->is_admin;
}),
]);
#### required_unless:_anotherfield_,_value_,...
如果 _anotherfield_ 字段不等于任一 _value_,验证的字段必须出现且不为空。
#### required_with:_foo_,_bar_,...
只有在其他任一指定字段出现时,验证的字段才必须出现且不为空。
#### required_with_all:_foo_,_bar_,...
只有在其他指定字段全部出现时,验证的字段才必须出现且不为空。
#### required_without:_foo_,_bar_,...
只在其他指定任一字段不出现时,验证的字段才必须出现且不为空。
#### required_without_all:_foo_,_bar_,...
只有在其他指定字段全部不出现时,验证的字段才必须出现且不为空。
#### same:_field_
验证的字段必须与给定字段匹配。
#### size:_value_
验证的字段必须具有与给定值匹配的大小。对于字符串,value 对应字符数。对于数字,value 对应给定的整数值。对于数组,size 对应数组的 `count` 值。对于文件,size 对应文件大小(单位kb)。
#### starts_with:_foo_,_bar_,...
验证的字段必须以给定值之一开头。
#### string
验证的字段必须是一个字符串。如果允许这个字段为 `null`,需要给这个字段分配 `nullable` 规则。
#### timezone
验证的字段必须是一个基于 PHP 函数 `timezone_identifiers_list` 的有效时区标识。
#### unique:_table_,_column_,_except_,_idColumn_
验证的字段在给定的数据库表中必须是唯一的。如果没有指定 `column` ,将会使用字段本身的名称。
**指定自定义字段**
'email' => 'unique:users,email_address'
**自定义数据库连接**
有时,你可能需要为验证程序创建的数据库查询设置自定义连接。上面的例子中,将 `unique:users` 设置为验证规则,等于使用默认数据库连接来查询数据库。如果要对其进行修改,请使用「点」方法指定连接和表名:
'email' => 'unique:connection.users,email_address'
**强迫 Unique 规则忽略指定 ID :**
有时,你可能希望在进行字段唯一性验证时忽略指定 ID 。例如, 在「更新个人资料」页面会包含用户名、邮箱和地点。这时你会想要验证更新的 E-mail 值是否唯一。如果用户仅更改了用户名字段而没有改 E-mail 字段,就不需要抛出验证错误,因为此用户已经是这个 E-mail 的拥有者了。
使用 `Rule` 类定义规则来指示验证器忽略用户的 ID。这个例子中通过数组来指定验证规则,而不是使用 | 字符来分隔:
use Illuminate\Validation\Rule;
Validator::make($data, [
'email' => [
'required',
Rule::unique('users')->ignore($user->id),
],
]);
> {tip} 您永远不应将任何用户控制的请求输入传递给 `ignore` 方法。相反,您应该只从Eloquent模型实例传递系统生成的唯一ID,例如自增ID或UUID。否则,您的应用程序将容易受到SQL注入攻击。
你可以传递整个模型实例,而不是将模型键的值传递给 `ignore` 方法。Laravel 将自动从模型中提取主键:
Rule::unique('users')->ignore($user)
如果你的数据表使用的主键名称不是 `id` ,那就在调用 `ignore` 方法时指定字段的名称:
Rule::unique('users')->ignore($user->id, 'user_id')
默认情况下,`unique` 规则将检查与要验证的属性的名称匹配的列是否唯一。但是你可以将不同的列名称作为第二个参数传递给 `unique` 方法:
Rule::unique('users', 'email_address')->ignore($user->id),
**增加额外的 Where 语句:**
你也可以通过 `where` 方法指定额外的查询条件。例如, 我们添加 `account_id` 为 `1` 的约束:
'email' => Rule::unique('users')->where(function ($query) {
return $query->where('account_id', 1);
})
#### url
验证的字段必须是有效的 URL。
#### uuid
验证字段必须是有效的 RFC 4122(版本 1,3,4 或 5)通用唯一标识符(UUID)。
## 按条件增加规则
#### 存在时则验证
在某些情况下,**只有**在该字段存在于数组中时, 才可以对字段执行验证检查。可通过增加 `sometimes` 到规则列表来实现:
$v = Validator::make($data, [
'email' => 'sometimes|required|email',
]);
在上面的例子中, `email` 字段只有在 `$data` 数组中存在才会被验证。
> {tip} 如果你尝试验证应该始终存在但可能为空的字段,请查阅 [可选字段的注意事项](#a-note-on-optional-fields)
#### 复杂的条件验证
有时候你可能需要增加基于更复杂的条件逻辑的验证规则。例如,你可以希望某个指定字段在另一个字段的值超过 100 时才为必填。或者当某个指定字段存在时,另外两个字段才能具有给定的值。增加这样的验证条件并不难。首先,使用 静态规则 创建一个 `Validator` 实例:
$v = Validator::make($data, [
'email' => 'required|email',
'games' => 'required|numeric',
]);
假设我们有一个专为游戏收藏家所设计的网页应用程序。如果游戏收藏家收藏超过一百款游戏,我们会希望他们来说明下为什么他们会拥有这么多游戏。比如说他们有可能经营了一家游戏分销商店,或者只是为了享受收集的乐趣。为了在特定条件下加入此验证需求,可以在 `Validator `实例中使用 `sometimes` 方法。
$v->sometimes('reason', 'required|max:500', function ($input) {
return $input->games >= 100;
});
传入 `sometimes` 方法的第一个参数是要用来验证的字段名称。第二个参数是我们想使用的验证规则。 `闭包` 作为第三个参数传入,如果其返回 `true` , 则额外的规则就会被加入。这个方法可以轻松地创建复杂的条件验证。你甚至可以一次对多个字段增加条件验证:
$v->sometimes(['reason', 'cost'], 'required', function ($input) {
return $input->games >= 100;
});
> {tip} 传入 `闭包` 的 `$input` 参数是 `Illuminate\Support\Fluent` 的一个实例,可用来访问你的输入或文件对象。
## 验证数组
验证表单的输入为数组的字段也不难。你可以使用 「点」方法来验证数组中的属性。例如,如果传入的 HTTP 请求中包含 `photos[profile]` 字段, 可以如下验证:
$validator = Validator::make($request->all(), [
'photos.profile' => 'required|image',
]);
你也可以验证数组中的每个元素。例如,要验证指定数组输入字段中的每一个 email 是唯一的,可以这么做:
$validator = Validator::make($request->all(), [
'person.*.email' => 'email|unique:users',
'person.*.first_name' => 'required_with:person.*.last_name',
]);
同理,你可以在语言文件定义验证信息时使用 `*` 字符,为基于数组的字段使用单个验证消息:
'custom' => [
'person.*.email' => [
'unique' => 'Each person must have a unique e-mail address',
]
],
## 自定义验证规则
### 使用规则对象
Laravel 提供了许多有用的验证规则;同时也支持自定义规则。注册自定义验证规则的方法之一,就是使用规则对象。可以使用 Artisan 命令 `make:rule` 来生成新的规则对象。接下来,让我们用这个命令生成一个验证字符串是大写的规则。Laravel 会将新的规则存放在 `app/Rules` 目录中:
php artisan make:rule Uppercase
一旦创建了规则,我们就可以定义它的行为。规则对象包含两个方法: `passes` 和 `message`。`passes` 方法接收属性值和名称,并根据属性值是否符合规则而返回 `true` 或 `false`。 `message` 方法应返回验证失败时应使用的验证错误消息:
validate([
'name' => ['required', 'string', new Uppercase],
]);
### 使用闭包
如果你在应用程序中只需要一次自定义规则的功能,则可以使用闭包而不是规则对象。闭包接收属性的名称,属性的值如果验证失败则应该使用回调中的 `$fail`:
$validator = Validator::make($request->all(), [
'title' => [
'required',
'max:255',
function ($attribute, $value, $fail) {
if ($value === 'foo') {
$fail($attribute.' is invalid.');
}
},
],
]);
### 使用扩展
注册自定义的验证规则的另一种方法是使用 `Validator` [facade](/docs/{{version}}/facades) 中的 `extend` 方法。让我们在 [服务容器](/docs/{{version}}/providers) 中使用这个方法来注册自定义验证规则:
"Your input was invalid!",
"accepted" => "The :attribute must be accepted.",
// 其余的验证错误消息...
当创建一个自定义验证规则时,你可能有时候需要为错误信息定义自定义占位符。可以通过创建自定义验证器然后调用 `Validator` 门面上的 `replacer` 方法。你可以在 [服务容器](/docs/{{version}}/providers) 的 `boot` 方法中执行如下操作:
/**
* 启动应用程序。
*
* @return void
*/
public function boot()
{
Validator::extend(...);
Validator::replacer('foo', function ($message, $attribute, $rule, $parameters) {
return str_replace(...);
});
}
#### 隐式扩展
默认情况下, 当所要验证的属性不存在或包含由 [`required`](#rule-required) 规则定义的空值时,那么正常的验证规则,包括自定义扩展将不会执行。 例如,[`unique`](#rule-unique) 规则将不会检验 `null` 值:
$rules = ['name' => 'unique'];
$input = ['name' => null];
Validator::make($input, $rules)->passes(); // true
如果要求即使为空时也要验证属性,则必须要暗示属性是必须的。要创建这样一个「隐式」扩展, 可以使用 `Validator::extendImplicit()` 方法:
Validator::extendImplicit('foo', function ($attribute, $value, $parameters, $validator) {
return $value == 'foo';
});
> {note} 「隐式」扩展只暗示该属性是必需的。至于它到底是缺失的还是空值这取决于你。