[ZoomX] Файловые плагины, markdown, кэширование сниппетов

Привет, друзья! Наконец я выпустил новую версию ZoomX. Эта версия минорная, но в ней много заслуживающего внимания. Расскажу о самом интересном:

• Файловые плагины.
• Модификатор markdown.
• Механизм кэширования сниппетов.
• Короткие имена контроллеров в роутах.
• Упрощённый вариант переадресации в роутах.
• Событие «OnBeforeRouteProcess».
• Доработана функция jsonx.
• Функционал контейнера.

Файловые плагины

Возможно не все знают, но я уже решал эту задачу в своём дополнении Middlewares. В ZoomX я предлагаю доработанную версию файловых плагинов. Давайте познакомимся с ними.
Файловые плагины в отличие от файловых сниппетов представляют собой классы. Вот пример такого плагина.

<?php
//  core/elements/plugins/MyPlugin.php

class MyPlugin extends \Zoomx\Elements\Plugin
{
    // События и приоритеты.
    public static $events = [
        'OnMODXInit' => -101,
        'OnHandleRequest' => 0,
    ];
    public $disabled = false;

    
    public function OnMODXInit($scriptProperties = [])
    {
        // ...
    }
    
    public function OnHandleRequest()
    {
        // ...
    }
}

Как видите, названия методов совпадают с названиями событий. Таким образом, один класс содержит функционал для разных событий в отличие от того же Laravel, где для каждого события создаётся отдельный класс. В свойстве $events указываются события, которые должны сработать. Это добавляет гибкости, так как можно запускать только указанные события. Также плагин можно отключить с помощью свойства $disabled.

Ещё хотелось бы отметить, что данный механизм легко подхватывает файловые элементы компонентов (если авторы их используют).

Модификатор markdown

Тут всё просто. Пригодится для тех, кто привык работать с этим форматом.

...
{'content'|resource|markdown}
...

Механизм кэширования сниппетов

Сейчас MODX предлагает следующую логику кэширования — или сниппет никогда не кэшируется или кэшируется с сохранением результата на странице. Т.е. или он будет вызыватся при каждом запросе, или после первого выполнения он будет заменён на результат и больше работать не будет. Но этих вариантов бывает недостаточно. Приходилось писать сниппеты-обёртки, которые сохраняли результат на определённое время. Теперь это можно сделать прямо из коробки. В теге сниппета в атрибуте cache_lifetime нужно указать количество секунд для хранения результата в кэше.

{'name'|snippet:[...] cache_lifetime=3600 nocache}

Короткие имена контроллеров в роутах

Если все контроллеры находятся в одном пространстве имён, то зачем постоянно их указывать. Теперь в системной настройке zoomx_controller_namespace можно указать неймспейс контроллеров, а в роутах писать только имя класса.

$router->get('uri', ['MyController', 'method']); // Преобразуется в Zoomx\Controllers\MyController

Упрощённый вариант переадресации в роутах

Если для переадресации не нужны никакие проверки, то можно воспользоваться специальным методом redirect маршрутизатора.

$router->redirect('uri_from', 'uri_to');
// С указанием кода
$router->redirect('uri_from', 'uri_to', 301);

Переадресовывать можно и роуты с масками. В URI переадресации нужно указать соответствующую переменную со знаком $ в фигурных скобках.

$router->redirect('articles/{id}', 'posts/{$id}');

Событие «OnBeforeRouteProcess»

Данное событие сработает перед вызовом хандлера роута (контроллера или фукнции). В нем можно выполнить определённые проверки и изменить стандартное поведение. Например, можно взять из роута id объекта (ресурса, пользователя и т.д) и в плагине получить соответствущий объект. Таким образом в методе контроллера будет уже не id, а готовый объект.

Функция jsonx

За доработку этой функции можно поблагодарить @Николай Савин. Для удобства в эту функцию добавлен третий параметр для указания HTTP кода ответа.

$router->get('uri', function() {
    // получение данных
    ...
    
    return jsonx($array, $headers, 201); // Код ответа: 201 Created
});

Если код статуса будет меньше 400, то свойство success, указывающее об успешности запроса, будет равно true.

{
  success: true,
  data: {
      foo: "bar"
  },
  meta: {
  	total_time: "0.0123 s",
  	query_time: "0.0000 s",
  	php_time: "0.0123 s",
  	queries: 1,
  	memory: "2 048 kb"
  }
}

Для кода 400 и выше признак успешности будет false, а данные по ошибке будут в свойстве errors:

{
  success: false,
  data: {},
  errors: {
      foo: "bar" // данные из функции jsonx
  },
  meta: {
  	...
  }
}

А если включён обработчик ошибок ZoomX (по-умолчанию включён), то и все ошибки PHP и исключения будут также отдаваться в этом формате.

...
errors: {
    "code": 500,
    "title": "Error 500: Internal Server Error",
    "message": "Сообщение об ошибке"
  },
...

Функционал контейнера

Ещё в главный сервис была добавлена возможность сохранять данные для последующего использования. Это часть функционала DI контейнера. Это промежуточная ступень к внедрению полноценного DI контейнера если появится потребность.
Сохранить в контейнер

zoomx()->set('foo', $object);
// или так
zoomx(['foo' => $object]);

Затем в любом месте приложения можно получить сохранённую переменную.

$object = zoomx('foo');

Заключение

Я опустил все технические подробности. Кому они интересны прошу сюда.
В общем, пробуйте, пишите чего не хватает, что доработать. У меня самого ещё много планов на этот компонент. И по функционалу и серию уроков снять. Надеюсь, в следующем году их все реализовать. Всех с Наступающим!