Кастомные директивы Blade в Laravel

Blade — это встроенный шаблонизатор Laravel, который уже сам по себе мощный. Но добавление пользовательских директив делает его ещё гибче: вы можете инкапсулировать сложную логику, повысить читаемость шаблонов и избавиться от повторений.

Почему пользовательские директивы важны

Хотя Blade уже предоставляет базовые конструкции (@if, @foreach, @include и другие), в реальных проектах часто возникает ситуация, когда:

• в шаблонах повторяется логика;

• приходится клонировать однотипные вложения;

• сложный вывод оформляется прямо в представлении.

Пользовательские директивы позволяют вынести такую логику из .blade.php в одно место, что это делает код чище, проще в поддержке и легче читать.

Где регистрировать свои директивы

Лучшее место для регистрации метод boot() вашего сервиса-провайдера. Чаще всего это App\Providers\AppServiceProvider. Laravel гарантирует, что директивы будут доступны до рендеринга любых представлений.

Простые (inline) директивы

Inline-директивы — это те, которые возвращают одну строку PHP-кода.

Пример: форматирование валюты

Вместо повторяющихся вызовов number_format(...) в шаблонах можно создать свою директиву @currency.

use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::directive('currency', function ($expression) {
        return "<?php echo number_format($expression, 2); ?>";
    });
}

Теперь везде в шаблонах:

<p>Итого: @currency($order->total)</p>

Такой вызов выведет цену в удобочитаемом формате.

Блочные директивы для условий

Иногда нужно оборачивать целые блоки логики условием. Для этого используют метод Blade::if().

Пример: проверка роли администратора

use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Blade;

public function boot(): void
{
    Blade::if('admin', function () {
        return Auth::check() && Auth::user()->is_admin;
    });
}

Теперь в шаблонах:

@admin
    <button class="btn btn-danger">Удалить пользователя</button>
@endadmin

Под капотом это превращается в обычный PHP-if.

Директивы с параметрами

Можно передавать аргументы, чтобы директива была ещё гибче.

Пример: проверка роли

Blade::if('hasRole', function (string $role) {
    return auth()->check() && auth()->user()->role === $role;
});

Использование в шаблоне:

@hasRole('manager')
    <a href="/reports">Просмотр отчётов</a>
@endhasRole

Это удобно для сегментации UI по ролям пользователя.

Управление датами и форматами

Иногда надо форматировать дату в каждом шаблоне, и это можно оформить как директиву.

Пример стандартной директивы:

Blade::directive('datetime', function ($expression) {
    return "<?php echo ($expression)->format('d M Y, h:i A'); ?>";
});

Теперь:

Создано: @datetime($user->created_at)

Laravel подставит форматированную дату.

Лучшие практики по директивам

При разработке пользовательских директив стоит помнить:

• Держите директивы простыми и сфокусированными, они должны инкапсулировать мелкую логику отображения.

• Сложную бизнес-логику лучше выносить в сервисы или хелперы, а не в шаблоны.

• Если директива формирует сырые PHP-вставки, следите за безопасностью вывода.

• После добавления новых директив может потребоваться очистить кеш: php artisan view:clear.

Когда не стоит использовать директивы

• Если логика слишком сложная (например, большие циклы или запросы к базе).

• Если то же самое удобнее оформить через компонент или view composer.

• Если директива нарушает принцип разделения ответственности (presentation vs business).