Использование токенов (шорткодов) для строк в Laravel

Введение

При разработки веб-сайтов и приложений, довольно часто возникает необходимость динамического формирование строк контента. Решается это по разному, кто то использует str_replace(), кто то делает поиск и замену с помощью регулярок, а кто то использует другие способы.

Вот, например, несколько таких задач:

• Генерация названий сущностей на сайте при их сохранении в БД (имя статьи, название категории)
• Генерация и вывод СЕО метатегов на страницах
• Шаблоны email писем и других типов уведомлений
• Генерация url-путей, слагов
• Динамическая генерация и вывод другого контента по заданному шаблону

В известных CMS, эти задачи решаются с использованиям так называемых токенов (Drupal) или шорткодов (WordPress) или "жетонов".

Однозначного определения "токена" нет. Мы же это определим так:

Токены (шорткоды) — это специальные конструкции, фрагменты в текстовых строках, "контейнер с данными", которые после обработки, автоматически заменяются на нужный нам текст.

Решение

Для работы с токенами в Laravel, мы будем использовать следующий пакет laravel-str-tokens
Чтобы его применять в нашем проекте, будем использовать фасад StrToken.
Установка и настройка пакета очень проста, описана в документации на github.

Рассмотрим, для начала, пример: нам нужно сохранить статью в БД. Название статьи должно содержать само имя статьи, имя автора и текущая дата. Допустим, имя статьи пользователь задает вручную, а система с помощью токенов добавляет к этому имени, имя автора и дату. Зададим шаблон и сформируем строку с нужным полным названием статьи:

    public function store(Request $request)     {         $name = StrToken::setText($request->name . '[user:name]-[date:short]')             ->setDate(\Carbon\Carbon::now())             ->setEntity(Auth::user())             ->replace();         // сохраняем статью с $name в БД     }

В нашей строке есть конструкция [user:name]-[date:date] — это и есть наши токены — подстроки, обернутые в квадратные скобки “[ ]”. Сущность (обьект, модель) и его поле (метод, параметр) разделяются двоеточием “:”
[user:name] — user — имя Eloquent модели, name — поле этой модели
[date:short] — date — объект даты Carbon, short — это формат даты

Фасад StrToken имеет следующие методы:

• setText(string) — принимает строку, в которой нужно найти и заменить токены
• setDate(Carbon) — принимает объект даты Carbon. При использовании мы пишем токен выда [date:short], [date:time], [date:date]… — шаблон результата можно задать в конфигурационном файле пакета
• setEntity(Eloquent) — принимает объект модели Eloquent. При использовании название класса модели и название первой части токена должны совпадать, например Article & [article:name]
• setEntities(array) — аналогично как setEntity, только уже принимает ассоциативный массив Eloquent моделей, например: [‘user1’ => User::find(1), ‘user2’ => User::find(2), ‘node’ => Page::first()]
  и примеры строк с токенами: [‘user1:name’],[‘user2:city:name],[‘node:title’]
• setVar(string, string) — принимает два аргумента — ключ и его значение
• setVars(array) — сюда кидаем ассоциативный массив переменных. Токен в строке записываем по аналогии как выше, например [var:length], [var:price]
• replace():string — заменить токены в строке и получить результат

Также, есть возможность использовать токены для получения значений конфигов Laravel, используя токены вида:
[config:app.name], [config:mail.from.address],…

Задать шаблоны защищенных конфигов возможно в конфигурационном файле пакета, например, чтобы скрыть пароли, токены своих сервисов и т.д.

Приведем еще один пример работы с токенами разного типа:

$str = StrToken::setText('     Example str with tokens for article: "[article:title]([article:id])",     Article created at date: [article:created_at],     Author: [article:user:name]([article:user:id]).     User: [article:user:email], [article:user:city:country:title], [article:user:city:title].     Generated token at: [config:app.name], [date:raw]     [article:test:Hello]!!!     Length: [var:length];     Width: [var:width];     Price: [var:price] ')->setDate(\Carbon\Carbon::tomorrow())     ->setEntity(\App\Model\Article::findOrFail(13))     ->setVars(['length' => '2.2 m.', 'width' => '3.35 m.'])     ->setVar('price', '$13')     ->replace();

В результате мы получим слудующую строку:

Example str with tokens for article: "Test article title(23)", Article created at date: 15.07.2018, Author: Taylor Otwell(1), User: taylorotwell@gmail.com, AR, Little Rock. Generated token at: Laravel, 2018-10-27 00:00:00 TEST TOKEN:Hello!!!  Length: 2.2 m.; Width: 3.35 m.; Price: $13

Как выше могли заметить, пакет поддерживает использование связей между моделями и может с ними отлично работать: [user2:city:name].

Итоги

Можно с уверенностью сказать, что применение пакета https://github.com/fomvasss/laravel-str-tokens, очень упрощает многие аспекты работы и ускоряет процесс разработки веб-приложений на Laravel, где нужно генерировать текстовый строки, создавать шаблоны.

В следующей статьи, планируестя показать, как добавлять собственные кастомные методы для построения своих токенов для Eloquent моделей и как можно использовать токены для связанных моделей.