* * * * *
[TOC]
## 简介
Blade 是 Laravel 提供的一个简单而又强大的模板引擎。和其他流行的 PHP 模板引擎不同，Blade 并不限制你在视图中使用原生 PHP 代码。所有 Blade 视图文件都将被编译成原生的 PHP 代码并缓存起来，除非它被修改，否则不会重新编译，这就意味着 Blade 基本上不会给你的应用增加任何负担。Blade 视图文件使用 `.blade.php` 作为文件扩展名，被存放在 `resources/views` 目录。
## 模板继承
### 定义布局
Blade 的两个主要优点是 *模板继承* 和 *区块* 。为方便开始，让我们先通过一个简单的例子来上手。首先，我们来研究一个「主」页面布局。因为大多数 web 应用会在不同的页面中使用相同的布局方式，因此可以很方便地定义单个 Blade 布局视图：
~~~
<!-- 文件保存于 resources/views/layouts/app.blade.php -->
<html>
<head>
<title>应用程序名称 - @yield('title')</title>
</head>
<body>
@section('sidebar')
这是主布局的侧边栏。
@show
<div class="container">
@yield('content')
</div>
</body>
</html>
~~~
如你所见，该文件包含了典型的 HTML 语法。不过，请注意 `@section` 和 `@yield` 命令。顾名思义，`@section`命令定义了视图的一部分内容，而 `@yield` 指令是用来显示指定部分的内容。
现在，我们已经定义好了这个应用程序的布局，接下来，我们定义一个继承此布局的子页面。
### 继承布局
当定义子视图时，你可以使用 Blade 提供的 `@extends` 命令来为子视图指定应该 「继承」 的布局。 继承 Blade 布局的视图可使用 `@section` 命令将内容注入于布局的 `@section` 中。而「主」布局中使用 `@yield` 的地方会显示这些子视图中的 `@section` 间的内容：
~~~
<!-- 文件保存于 resources/views/layouts/child.blade.php -->
@extends('layouts.app')
@section('title', 'Page Title')
@section('sidebar')
@parent
<p>这将追加到主布局的侧边栏。</p>
@endsection
@section('content')
<p>这是主体内容。</p>
@endsection
~~~
在上面的例子里，`@section` 中的 `sidebar` 使用 `@parent` 命令在「主」布局的 `@section('sidebar')` 中增加内容（不是覆盖）。渲染视图时，`@parent` 指令会被替换为「主」布局中 `@section('sidebar')` 间的内容。
> {tip} 与上一个示例相反，此侧边栏部分以 `@endsection` 而不是 `@show` 结尾。 `@endsection` 指令只定义一个区块，而 `@show` 则是定义并立即生成该区块。
你也可以通过在路由中使用全局辅助函数 `view` 来返回 Blade 视图：
~~~
Route::get('blade', function () {
return view('child');
});
~~~
## Components & Slots
Components 和 slots 类似于布局中的 `@section`，但其使用方式更容易使人理解。首先，假设我们有一个能在整个应用程序中被重复使用的「警告」组件:
~~~
<!-- /resources/views/alert.blade.php -->
<div class="alert alert-danger">
{{ $slot }}
</div>
~~~
`{{ $slot }}` 变量将包含我们希望注入到组件的内容。然后，我们可以使用 Blade 命令 `@component` 来构建这个组件：
~~~
@component('alert')
<strong>Whoops!</strong> Something went wrong!
@endcomponent
~~~
有时为组件定义多个 slots 是很有帮助的。现在我们要对「警报」组件进行修改，让它可以注入「标题」。通过简单地 「打印」匹配其名称的变量来显示被命名的 `@slot` 之间的内容：
~~~
<!-- /resources/views/alert.blade.php -->
<div class="alert alert-danger">
<div class="alert-title">{{ $title }}</div>
{{ $slot }}
</div>
~~~
现在，我们可以使用 `@slot` 指令注入内容到已命名的 slot 中，任何没有被 `@slot` 指令包裹住的内容将传递给组件中的 `$slot` 变量:
~~~
@component('alert')
@slot('title')
Forbidden
@endslot
你没有权限访问这个资源！
@endcomponent
~~~
#### 向组件传递数据
需要向组件传递数据时，可以给 `@component` 指令的第二个参数传入一个数组。数组里的数据将在组件模板以变量的形式生效：
~~~
@component('alert', ['foo' => 'bar'])
...
@endcomponent
~~~
#### 组件别名
子目录中的 Blade 组件，使用别名更方便访问。现在，有一个 Blade 组件存储在 `resources/views/components/alert.blade.php`，可以使用 `component` 方法给它起个 `alert` 的别名。通常，在`AppServiceProvider` 的 `boot` 方法中完成这个操作：
~~~
use Illuminate\Support\Facades\Blade;
Blade::component('components.alert', 'alert');
~~~
组件起好别名后，使用指令渲染：
~~~
@alert(['type' => 'danger'])
你无权访问！
@endalert
~~~
也可以不传参数：
~~~
@alert
你无权访问！
@endalert
~~~
## 显示数据
传入 Blade 视图的数据，通过双花括号包裹来显示。例如，给出如下路由：
~~~
Route::get('greeting', function () {
return view('welcome', ['name' => 'Samantha']);
});
~~~
这样显示 `name` 变量的内容：
~~~
Hello, {{ $name }}.
~~~
当然，不限于显示传入视图的变量内容，还可以输出 PHP 函数结果。实际上，可以在Blade echo 语句里放置任何 PHP 代码：
~~~
The current UNIX timestamp is {{ time() }}.
~~~
> {tip} Blade `{{ }}` 语句会自动调用 PHP的 `htmlspecialchars` 函数防止XSS 攻击。
#### 显示未转义数据
默认情况下，Blade `{{ }}` 语句会自动调用 PHP的 `htmlspecialchars` 函数防止 XSS 攻击。不想转义的话，可以使用以下语法：
~~~
Hello, {!! $name !!}.
~~~
> {note} 输出用户提供的数据时，千万要小心。对用户提供的数据，总是要使用双花括号进行显示，防止 XSS 攻击。
#### 渲染 JSON
有时，为了初始化 JavaScript 变量，需要将传入视图的数组进行 JSON 化。例如：
~~~
<script>
var app = <?php echo json_encode($array); ?>;
</script>
~~~
然而，可以用 `@json` Blade 指令替代手动`json_encode`：
~~~
<script>
var app = @json($array);
</script>
~~~
#### HTML 实体转换
默认情况下，Blade （和 Laravel 的 辅助函数 `e`） 会将 HTML 全部转换。要关闭全部转换，可以在 `AppServiceProvider` 的 `boot` 方法里调用 `Blade::withoutDoubleEncoding`：
~~~
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 引导应用服务.
*
* @return void
*/
public function boot()
{
Blade::withoutDoubleEncoding();
}
}
~~~
### Blade & JavaScript 框架
由于许多 JavaScript 框架也是用花括号来表示要显示在浏览器的表达式， 可以使用 `@` 符告诉 Blade 渲染引擎保持这个表达式不变。例如：
~~~
<h1>Laravel</h1>
Hello, @{{ name }}.
~~~
渲染后，Blade 引擎会把 `@` 符移除，但是 `{{ name }}` 表达式保留，从而让 JavaScript 框架去渲染它。
#### `@verbatim` 指令
如果模板中一大部分需要显示 JavaScript 变量，就可以用 `@verbatim` 指令包裹住 HTML，这样就不用在每个 Blade echo 语句前加 `@` 符：
~~~
@verbatim
<div class="container">
Hello, {{ name }}.
</div>
@endverbatim
~~~
## 流程控制
除了模板继承和数据显示外，Blade 还为常用的 PHP 流程控制提供了便捷语句，例如条件语句和循环语句。这些语句不但简洁，还与 PHP 语句相似。
### If 语句
使用 `@if`、`@elseif`、`@else` 和 `@endif` 指令构建 `if` 语句。这些指令与 PHP 对应：
~~~
@if (count($records) === 1)
我有一条记录！
@elseif (count($records) > 1)
我有好几条记录！
@else
我没有记录！
@endif
~~~
为方便起见，Blade 还提供了 `@unless` 指令：
~~~
@unless (Auth::check())
未登陆
@endunless
~~~
除了以上述指令，`@isset` 和 `@empty` 也可能用到，功能与 PHP 函数对应：
~~~
@isset($records)
// $records 已定义且不为 null
@endisset
@empty($records)
// $records 为空
@endempty
~~~
#### 认证指令
`@auth` 和 `@guest` 指令用来快速认证当前用户：
~~~
@auth
// 通过认证
@endauth
@guest
// 未通过认证
@endguest
~~~
必要的话，可以在 `@auth` 和 `@guest` 指令中指定 [认证看守器（Guard）](https://www.kancloud.cn/tonyyu/laravel_5_6/786216)：
~~~
@auth('admin')
// 通过认证
@endauth
@guest('admin')
// 未通过认证
@endguest
~~~
#### Section 指令
`@hasSection` 指令检查 section 是否有内容：
~~~
@hasSection('navigation')
<div class="pull-right">
@yield('navigation')
</div>
<div class="clearfix"></div>
@endif
~~~
### Switch 语句
可以使用 `@switch`、`@case`、`@break`、`@default` 和 `@endswitch` 指令来构建 Switch 语句：
~~~
@switch($i)
@case(1)
First case...
@break
@case(2)
Second case...
@break
@default
Default case...
@endswitch
~~~
### 循环
除了条件表达式外，Blade 也支持 PHP 的循环结构。同样，以下这些指令中的每一个都与其 PHP 对应的函数相同：
~~~
@for ($i = 0; $i < 10; $i++)
目前的值为 {{ $i }}
@endfor
@foreach ($users as $user)
<p>此用户为 {{ $user->id }}</p>
@endforeach
@forelse ($users as $user)
<li>{{ $user->name }}</li>
@empty
<p>没有用户</p>
@endforelse
@while (true)
<p>死循环了</p>
@endwhile
~~~
> {tip} 循环时，你可以使用 [循环变量](https://www.kancloud.cn/tonyyu/laravel_5_6/786198#_402) 来获取循环的信息，例如是否在循环中进行第一次或最后一次迭代。
当使用循环时，你也可以结束循环或跳过当前迭代：
~~~
@foreach ($users as $user)
@if ($user->type == 1)
@continue
@endif
<li>{{ $user->name }}</li>
@if ($user->number == 5)
@break
@endif
@endforeach
~~~
你还可以使用一行代码包含指令声明的条件：
~~~
@foreach ($users as $user)
@continue($user->type == 1)
<li>{{ $user->name }}</li>
@break($user->number == 5)
@endforeach
~~~
### 循环变量
循环时，可以在循环内使用 `$loop` 变量。这个变量可以提供一些有用的信息，比如当前循环的索引，当前循环是不是首次迭代，又或者当前循环是不是最后一次迭代：
~~~
@foreach ($users as $user)
@if ($loop->first)
这是第一个迭代。
@endif
@if ($loop->last)
这是最后一个迭代。
@endif
<p>This is user {{ $user->id }}</p>
@endforeach
~~~
在一个嵌套的循环中，可以通过使用 `$loop` 变量的 `parent` 属性来获取父循环中的 `$loop` 变量：
~~~
@foreach ($users as $user)
@foreach ($user->posts as $post)
@if ($loop->parent->first)
This is first iteration of the parent loop.
@endif
@endforeach
@endforeach
~~~
`$loop` 变量也包含了其它各种有用的属性：
| 属性 | 描述 |
| --- | --- |
| `$loop->index` | 当前循环迭代的索引（从0开始）。 |
| `$loop->iteration` | 当前循环迭代 （从1开始）。 |
| `$loop->remaining` | 循环中剩余迭代数量。 |
| `$loop->count` | 迭代中的数组项目总数。 |
| `$loop->first` | 当前迭代是否是循环中的首次迭代。 |
| `$loop->last` | 当前迭代是否是循环中的最后一次迭代。 |
| `$loop->depth` | 当前循环的嵌套级别。 |
| `$loop->parent` | 在嵌套循环中，父循环的变量。 |
### 注释
Blade 也能在视图中定义注释。然而，跟 HTML 的注释不同的，Blade 注释不会被包含在应用程序返回的 HTML 内：
~~~
{{-- 此注释将不会出现在渲染后的 HTML --}}
~~~
### PHP
在某些情况下，将 PHP 代码嵌入到视图中很有用。你可以使用 Blade 的 `@php` 指令在模板中执行一段纯 PHP 代码：
~~~
@php
//
@endphp
~~~
> {tip} 虽然 Blade 提供了这个功能，但频繁地使用意味着你的模版被嵌入了太多的逻辑。
## 引入子视图
你可以使用 Blade 的 `@include` 命令来引入一个已存在的视图，所有在父视图的可用变量在被引入的视图中都是可用的。
~~~
<div>
@include('shared.errors')
<form>
<!-- 表单内容 -->
</form>
</div>
~~~
被引入的视图会继承父视图中的所有数据，同时也可以向引入的视图传递额外的数组数据：
~~~
@include('view.name', ['some' => 'data'])
~~~
当然，如果尝试使用 `@include` 去引入一个不存在的视图，Laravel 会抛出错误。如果想引入一个可能存在或可能不存在的视图，就使用 `@includeIf` 指令:
~~~
@includeIf('view.name', ['some' => 'data'])
~~~
如果要根据给定的布尔条件 `@include` 视图，可以使用 `@includeWhen` 指令：
~~~
@includeWhen($boolean, 'view.name', ['some' => 'data'])
~~~
要包含来自给定数组视图的第一个视图，可以使用 `includeFirst` 指令：
~~~
@includeFirst(['custom.admin', 'admin'], ['some' => 'data'])
~~~
> {note} 请避免在 Blade 视图中使用 `__DIR__` 及 `__FILE__` 常量，因为它们会引用编译视图时缓存的位置。
### 为集合渲染视图
你可以使用 Blade 的 `@each` 命令将循环及引入写成一行代码：
~~~
@each('view.name', $jobs, 'job')
~~~
第一个参数是对数组或集合中的每个元素进行渲染的部分视图。第二个参数是要迭代的数组或集合，而第三个参数是将被分配给视图中当前迭代的变量名称。举个例子，如果你要迭代一个 `jobs` 数组，通常会使用子视图中的变量 `job` 来获取每个 `job`。当前迭代的 `key` 将作为子视图中的 `key` 变量。
你也可以传递第四个参数到 `@each` 命令。当需要迭代的数组为空时，将会使用这个参数提供的视图来渲染。
~~~
@each('view.name', $jobs, 'job', 'view.empty')
~~~
> {note} 通过 `@each` 渲染的视图不会从父视图继承变量。 如果子视图需要这些变量，则应该使用 `@foreach` 和 `@include`。
## 堆栈
Blade 可以被推送到在其他视图或布局中的其他位置渲染的命名堆栈。这在子视图中指定所需的 JavaScript 库时非常有用：
~~~
@push('scripts')
<script src="/example.js"></script>
@endpush
~~~
你可以根据需要多次压入堆栈，通过 `@stack` 命令中传递堆栈的名称来渲染完整的堆栈内容：
~~~
<head>
<!-- Head Contents -->
@stack('scripts')
</head>
~~~
## 服务注入
`@inject` 命令可用于从 Laravel [服务容器](https://www.kancloud.cn/tonyyu/laravel_5_6/786056) 中检索服务。传递给 `@inject` 的第一个参数为置放该服务的变量名称，而第二个参数是要解析的服务的类或是接口的名称：
~~~
@inject('metrics', 'App\Services\MetricsService')
<div>
Monthly Revenue: {{ $metrics->monthlyRevenue() }}.
</div>
~~~
## 拓展 Blade
Blade 甚至允许你使用 `directive` 方法来定义自定义指令。当 Blade 编译器遇到自定义指令时，它将使用指令包含的表达式调用提供的回调。
以下示例创建一个 `@datetime($var)` 伪指令，该伪指令格式化给定的 `DateTime` 实例 `$var`：
~~~
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
/**
* 执行注册后引导服务。
*
* @return void
*/
public function boot()
{
Blade::directive('datetime', function ($expression) {
return "<?php echo ($expression)->format('m/d/Y H:i'); ?>";
});
}
/**
* 在容器中注册绑定。
*
* @return void
*/
public function register()
{
//
}
}
~~~
如你所见，我们可以链式调用在指令中传递的任何表达式的 `format` 方法。所以，在这个例子里，该指令最终生成了以下 PHP 代码：
~~~
<?php echo ($var)->format('m/d/Y H:i'); ?>
~~~
> {note} 更新 Blade 指令的逻辑后，你需要删除所有已缓存的 Blade 视图。使用 Artisan 命令 `view:clear` 来清除被缓存的视图。
### 自定义 If 语句
编写自定义指令有时候比定义简单、常见的条件语句更复杂，但是它又非常必要。因此，Blade 提供了一个 `Blade::if`方法，它能使用闭包来快速定义自定义条件指令。 例如，定义一个自定义条件来检查当前的应用程序环境。我们可以在 `AppServiceProvider` 的 `boot` 方法中这样做：
~~~
use Illuminate\Support\Facades\Blade;
/**
* 执行服务的注册后引导。
*
* @return void
*/
public function boot()
{
Blade::if('env', function ($environment) {
return app()->environment($environment);
});
}
~~~
一旦你定义了自定义条件之后，就可以很轻松地在模板中使用它：
~~~
@env('local')
// 该应用在本地环境中...
@elseenv('testing')
// 该应用在测试环境中...
@else
// 该应用不在本地或测试环境中...
@endenv
~~~
- 前言
- 翻译说明
- 发行说明
- 升级指南
- 贡献导引
- 入门指南
- 安装
- 配置信息
- 文件夹结构
- Homestead
- Valet
- 部署
- 核心架构
- 请求周期
- 服务容器
- 服务提供者
- Facades
- Contracts
- 基础功能
- 路由
- 中间件
- CSRF 保护
- 控制器
- 请求
- 响应
- 视图
- URL
- Session
- 表单验证
- 错误
- 日志
- 前端开发
- Blade 模板
- 本地化
- 前端指南
- 编辑资源 Mix
- 安全相关
- 用户认证
- Passport OAuth 认证
- 用户授权
- 加密解密
- 哈希
- 重置密码
- 综合话题
- Artisan 命令行
- 广播系统
- 缓存系统
- 集合
- 事件系统
- 文件存储
- 辅助函数
- 邮件发送
- 消息通知
- 扩展包开发
- 队列
- 任务调度
- 数据库
- 快速入门
- 查询构造器
- 分页
- 数据库迁移
- 数据填充
- Redis
- Eloquent ORM
- 快速入门
- 模型关联
- Eloquent 集合
- 修改器
- API 资源
- 序列化
- 测试相关
- 快速入门
- HTTP 测试
- 浏览器测试 Dusk
- 数据库测试
- 测试模拟器
- 官方扩展包
- Cashier 交易工具包
- Envoy 部署工具
- Horizon
- Scout 全文搜索
- Socialite 社会化登录