Шаблоны Blade

Статистика: Символов — 15 358/12 963 без пробелов (9 300/8 018 без кода):, слов — 1 283
Разметка: Wiki
{{TOC}}

{{DOCVER 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15, 5.1=cdc24ba7426c5b11eb4d050706bd78c3ea4913cc 19.06.2016 20:08:01}}

== Введение ==
Blade - простой, но мощный шаблонизатор, поставляемый с Laravel. В отличие от других популярных шаблонизаторов для PHP Blade не ограничивает вас в использовании чистого PHP-кода в ваших представлениях. На самом деле все представления Blade скомпилированы в чистый PHP-код и кешированы, пока в них нет изменений, а значит, Blade практически не нагружает ваше приложение. Файлы представлений Blade используют расширение %%(t).blade.php%% и обычно хранятся в папке %%(t)resources/views%%.

== Наследование шаблонов ==

=== Определение макета ===
Два основных преимущества использования Blade - //наследование шаблонов// и //секции//. Для начала давайте рассмотрим простой пример. Во-первых, изучим макет "главной" страницы. Поскольку многие веб-приложения используют один общий макет для разных страниц, удобно определить этот макет как одно представление Blade:
%%
<!-- Хранится в resources/views/layouts/app.blade.php -->

<html>
  <head>
    <title>App Name - @yield('title')</title>
  </head>
  <body>
    @section('sidebar')
      Это главная боковая панель.
    @show

    <div class="container">
      @yield('content')
    </div>
  </body>
</html>
%%

Как видите, этот файл имеет типичную HTML-разметку. Но обратите внимание на директивы %%(t)@section%% и %%(t)@yield%%. Директива %%(t)@section%%, как следует из её названия, определяет секцию содержимого, а директива %%(t)@yield%% используется для отображения содержимого данной секции.

Мы определили макет для нашего приложения, давайте определим дочернюю страницу, которая унаследует макет.

=== Наследование макета ===
При определении дочернего представления используйте Blade-директиву %%(t)@extends%% для указания макета, который должен быть "унаследован" дочерним представлением. Представления, которые наследуют макет Blade, могут внедрять содержимое в секции макета с помощью директив %%(t)@section%%. Запомните, как видно из приведённого выше примера, содержимое этих секций будет отображено в макете при помощи %%(t)@yield%%:
%%
<!-- Хранится в resources/views/child.blade.php -->

@extends('layouts.app')

@section('title', 'Page Title')

@section('sidebar')
    @parent

    <p>Это дополнение к основной боковой панели.</p>
@endsection

@section('content')
    <p>Это содержимое тела страницы.</p>
@endsection
%%

В этом примере секция %%(t)sidebar%% использует директиву %%(t)@parent%% для дополнения (а не перезаписи) содержимого к боковой панели макета. Директива %%(t)@parent%% будет заменена содержимым макета при отрисовке представления.

Blade-представления могут быть возвращены из маршрутов при помощи глобальной вспомогательной функции %%view()%%:
%%
Route::get('blade', function () {
  return view('child');
});
%%

== Отображение данных ==
Вы можете отобразить данные, переданные в ваши Blade-представления, обернув переменную в фигурные скобки. Например, для такого маршрута:
%%
Route::get('greeting', function () {
  return view('welcome', ['name' => 'Samantha']);
});
%%

Вы можете отобразить содержимое переменной %%(t)name%% вот так:
%%
Hello, {{ $name }}.
%%

Вы не ограничены отображением только содержимого переменных, передаваемых в представление. Вы также можете выводить результаты любых PHP-функций. На самом деле, вы можете поместить любой необходимый PHP-код в оператор вывода Blade:
%%
The current UNIX timestamp is {{ time() }}.
%%

.(alert)
Blade-оператор %%{{ }}%% автоматически отправляется через PHP-функцию %%htmlentities()%% для предотвращения XSS-атак.

**Вывод переменных после проверки на существование**

Иногда вам надо вывести значение переменной, но вы не уверены, задано ли оно. То есть вы хотите сделать так:
%%
{{ isset($name) ? $name : 'Default' }}
%%

Вместо написания тернарного оператора Blade позволяет вам использовать такое удобное сокращение, которое будет скомпилировано в тернарный оператор, приведённый ранее:
%%
{{ $name or 'Default' }}
%%

Если переменная %%(t)$name%% имеет значение, то оно будет отображено, иначе будет выведено слово %%(t)Default%%.

**Вывод неэкранированных данных**

По умолчанию Blade-оператор %%{{ }}%% автоматически отправляется через PHP-функцию %%htmlentities()%% для предотвращения XSS-атак. Если вы не хотите экранировать данные, используйте такой синтаксис:
%%
Hello, {!! $name !!}.
%%

.(alert)
Будьте очень осторожны и экранируйте переменные, которые содержат ввод от пользователя. Всегда используйте экранирование синтаксисом с двойными скобками, чтобы предотвратить XSS-атаки при отображении предоставленных пользователем данных.

.(tl_note)
Как показывает практика, вместо экранирования только пользовательских переменных безопаснее экранировать весь вывод, делая исключения только в редких случаях — прим. пер.

=== Blade и JavaScript-фреймворки ===
Поскольку многие JavaScript-фреймворки тоже используют фигурные скобки для обозначения того, что данное выражение должно быть отображено в браузере, то вы можете использовать символ %%(t)@%%, чтобы указать механизму отрисовки Blade, что выражение должно остаться нетронутым. Например:
%%
<h1>Laravel</h1>

Hello, @{{ name }}.
%%

В этом примере Blade удалит символ %%(t)@%%, но выражение %%{{ name }}%% останется нетронутым, что позволит вашему JavaScript-фреймворку отрисовать его вместо Blade.

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
**Директива %%@verbatim%%**

Если вы выводите JavaScript-переменные в большой части вашего шаблона, вы можете обернуть HTML директивой %%@verbatim%%, тогда вам не нужно будет ставить символ %%@%% перед каждым оператором вывода Blade:
~%%
@verbatim
  <div class="container">
    Hello, {{ name }}.
  </div>
@endverbatim
~%%
%%

== Управляющие конструкции ==
В дополнение к наследованию шаблонов и отображению данных Blade предоставляет удобные сокращения для распространенных управляющих конструкций PHP, таких как условные операторы и циклы. Эти сокращения обеспечивают очень чистый и краткий способ работы с управляющими конструкциями PHP и при этом остаются очень похожими на свои PHP-прообразы. 

=== Оператор If ===
Вы можете конструировать оператор %%if%%  при помощи директив %%@if%%, %%@elseif%%, %%@else%% и %%@endif%%. Эти директивы работают идентично своим PHP-прообразам:
%%
@if (count($records) === 1)
  Здесь есть одна запись!
@elseif (count($records) > 1)
  Здесь есть много записей!
@else
  Здесь нет записей!
@endif
%%

Для удобства Blade предоставляет и директиву %%@unless%%:
%%
@unless (Auth::check())
    Вы не вошли в систему.
@endunless
%%

%%(DOCNEW 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
Также вы можете определить, есть ли содержимое в данной секции макета, с помощью директивы %%@hasSection%%:
~%%
<title>
  @hasSection ('title')
    @yield('title') - Название приложения
  @else
    Название приложения
  @endif
</title>
~%%
%%

=== Циклы ===
В дополнение к условным операторам 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
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
.(alert)
При работе с циклами вы можете использовать ((#переменная переменную loop)) для получения полезной информации о цикле, например, находитесь ли вы на первой или последней итерации цикла.

При работе с циклами вы также можете закончить цикл или пропустить текущую итерацию:
~%%
@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
~%%
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51)
=== Переменная Loop ===
При работе с циклами внутри цикла будет доступна переменная %%$loop%%. Эта переменная предоставляет доступ к некоторым полезным данным, например, текущий индекс цикла, или находитесь ли вы на первой или последней итерации цикла:
~%%
@foreach ($users as $user)
  @if ($loop->first)
    Это первая итерация.
  @endif

  @if ($loop->last)
    Это последняя итерация.
  @endif

  <p>Это пользователь {{ $user->id }}</p>
@endforeach
~%%

Если вы во вложенном цикле, вы можете обратиться к переменной %%$loop%% родительского цикла через свойство %%parent%%:
~%%
@foreach ($users as $user)
  @foreach ($user->posts as $post)
    @if ($loop->parent->first)
      Это первая итерация родительского цикла.
    @endif
  @endforeach
@endforeach
~%%

Переменная %%$loop%% содержит также множество других полезных свойств:
%%(hvlraw)
  <table>
    <thead>
      <tr>
        <th>Свойство</th>
        <th>Описание</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>$loop->index</td>
        <td>Индекс текущей итерации цикла (начинается с 0).</td>
      </tr>
      <tr>
        <td>$loop->iteration</td>
        <td>Текущая итерация цикла(начинается с 1).</td>
      </tr>
      <tr>
        <td>$loop->remaining</td>
        <td>Число оставшихся итераций цикла.</td>
      </tr>
      <tr>
        <td>$loop->count</td>
        <td>Общее число элементов итерируемого массива.</td>
      </tr>
      <tr>
        <td>$loop->first</td>
        <td>Первая ли это итерация цикла.</td>
      </tr>
      <tr>
        <td>$loop->last</td>
        <td>Последняя ли это итерация цикла.</td>
      </tr>
      <tr>
        <td>$loop->depth</td>
        <td>Уровень вложенности текущего цикла.</td>
      </tr>
      <tr>
        <td>$loop->parent</td>
        <td>Переменная loop родительского цикла, для вложенного цикла.</td>
      </tr>
      <tr>
        <td></td>
        <td></td>
      </tr>
    </tbody>
  </table>
~%%

=== Комментарии ===
Blade также позволяет вам определить комментарии в ваших представлениях. Но в отличие от HTML-комментариев, Blade-комментарии не включаются в HTML-код, возвращаемый вашим приложением:
~%%
{{-- Этого комментария не будет в итоговом HTML --}}
~%%

=== PHP ===
В некоторых случаях бывает полезно встроить PHP-код в ваши представления. Вы можете использовать Blade-директиву %%@php%% для выполнения блока чистого PHP в вашем шаблоне:
~%%
    @php
        //
    @endphp
~%%

.(alert)
Несмотря на то, что в Blade есть эта возможность, её частое использование может быть сигналом того, что у вас слишком много логики, встроенной в шаблон.
%%

== Включение подшаблонов ==
Blade-директива %%(t)@include%% позволяет вам включать Blade-представление в другое представление. Все переменные, доступные родительскому представлению, будут доступны и включаемому представлению:
%%
<div>
  @include('shared.errors')

  <form>
    <!-- Содержимое формы -->
  </form>
</div>
%%

Хотя включаемое представление унаследует все данные, доступные родительскому представлению, вы также можете передать в него массив дополнительных данных:
%%
@include('view.name', ['some' => 'data'])
%%

Само собой, если вы попробуете сделать %%@include%% представления, которого не существует, то Laravel выдаст ошибку. Если вы хотите включить представление, которого может не существовать, вам надо использовать директиву %%@includeIf%%:
%%
@includeIf('view.name', ['some' => 'data'])
%%

.(alert)
Вам следует избегать использования констант %%(t)__DIR__%% и %%(t)__FILE__%% в ваших Blade-представлениях, поскольку они будут ссылаться на расположение кешированных, скомпилированных представлений.

=== Отрисовка представлений для коллекций ===

Вы можете комбинировать циклы и включения в одной строке при помощи Blade-директивы %%(t)@each%%:
%%
@each('view.name', $jobs, 'job')
%%

Первый аргумент - часть представления, которую надо отрисовать для каждого элемента массива или коллекции. Второй аргумент - массив или коллекция для перебора, а третий - имя переменной, которое будет назначено для текущей итерации в представлении. Например, если вы перебираете массив %%(t)jobs%%, то скорее всего захотите обращаться к каждому элементу как к переменной %%(t)job%% внутри вашей части представления. Ключ для текущей итерации будет доступен в виде переменной %%(t)key%% в вашей части представления.

Вы также можете передать четвёртый аргумент в директиву %%(t)@each%%. Этот аргумент определяет представление, которое будет отрисовано, если данный массив пуст.
%%
@each('view.name', $jobs, 'job', 'view.empty')
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
== Стеки ==
Blade позволяет использовать именованные стеки, которые могут быть отрисованы где-нибудь ещё в другом представлении или макете. Это удобно в основном для указания любых JavaScript-библиотек, требуемых для ваших дочерних представлений:
~%%
@push('scripts')
  <script src="/example.js"></script>
@endpush
~%%

"Пушить" в стек можно сколько угодно раз. Для отрисовки всего содержимого стека передайте имя стека в директиву %%@stack%%:
~%%
<head>
  <!-- Содержимое заголовка -->

  @stack('scripts')
</head>
~%%
%%

== Внедрение сервисов ==
Директива %%(t)@inject%% служит для извлечения сервиса из ((/docs/v5/container сервис-контейнера)) Laravel. Первый аргумент, передаваемый в %%(t)@inject%%, это имя переменной, в которую будет помещён сервис. А второй аргумент - имя класса или интерфейса сервиса, который вы хотите извлечь:
%%
@inject('metrics', 'App\Services\MetricsService')

<div>
  Месячный доход: {{ $metrics->monthlyRevenue() }}.
</div>
%%

== Наследование Blade ==
Blade позволяет вам определять даже свои собственные директивы с помощью метода %%directive()%%. Когда компилятор Blade встречает пользовательскую директиву, он вызывает предоставленный обратный вызов с содержащимся в директиве выражением.

Следующий пример создаёт директиву %%@datetime($var)%%, которая форматирует данный %%$var%%, который должен быть экземпляром %%(t)DateTime%%:
%%
<?php

namespace App\Providers;

use Illuminate\Support\Facades\Blade;
//для версии 5.2 и ранее:
//use 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'); ?>
%%

%%(DOCNEW 5.3=c06d6a2352ed8c767633aab9c20f2bf7d880c967 28.01.2017 5:00:51, 5.2=6b0b057ae6de3c88cb29188459e38383c622ec23 8.12.2016 23:00:15)
.(alert)
После изменения логики директивы Blade вам надо удалить все кешированные представления Blade. Это можно сделать Artisan-командой %%(sh)view:clear%%.
%%