modHelpers

Версия 3.5.1-beta
Внимание! Этот компонент требует версию PHP 5.5 и выше!

modHelpers - это библиотека функций, которые доступны в глобальном контексте. Их можно использовать и сниппетах, и в плагинах, и в классах. Для плагинов есть ограничение - функции для работы с текущим документом доступны только после события OnLoadWebDocument.

В данный момент она содержит следующие функции:

Функции логирования

Классы

Расширение библиотеки

Все классы библиотеки можно расширять. Для этого нужно указать название нового класса в соответствующий системной настройке:

  • modhelpers_cacheManagerClass — новый класс менеджера кэша.
  • modhelpers_collectionClass — новый класс коллекции.
  • modhelpers_containerClass — новый класс контейнера.
  • modhelpers_loggerClass — новый класс логера.
  • modhelpers_mailerClass — новый класс мейлера.
  • modhelpers_modelBuilderClass — новый класс билдера модели.
  • modhelpers_modelColumnClass — класс колонок модели.
  • modhelpers_objectClass — класс менеджера объектов.
  • modhelpers_queryClass — класс менеджера SQL запросов.
  • modhelpers_requestClass — класс менеджера HTTP запросов.
  • modhelpers_varDumperClass — класс для вывода дампа переменных.
  • modhelpers_optionalClass — класс расширяющий Optional класс.
  • modhelpers_stringClass — класс вместо класс Str.

Функции библиотеки

abort()

Функция выводит страницу ошибок и является обёрткой над $modx->$modx->sendUnauthorizedPage() и $modx->$modx->sendErrorPage().

Агрумент функции:

  • array|integer Опции. Указывается массив опций для вывода страниц ошибок или response code (401, 403, 404). Необязательный.
// Выводит страницу ошибки для неавторизованных пользователей, указанную в параметре unauthorized_page
abort(401);  // или 403
// Выводит страницу, указанную в параметре error_page
abort(404); // аналогично вызову без параметра - abort()

app()

Функция для работы с контейнером. Используется для разрешения зависимостей и хранения данных.

Агрументы функции:

  • string Ключ зависимости. Можно указать или псевдоним или имя класса. Необязательный.
  • array Параметры, которые будут использованы при разрешении зависимости. Необязательный.

Если вызывать функцию без параметров, то она вернёт объект контейнера.

array_empty()

Эта функция проверяет, является ли указанная переменная пустым массивом.

// Вместо
if (empty($var) && is_array($var)) {}
// Пишем
if (array_notempty($var)) {}

array_ltrim()

Применяет функцию ltrim для массивов любой размерности.

Параметры функции:

  • array Массив. Обязательный.
  • string Символы для удаления. Необязательный.

array_notempty()

Эта функция проверяет, является ли указанная переменная непустым массивом. Имейте ввиду, что эта функция не одно и тоже, что и !array_empty().

// Вместо
if (!empty($var) && is_array($var)) {}
// Пишем
if (array_notempty($var)) {}

array_rtrim()

Применяет функцию rtrim для массивов любой размерности.

Параметры функции:

  • array Массив. Обязательный.
  • string Символы для удаления. Необязательный.

array_trim()

Применяет функцию trim для массивов любой размерности.

Параметры функции:

  • array Массив. Обязательный.
  • string Символы для удаления. Необязательный.
$array = array(
    'key1' => '/    Value 1 ',
    'key2' => '  Value 2      /',
    'key3' => array(
        '       Sub Array Value 1    ', 
        '/  Sub Array Value 2/'
    )
);
// Указываем удаляемые символы. Если не указать, то будут удалены только пробелы.
return array_trim($array, ' /');
// Результат
Array
(
    [key1] => 'Value 1'
    [key2] => 'Value 2'
    [key3] => Array
        (
            [0] => 'Sub Array Value 1'
            [1] => 'Sub Array Value 2'
        )
)

cache()

Используется для работы с кэшем MODX. Если вызвать без аргументов, то вернётся объект специального класса-декоратора текущего менеджера кэша.

Агрументы функции:

  • string|array Ключ. Название файла, в котором будет хранится кэш. Тип аргумента влияет на режим работы функции. Строка - получить данные из кэша, массив - сохранить данные в кэш. Необязательный.
  • integer|string|array Параметры. Число обозначает количество секунд для хранения, строка - название папки (раздел) кэша, массив используется для задания нескольких параметров. Необязательный.

Сохранить данные в кэш через аргументы

Для этого первым аргументом нужно передать массив array('key'=>'Данные'). Ключ должен быть строковым, так как используется для названия файла. А данные могут быть любого типа. Вторым параметром можно передать:

  • Массив с опциями (возможные значения опций перечислены в конце описания функции).
  • Название папки.
  • Время хранения кэша в секундах.
// Сохранить в кэш в папку core/cache/default
cache(['key' => 'Данные']);
// Сохранить в кэш в папку core/cache/my_data
$options = array(
    xPDO::OPT_CACHE_KEY = 'my_data'
)
cache(['key' => 'Данные'], $options);
// или так
cache(['key' => 'Данные'], 'my_data');

Сохранить данные в кэш через кэш-менеджера

В этом случае функцию нужно вызывать без аргументов и использовать метод set(). Первым аргументом передаётся ключ. Вторым - данные. Третим параметром в базовом методе modCacheManager::set() указывается время жизни кэша, а четвёртым - массив опций. Класс-декоратор немного меняет логику работы кэш-менеджера. Третим параметром можно передать:

  • Массив с опциями. В данном случае четвёртый параметр не нужен.
  • Время хранения кэша в секундах. Четвёртый параметр используется.
  • Название папки. Четвёртый параметр не нужен.
// Работаем с объектом кэш менеджера
cache()->set('key', 'Данные'); // Третий параметр можно не указывать
// Сохранить в кэш в папку cache/my_data
$options = array(
    xPDO::OPT_CACHE_KEY = 'my_data'
)
cache()->set('key', 'Данные', 0, $options);
// или так
cache()->set('key', 'Данные', $options);
// или так
cache()->set('key', 'Данные', 'my_data');
// или с указанием времени жизни
cache()->set('key', 'Данные', 7200, 'my_data');

Возвращается признак успешности выполнения операции.

Важно знать!

При сохранении любого объекта в админке кэш очищается и том числе папка default. Если вы хотите, чтобы ваши данные не удалялись при очищении кэша, сохраняйте их в отдельную папку.

Получить значение из кэша

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

// Самый простой вариант. Файл с данными в папке core/cache/default
$value = cache('key');

// Получить значение из кэша 
$options = array(
    xPDO::OPT_CACHE_KEY = 'my_data' // Папка с данными 
)
$value = cache('key', $options);
// или так
$value = cache('key', 'my_data');

// Получить значение из кэша через менеджера кэширования
$value = cache()->get('key', $options);
// или так
$value = cache()->get('key', 'my_data');

Одновременное получение и сохранение данных в кэш

Иногда нужно получить значение из кэша, и если кэш пустой, то рассчитать данные и сохранить их в кэш. Сделать это можно используя функцию remember(). Она похожа на функцию get(), но третьим параметром передаётся замыкание, которое должно вернуть значение для дальнейшего сохранения в кэш:

cache()->remember('count_users', 300, function() use ($modx) {
    return $modx->getCount('modUser', array('active' => 1));
});

Удалить полученные данные из кэша

Этот метод совмещает 2 функции - get() и delete(). После того, как данные получены, они удаляются из кэша.

$value = cache()->pull('key', $options);

Удалить значение из кэша

Удалить значение можно только используя метод delete() кэш менеджера. Первым параметром передаётся ключ, а вторым можно передать массив опций или имя раздела (папки). Возвращается признак успешности выполнения операции.

// Удалить значение из кэша, который хранится в папке cache/my_data
cache()->delete('ключ', 'my_data');

Возможные значения опций

  • xPDO::OPT_CACHE_KEY - Папка (partition), в которую будет записан файл с данными.
  • xPDO::OPT_CACHE_HANDLER - Для каждого партишена можно указать свой кэшер.
  • xPDO::OPT_CACHE_EXPIRES: - Время жизни по-умолчанию.

Подробнее про кэширование в MODX вы можете узнать в моей статье.

can()

Проверяет указанные права для текущего пользователя. Короткий синтаксис метода $modx->hasPermission().

Функция принимает один параметр:

  • string Права. Обязательный.
if (can('view')) {
    // Права на просмотр есть
} else {
    // Прав нет
}

children()

Выводит id дочерних ресурсов ресурса для указанного уровня в виде массива.

Параметры функции:

  • integer Id ресурса. Обязательный.
  • integer Уровень. По-умолчанию 10. Необязательный.
  • array Опции. Необязательный.
$id = 10; 
$depth = 3;
$children = children($id, $depth);

chunk()

Эта функция расширяет метод $modx->getChunk() и позволяет загружать чанк из файла. Причем путь к файлу можно указать как полный, так и относительный. В последнем случае путь к файлу формируется относительно пути, указанного в системной настройке modhelpers_chunks_path. Путь считается относительным, если путь начинается с "./".

Параметры функции:

  • string Имя чанка. Обязательный.
  • array Плейсхолдеры. Необязательный.
$output = chunk('myChunk', $placeholders); 
// Файловый чанк с полным путём
$output = chunk(MODX_CORE_PATH . 'chunks/myChunk.tpl', $params);
// Файловый чанк с относительным путём
$output = chunk('./myChunk.tpl', $params);

collection()

Используется для вывода коллекции объектов указанного класса. Возвращает объект специального класса менеджера объектов. Принимает 3 аргумента

  • string Название класса объекта. Обязательный.
  • array|integer Массив ключей для поиска. Необязательный.

Для объекта менеджера можно использовать цепочку методов конструктора запросов MODX (where(), sortby() и т.д.)

По-умолчанию массив ограничен 20 записями. Чтобы получить все записи нужно использовать метод объекта коллекции all() или метод конструктора запросов limit(0)

// Получаем 20 ресурсов
$collection = collection('modResource', ['published'=>0])->get();
// Получаем все объекты
$collection = collection('modResource', ['published'=>0])->all();

foreach ($collection as $object) {
    echo $object->pagetitle, "
"; } // Коллекция ресурсов в виде массивов $collection = collection('modResource',['id:<'=>20])->toArray(); foreach ($collection as $array) { echo $array['pagetitle'], "
"; } // Список значений pagetitle ресурсов с parent = 20 $collection = collection('modResource',['parent'=>20])->get('pagetitle'); // Альтернатива $collection = collection('modResource')->where(['parent'=>20])->get('pagetitle'); echo collection('modResource')->select('modResource.pagetitle, Template.templatename')->where(['id:>'=>20])->innerJoin('modTemplate','Template')->toSql(); // SELECT modResource.pagetitle, Template.templatename FROM `modx_site_content` AS `modResource` // JOIN `modx_site_templates` `Template` ON `modResource`.`template` = `Template`.`id` // WHERE `modResource`.`id` > 20 LIMIT 20

columns()

Выводит название столбцов таблицы указанного класса. Короткий вариант $modx->getSelectColumns()

Параметры функции:

  • string Имя класса объекта. Обязательный.
  • string Псевдоним. Необязательный.
  • string Префикс колонок. Необязательный.
  • array Колонки.
  • boolean Исключить. Если true, то указанные в предыдущем параметре колонки будут исключены из списка.
columns('modUser'); //`id`,`username`,`password`,`cachepwd`,`class_key`,`active`,`remote_key`,`sudo`,
                    //`remote_data`,`hash_class`,`salt`,`primary_group`,`session_stale`,`createdon`

config()

Получает или изменяет системные настройки. Изменённые данные в базе не сохраняются. Изменение производится в массиве настроек. Если вызвать функцию без параметров, то выведется весь массив настроек.

Параметры функции:

  • string|array Ключ настройки. Если указана строка, то функция вернёт значение указанной настройки. Обязательный.
  • mixed Значение по-умолчанию, если указанная настройка не найдена. Необязательный.
  • bool Присвоить дефолтное значение для пустой настройки. По-умолчанию False.
// Получить системную настройку
$siteName = config('site_name', 'Значение по-умолчанию');
// Изменить системную настройку
config(['site_name'=>'Новое название сайта']);

context()

Выводит указанное свойство текущего контекста.

Функция принимает один необязательный аргумент:

  • string Свойство. По-умолчанию выводит ключ "key".

csrf_field()

Формирует HTML код скрытого инпута с токеном. Пример с использованием шаблонизаторов:

<form method="POST" action="profile">
    {csrf_field()}  // Выведет <input type="hidden" name="csrf_token" value="sf7Y5wgC01vaSck2rc">
    ...
</form>

Если шаблонизатор не установлен, то можно создать простой сниппет и вставить его в форму:

// CSRF_snippet return csrf_field();

csrf_meta()

Формирует HTML тег META.

<html lang="ru">
<head>
    {csrf_meta()}  // <meta name="csrf-token" content="sf7Y5wgC01vaSck2rc">
    ...
</head>

csrf_token()

Получает токен для текущего пользователя. Автоматически генерируется при первом заходе пользователя и записывается в сессию. По-умолчанию, токен хранится до конца сессии пользователя. Но для большей безопасности вы можете ограничить время жизни токена, указав в системной настройке modhelpers_token_ttl количество минут, по прошествии которых будет создан новый токен. Если нужно изменить токен принудительно, то в функцию нужно передать первым параметром True.

Аргумент функции:

  • bool True - сгенерировать новый токен. По-умолчанию False. Необязательный.

css()

Добавляет стили. Позволяет добавлять атрибуты к тегу css за исключением аттрибута href.

Параметры функции:

  • string Источник. Можно указать пусть к файлу или стили, обёрнутые в тег style. Обязательный.
  • string Аттрибуты. Могут быть использованы любые аттрибуты тега link. Если не указать аттрибут rel, то пропишется rel="stylesheet". Необязательный.
css('assets/css/style.css');
css('<style>body { margin: 0; padding: 0 }</style>'); 
// С аттрибутами
css('assets/css/style.css', ['media' => 'all', 'rel' => "alternate"]);

dd()

Выводит информацию о переменных в удобном формате и прекращает выполнение сценария. Переменные для вывода указываются в параметрах через запятую. Доступны 2 темы - тёмная и светлая. Тёмная установлена по-умолчанию. Чтобы сменить тему, создайте системную настройку modhelpers_debug_theme и укажите в ней "light". Для тёмной темы значение должно быть "dark".

dd($modx->user, $array, $string);

default_if()

Эта функция возвращает определённое (дефолтное) значение в зависимости от условий. Она используется как альтернатива коду

if (!isset($var)) {
    $var = 'default';
}

Параметры функции:

  • mixed Переменная/Значение для проверки. Обязательный.
  • mixed Значение по-умолчанию. Необязательный.
  • bool Значение для сравнения. Необязательный.

По-умолчанию первый параметр проверяется на существование. Если он не существует или равен null, то возвращается дефолтное значение. Но третий параметр позволяет переопределить сравниваемое значение.

Примеры.

// Проверка переменной
$var = default_if($var, 'default');
// Проверка значения
$var = default_if($object->method(), 'default');
// Вывести дефолтное значение, если переменная пустая строка.
$var = default_if($var, 'default', '');
// Вывести дефолтное значение, если переменная пустой массив.
$message = default_if($data, 'Массив пустой!', array()); 

dump()

Выводит информацию о переменных в удобном формате. Переменные для вывода указываются в параметрах через запятую. Доступны 2 темы - тёмная и светлая. Тёмная установлена по-умолчанию. Чтобы сменить тему, создайте системную настройку modhelpers_debug_theme и укажите в ней "light". Для тёмной темы значение должно быть "dark".

dump($modx->user, $array, $string);

echo_br()

Добавляет к строке тег <br>. Используется для вывода в HTML разметке.

echo_br('Раз');
echo_br('Два');
echo_br('Три');
// Результат:
Раз
Два
Три

echo_nl()

Добавляет к строке символ конца строки. По-умолчанию это "\n".

echo_nl('Раз');
echo_nl('Два');
echo_nl('Три');
// Результат:
Раз
Два
Три

email()

Используется для отправки email. Принимает 3 аргумента:

  • string|array Электронный адрес или массив с адресами. Обязательный.
  • string|array Заголовок письма или параметры. Обязательный.
      Ключи массива параметров:
    • subject. Заголовок письма. Обязательный
    • content. Тело письма. Обязательный.
    • sender. По-умолчанию берётся значение из системной настройки emailsender. Необязательный.
    • from. По-умолчанию берётся значение из системной настройки emailsender. Необязательный.
    • fromName. По-умолчанию берётся значение из системной настройки site_name. Необязательный.
    • сс. Адрес для копии письма. Необязательный.
    • bсс. Адрес для скрытой копии письма. Необязательный.
    • replyTo. Адрес для обратного ответа. Необязательный.
    • attach. Файл для вложения. Для отправки нескольких файлов нужно указать массив. Необязательный.
    • tpl. Имя чанка или полный путь к файлу. Учитывается, если не указан ключ content. Необязательный.
  • string Тело письма. Если вторым параметром передан массив, то игнорируется. Необязательный.

Возвращает true или false в зависимости от результата.

Простой вариант

email('user@mail.ru', 'Заголовок письма', 'Тело сообщения');
// Вариант с параметрами
$params = array(
    // Обязательные параметры
    'subject' => 'Тема',
    'content' => 'Содержание письма',
    // Необязательные параметры
    'sender'   => 'admin@mail.ru',
    'from'     => 'Администратор',
    'fromName' => 'Центр досуга',
);
if (! email('user@mail.ru', $params)) {
    // Почта не отправилась. Причину смотри в журнале ошибок.
}

Используем класс мейлера

Вместо ключей массива параметров используются методы с аналогичными названиями. Для отправки используется метод send().

email()
	->to('user1@mail.ru')
	->toUser(5)
	->cc('user2@mail.ru') 
	->subject('Тема письма')
	->content('тело сообщения')
	->tpl('Название чанка или файл', $params) // игнорируется, если вызван метод content()
	->from('Администратор')
	->replyTo('admin@gmail.com')
	->attach('file1.jpg')
	->attach('file2.png')
	->send();

Эмулирование отправки сообщения

Эта возможность может пригодится при тестировании и отладке функционала на локальной машине. Для этого предназначены 2 метода, которые используются вместо метода send():

  • log() - запись массива данных сообщения в лог системы. Если передать параметр true, то сообщение запишется в формате JSON.
  • toArray() - получить массив с данными сообщения. Если передать параметр true, то сообщение выведется в виде строки через функцию print_r().
email()
	->to('user1@mail.ru')
	->toUser(5)
	->cc('user2@mail.ru') 
	->subject('Тема письма')
	->tpl('Название чанка или файл', $params)
	->from('Администратор')
	->replyTo('admin@gmail.com')
	->attach('file1.jpg')
	->log();

Использование очередей

Отправка почты - операция затратная. Поэтому лучше выполнять её асинхронно. Для этого можно воспользоваться механизмом очередей. Сначала сохранить письмо в очередь, а затем, например, в крон скрипте обработать очередь и отправить сохраненные в ней письма.

Для работы с очередями доступны 4 функции:

  • toQueue() - добавить письмо в очередь.
  • queue() - то же что и toQueue().
  • save() - то же что и toQueue().
  • sendFromQueue() - отправить письма из очередьи
  • queued() - алиас для sendFromQueue().
  • saved() - алиас для sendFromQueue().

В качестве аргумента этим методам можно передать название очереди. По-умолчанию, создаётся обрабатывается очередь с именем emails. Для работы с другой очередью нужно просто передать в метод новое название.

# Сохраняем письмо для менеджера
email()->to('manager@mail.mail')...->save('for_manager'); // Письмо будет добавлено в очередь "for_manager".
# Сохраняем письмо для администратора (очередь "for_admin"). 
email()->to('manager@mail.mail')...->save('for_admin'); // Можно очистить старую очередь передав вторым параметром TRUE.
...
# А в крон скриптах отсылаем письма. Например, для менеджера 1 раз в минуту, а для админа - раз в день.
... // Подключаем MODX
email()->saved('for_admin');

email_user()

Используется для отправки email указанному пользователю. Также принимает 3 аргумента:

  • string|integer|modUser Пользователь. Указывается или имя пользователя, или его id, или объект пользователя. Обязательный.
  • string|array Заголовок письма или параметры. Обязательный.
      Ключи массива:
    • subject. Заголовок письма. Обязательный
    • content. Тело письма. Обязательный.
    • sender. По-умолчанию берётся значение из системной настройки emailsender. Необязательный.
    • from. По-умолчанию берётся значение из системной настройки emailsender. Необязательный.
    • fromName. По-умолчанию берётся значение из системной настройки site_name. Необязательный.
    • сс. Адрес для копии письма. Необязательный.
    • bсс. Адрес для скрытой копии письма. Необязательный.
    • replyTo. Адрес для обратного ответа. Необязательный.
    • attach. Файл для вложения. Для отправки нескольких файлов нужно указать массив. Необязательный.
    • tpl. Имя чанка или полный путь к файлу. Учитывается, если не указан ключ content. Необязательный.
  • string Тело письма. Если вторым параметром передан массив, то игнорируется. Необязательный.

Возвращает true или false в зависимости от результата.

$user_id = 5; // или имя пользователя
email_user($user_id, $subject, $content);

escape()

Оборачивает строку специальным escape символом для текущего драйвера БД. Короткий синтаксис метода $modx->escape().

Принимает один параметр:

  • string Строка. Обязательный.
echo escape('Строка'); // `Строка`

explode_ltrim()

Эта функция объединяет и расширяет работу двух функций — explode() и ltrim(). Третим параметром можно передать символы для удаления.

Параметры функции:

  • string Разделитель. Обязательный.
  • string Строка. Обязательный.
  • string Символы для удаления. Необязательный. По-умолчанию указан пробел.
$string = '/string1,     /string2,/   string3';
explode_ltrim(',', $string, ' /'); // Array('string1','string2','string3')

explode_rtrim()

Эта функция объединяет и расширяет работу двух функций — explode() и rtrim(). Третим параметром можно передать символы для удаления.

Параметры функции:

  • string Разделитель. Обязательный.
  • string Строка. Обязательный.
  • string Символы для удаления. Необязательный. По-умолчанию указан пробел.
$string = '/string1/,/string2   /,/string3/     ';
explode_rtrim(',', $string, ' /'); // Array('/string1','/string2','/string3')

explode_trim()

Эта функция объединяет и расширяет работу двух функций — explode() и trim(). Третим параметром можно передать символы для удаления.

Параметры функции:

  • string Разделитель. Обязательный.
  • string Строка. Обязательный.
  • string Символы для удаления. Необязательный. По-умолчанию указан пробел.
$string = '/string1/,/      string2   /,/      string3/     ';
explode_trim(',', $string, ' /'); // Array('string1','string2','string3')

faker()

Функция для создания фейковых данных. Использует библиотеку Faker.

    Параметры:
  • string|arrray Параметры для класса Faker в формате - 'метод' или array('метод'=>'Опции').
  • string Локаль. Доступные значения - 'ru_RU', 'en_US', 'de_DE', 'fr_FR'. Если не указана, то будет определена по системной настройке cultureKey.
// В HTML документе через шаблонизатор Fenom
// Случайная картинка с размерами 640х480 (по-умолчанию)
<img src="{faker('imageUrl')}">
// Можно указать собственные размеры
<img src="{faker(['imageUrl'=>[200,50]])}">
// В php скрипте
$imgUrl = faker()->imageUrl(100,100);
// Вывод 3-х абзацев
<p>{faker(['text'=>[700]])}</p>
<p>{faker(['text'=>[500]])}</p>
<p>{faker(['text'=>[1000]])}</p>

Возможные методы можно посмотреть в документации к библиотеки Faker. Их достаточно много и можно использовать для создания текстов, картинок, имен, адресов, компаний, банков, телефонов, email, дат, времени и т.д.

filter_data()

Функция для фильтрации данных. Она преобразует входящие данные согласно указанным правилам.

Параметры функции:

  • array Данные в виде ассоциативного массива. Обязательный.
  • array Массив правил. Обязательный.
  • bool TRUE для вывода только отфильтрованных данных. По-умолчанию FALSE. Необязательный.

Первым параметром передается ассоциативный массив с данными. Например, это может быть $_POST. Правила - это тоже массив. Ключи должны совпадать с ключами массива данных, а в значениях можно указывать название фильтра, имя класса, php функцию или замыкание. Причем их можно комбинировать.

# Данные из формы
// $_POST = ['id' => '5', 'name' => '   John', 'fullname' => '   Silver   ', 'checkbox1' => 'on']

// Указываем фильтры для всех полей, кроме fullname
$rules = [
	'id' => 'int', // Приводит к типу integer значение из $_POST['id']
	'name' => 'string', // Удаляет теги и пробелы (trim) из $_POST['name']
	'checkbox1' => 'bool',  // Обрабатывает значение чекбокса $_POST['checkbox1']
	'checkbox2' => 'bool'  //  Обрабатывает значение чекбокса $_POST['checkbox2']
];
// Выводит всё (fullname присутствует, но не отфильтрован)
$filteredData = filter_data($_POST, $rules);
//  ['id' => 5, 'name' => 'John', 'fullname' => '   Silver   ', 'checkbox1' => true, 'checkbox2' => false]

// Выводит только отфильтрованные (fullname отсутствует)
$filteredData = filter_data($_POST, $rules, true);
//  ['id' => 5, 'name' => 'John', 'checkbox1' => true, 'checkbox2' => false]

На сегодняшний момент доступны следующие фильтры:

  • int, integer — Приводит к integer.
  • string — Удаляет теги и пробелы из начала и конца строки.
  • float — Приводит к float типу.
  • array — Конвертирует значение в массив.
  • bool, boolean — Возвращает TRUE для «1», «true», «on» и «yes». И FALSE в остальных случаях.
  • alpha — Возвращает только буквенные символы латинского алфавита из указанного значения.
  • alpha_num — Возвращает только буквы и цифры. Используется латинский алфивит.
  • num — Возвращает только цифры.
  • email — Удаляет все символы кроме букв, цифр и !#$%&'*+-=?^_`{|}~@.[].
  • url — Удаляет все символы кроме букв, цифр и $-_.+!*'(),{}|\^~[]`<>#%";/?:@&=.
  • limit — Обрезает строку до указанного значения и добавляет в конец указанную строку. После двоеточия через запятую можно определить 2 параметра — длина строки и окончание ('limit:20,...'). Многоточие указывается по-умолчанию.
  • fromJSON — Декодирует строку из JSON формата.
  • toJSON — Возвращает значение в JSON формате.
  • default — Возвращает значение по-умолчанию, если указанное значение не существует ('default: Значение по-умолчанию').

Если в фильтре указать название класса, то функция загрузит объект этого класса.

// $_POST = ['user' => '5', 'name' => '   John', 'fullname' => '   Silver   ', 'checkbox1' => 'on']
$rules = [
    'user' => 'modUser',
];
$filteredData = filter_data($_POST, $rules);
// $filteredData['user']  - это теперь объект класса modUser с id 5.

Указываем в качестве фильтра php функции. Указать несколько фильтров можно через вертикальную черту (|).

// $_POST['list' => 'cat1, cat2, cat5']
$post = filter_data($_POST, ['list' => 'explode|trim'; // Вызываем 2 фильтра - функции php
// $post['list'] = array('cat1', 'cat2', 'cat5')

Ну и последний вариант для сложных преобразований - передать в качестве фильтра замыкание. В нём можно выполнять любый манипуляции с входящими данными.

$rules = [
	'some' => function($value) { return $value ?: 'Значение по-умолчанию'; },
];

first()

Возвращает первый существующий (not null) из переданных аргументов.

$obj = first($someObj1, $someObj2, $defaultObj);

forward()

Отображает указанную страницу без замены URL. Расширяет метод $modx->sendForward().

Параметры функции:

  • integer Идентификатор ресурса. Обязательный.
  • array|string Опции или код ответа (response code). Необязательный.
// Отображает страницу с id=5 для текущего URL
forward(5);

has_parent()

Проверяет наличие одного или нескольких родителей у ресурса по цепочке до корня. Это бывает удобно, когда нужно проверить, входит ли текущий ресурс в определённую категорию, которая может быть на несколько уровней выше. Работает как с текущим ресурсом, так и с указанным в первом параметре. Для текущего ресурса его можно опустить.

Параметры функции:

  • integer Ресурс, для которого будет идти проверка. Необязательный. Для текущего ресурса можно не указывать.
  • integer|array Id родителя или массив с идентификаторами родителей. Обязательный.
  • bool Ключ, указывающий, что все указанные родители должны присутствовать. По-умолчанию false. Необязательный.
// Проверяет наличие родителя с id 1 у текущего ресурса.
if (has_parent(1)) { ...}

// Проверяет наличие родителя с id 1 у ресурса с id 10.
if (has_parent(10, 1)) { ... }

// Проверяет наличие одного из указанных родителей у ресурса с id 10.
if (has_parent(10, [1,5,8])) { ... }

// Проверяет наличие всех указанных родителей у ресурса с id 10.
if (has_parent(10, [1,5,8], true)) { ... }

html()

Эта функция аналогична функции script(), но используется для вставки на страницу html кода. Если второй параметр равен true, то указанная строка подключается в секцию head.

Параметры функции:

  • string Код для подключения. Обязательный.
  • bool Подключить в head. True - подключить в секции head, false - в конец секции body. По-умолчанию, false.
html('<div>Блок с рекламным сообщением.</div>');
// Подключаем в секцию head
html('<meta name="viewport" content="width=device-width, initial-scale=1.0">', true);

html_attirbutes()

Формирует готовую строку для из массива аттрибутов для HTML тега.

echo ' 'text', 'id' => 'id', 'required']) . '>';  // 

img()

Генерирует HTML тег img.

Функция принимает 2 аргумента:

  • string Url. Обязательный.
  • array Атрибуты тега. Ассоциативный массив (array('alt'=>'Картинка')). Необязательный.

is_ajax()

Возвращает true, если текущий запрос асинхронный (ajax).

if (is_ajax()) {
   // Асинхронный запрос
}

is_auth()

Проверяет, авторизован пользователь в указанном контексте или нет. Короткий синтаксис метода $modx->user->isAuthenticated(). В качестве аргумента можно передать контекст. По-умолчанию берётся текущий контекст, в то время как в методе $modx->user->isAuthenticated() по-умолчанию берется контекст "web". Т.е. функция is_auth() эквивалентна $modx->user->isAuthenticated($modx->context->key).

Функция принимает один необязательный агрумент:

  • string Контекст. По-умолчанию берётся текущий.
if (is_auth('en')) {
    // Пользователь авторизован в контексте en
}

is_desktop()

Возвращает TRUE, если запрос с компютера.

{if is_desktop()}
    <h1>Desktop version</h1>
{/if}

is_email()

Проверка валидности адреса электронной почты.

Параметр функции:

  • string Строка для проверки. Обязательный.
if (is_email($_POST['email'])) {
   // Почта валидная
}

is_guest()

Проверяет, является ли пользователь гостем. Т.е. проверка $modx->user->id = 0.

if (is_guest()) {
    // Пользователь не авторизован
}

is_mobile()

Проверяет, является текущий запрос с мобильного устройства.

{if is_mobile()}
    Mobile
{else}
    Desktop
{/if}

is_tablet()

Возвращает TRUE, если запрос пришёл с планшета.

if (is_tablet()) {
    // Запрос с планшета
}

is_url()

Проверка валидности URL.

Параметр функции:

  • string Строка для проверки. Обязательный.
if (is_url($url)) {
   // URL валидный
}

lang()

Выводит запись из лексикона. Используется для короткого синтаксиса вместо $modx->lexicon().

Параметры функции:

  • string Ключ. Обязательный.
  • array Плейсхолдеры. Необязательный.
  • string Язык. Необязательный.
$name = lang('object_name');

load_model()

Загружает модель указанной таблицы. Это нужно для того, чтобы MODX мог работать с таблицей через xPDO.

    Агрументы:
  • string Класс модели. Обязательный.
  • string|callable Таблица базы данных. Нужно указывать без префикса. Обязательный.
  • callable Функция для формирования модели. Можно вызывать вторым параметром, если нужно расширить существующую модель, например, модель ресурсов или пользователей.

Для загрузки модели уже созданной таблицы нужно выполнить 2 шага:

Шаг 1. Создать файл, в котором описать модель. Создать его можно в любом месте, но лучше выделить отдельную папку в директории core. Например, core/models/. Пример файла для модели Object, данные которой будут храниться в таблице modx_objects.

<?php # core/models/models.php
if (!class_exists('Object')) {
    class Object extends xPDOObject{} // xPDOSimpleObject
    class Object_mysql extends Object{}
    load_model('Object', 'objects', function ($model) {
        /** @var modHelperModelBuilder $model */
        $model->id('id')->pk(); // тип поля unsigned integer и указываем, что это первичный ключ.
        $model->varchar('name', 100)->setDefault('string')->rulePregMatch('invalid','/^[a-zA-Z\s]+$/','Нельзя использовать цифры в названии!');
        $model->text('description')->null()->alias('desc');
        $model->arr('properties')->null(); // array phptype
        $model->int('rid',true)->aggregate('Resource',array('class'=>'modResource','foreign'=>'id','cardinality'=>'one', 'owner'=>'foreign'))->index();
        $model->int('createdby')->unsigned()->aggOneForeign('CreateUser','modUser','id')->index(); 
        $model->int('editedby', true)->aggOneForeign('EditUser','modUser','id')->index(); 
        $model->datetime('createdon'); // Если дата храниться в БД с типом datetime
        $model->bigint('editedon',true)->phpType('datetime');// Если дата храниться в базе в UNIX формате.
    });
}

Обратите внимание!

Если ваша таблица содержит автоинкрементное поле id, то модель нужно наследовать от класса xPDOSimpleObject. И в этом случае в модели не нужно определять поле id, MODX определяет его автоматически.

Пример расширения базового класса ресурса, в таблице которого добавили поле tags для хранения тэгов:

load_model('modResource', function ($model) {
    $model->text('tags');
}

Шаг 2. В плагине нужно загрузить этот файл моделей. Создаём плагин и добавляем к нему событие OnMODXInit:

switch ($modx->event->name) {
    case 'OnMODXInit':
        include_once MODX_CORE_PATH . 'models/objects.php';
        break;
}

Теперь вы спокойно можете пользоваться методами xPDO для работы с этой таблицей.

$object = $modx->getObject('Object', 1);
$Creater = $object->CreateUser->username;
// Валидация
$obj->set('name', 'Супер 777'); // В модели мы указали правило, запрещающее вводить цифры в название
if (!$obj->validate()) {
    $validator = $obj->getValidator();
    return $validator->getMessages()[0]['message'];
}
$obj->save();

В целях оптимизации модель кэшируется. Так что, если вы поменяли модель в файле, нужно удалить файл с кэшированной версией в core/cache/default/название_модели_map.php. Или запретить кэшировать модель, указав специальной системной настройке modHelpers_cache_model значение false перед вызовом функции load_model():

config(['modHelpers_cache_model'=>false]); // По окончании разработки можно удалить
load_model('Class', function ($model) {
    ...
}

login()

Принудительная аутентификация (логин) указанного пользователя в текущий контекст.

Функция принимает один аргумент:

  • int|modUser $user. ID или объект пользователя.
login(10);
// или
$user = user(10); // == $modx->getObject('modUser', 10);
login($user);

logout()

Разлогинивает текущего пользователя.

Функция имеет 3 необязательных аргумента:

  • bool $redirect. Редиректить пользователя после разлогинивания. По-умолчанию, FALSE.
  • int $responseCode. Код для функции abort(). Возможные значения - 401, 403, 404. По-умолчанию, 401.
  • bool $relogin. Если TRUE, то MODX подгрузит текущего пользователя контекста "mgr", если такой есть. По-умолчанию, TRUE.

memory()

Выводит отформатированное значение памяти, выделенной для php скрипта.

Параметр функции:

  • string Единица измерения. Доступные значение - "byte", "KB" и "MB". По-умолчанию выводится в килобайтах. Необязательный.
echo memory(); // Аналогично memory('KB').

null_if()

Функция возвращает NULL, если переданное значение равно второму параметру. По-умолчанию, сравнивается с пустой строкой.

Параметры функции:

  • mixed .
  • mixed Значение для сравнений. По-умолчанию, пустая строка. Необязательный.
// $string = ''
$string = null_if($string); // NULL

object()

Используется для работы с объектом указанного класса. Возвращает объект специального класса менеджера объектов. Принимает 2 аргумента

  • string Название класса объекта. Обязательный.
  • array|integer Ключи для поиска - массив или id. Необязательный.

Для объекта менеджера можно использовать цепочку методов конструктора запросов MODX (where(), sortby() и т.д.)

// Получаем объект шаблона
$templObject = object('modTemplate',['id'=>1])->get(); 
$templateName = $templObject->get('templatename');
// Можно сразу получить значение поля объекта
$templateName = object('modTemplate', 1)->get('templatename');
// Можно указать ключи через метод where конструктора запросов
$templateName = object('modTemplate')->where(['id'=>1])->get('templatename');
// Обновить заголовок ресурса
$templateName = object('modResource')->where(['id'=>1])->set(['pagetitle'=>'Новый заголовок']);

Функция object() всегда выводит только один объект.

object_exists()

Проверяет наличие объекта указанного класса. Является обёрткой над методом $modx->getCount(). Принимает два параметра:

  • string Класс объекта.
  • array Критерии.

Возвращает true или false.

if (object_exists('Ticket', array('published'=>0))) {
    //Минимум один неопубликованный тикет существует 
}

optional()

Помогает избежать ошибки при обращении к свойству объекта, которого не существует, или к ключу несуществующего массива.

Параметры функции:

  • mixed Предполагаемый объект или массив.
$nullObj = null;
// Ошибка "Trying to get property of non-object"
echo $nullObj->property;
// Нет ошибки
echo optional($nullObj)->property; // Выведет null

parents()

Выводит id родителей ресурса для указанного уровня в виде массива.

Параметры функции:

  • integer Id ресурса. Обязательный.
  • integer Уровень. По-умолчанию 10. Необязательный.
  • array Опции. Необязательный.
$id = 10; 
$height = 3;
$parents = parents($id, $height);

parse()

Функция предназначена для парсинга строк. Имеет 2 режима - быстрый и полный. В быстром режиме аналогична методу modX::parseChunk(), только вместо имени чанка указывается строка. Т.е. как бы парсится инлайн-чанк. В полном режиме (включается третьим параметром) в исходной строке можно передавать также теги чанков и сниппетов.

Параметры функции:

  • string Строка с плейсхолдерами. Обязательный.
  • array Массив плейсхолдеров. Необязательный.
  • string Многоцелевой. Для быстрого режима - это префикс плейсхолдеров. По-умолчанию "[[+". Если указать TRUE, то запускается полный режим. Необязательный.
  • string Много целевой. В быстром режиме - суффикс плейсхолдеров. По-умолчанию "]]". В полном режиме указывается количество итераций. По-умолчанию 10. Необязательный.
# Быстрый режим (режим по-умолчанию)
foreach($userArray as $user) {
    $output .= parse('<p>id: [[+id]]</p><p>Имя пользователя: [[+username]]</p>');
}

# Полный режим
$tpl = 'Строка с вызовом чанка [[$chunk]].';
$output = parse($tpl, $data, true, 5);

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

pls()

Функция для работы с плейсхолдерами. Принимает 2 аргумента. Назначение аргументов зависит от режима. Чтобы получить плейсхолдер, укажите его название. Чтобы сохранить плейсхолдер, нужно передать массив. Если вызвать без аргументов, то выведет весь массив плейсхолдеров.

Параметры функции:

  • array|string Укажите имя плейсхолдера для того, чтобы получить его значение. Если передать массив, то он будет сохранён в качестве плейсхолдеров.
  • mixed В режиме получения - значение по умолчанию. При сохранении плейсхолдеров можно передать массив с параметрами.
# Получить значение плейсхолдера
$val = pls('my.Placeholder', 'Значение по-умолчанию');

# Сохранить плейсхолдер
pls(array('my.Placeholder'=>'значение'));

# Сохранить несколько плейсхолдеров
pls([
    'my.Placeholder1'=>'значение1',
    'my.Placeholder2'=>'значение2',
    'my.Placeholder3'=>'значение3',
]);

# Сохранение с указанием параметров
pls(['placeholder'=>'value'], [
    'prefix' => 'my', // Префикс
    'separator' => '_',  // Разделитель
]);
// my_placeholder

pls_delete()

Удаляет указанные плейсхолдеры.

Параметр функции:

  • array|string Ключ. В качестве параметра может принимать как строку с ключом, так и массив ключей.
pls_delete('my.Placeholder');

Выводит значение через функцию print_str() и завершает выполнение сценария (print and die).

Работает также как и print_r(). Но выполняет ещё ряд манипуляций - конвертирует переменную в строку и печатает или выводит её (вторым параметром нужно передать true). В качестве аргумента может быть строка, массив, объект, у которого определён метод toArray(). Массив оборачивается в тег pre. Кроме того, можно передать имя тега («p», «div» или «li») или шаблон, чтобы обернуть значение. Данная функция очень пригодится для отладки. Например, при выводе булевой переменной мы увидим не 1 и пустоту, а «TRUE» и «FALSE». А в случае с неопределенной переменной будет выведено «NULL», а не пустое значение.

Параметры функции:

  • string|array|object|bool|null Переменная. Обязательный.
  • bool|string Магический. True означает, что для вывода будет использован оператор return. Строка считается шаблоном. Необязательный.
  • string HTML тег или шаблон. Необязательный.
  • string Плейсхолдер для шаблона. По-умолчанию "output". Необязательный.
$nullVar;
$boolVar = true;
$objectVar = $modx->user;
$arrayVar = array(
	'key1' => 'value1'
	'key2' => 'value2'
	'key3' => array(
			'subkey1' => 'subvalue1',
			'subkey2' => 'subvalue2',
		)
);
$stringVar = 'Some text';

# Погнали
print_str($nullVar);   // Результат: 'NULL'
print_str($boolVar);   // Результат: 'TRUE'
print_str($objectVar); // Результат: <pre>
                       //                Array (
                       //                      [id] => 1
                       //                      [username] => 'admin'
                       //                      ...
                       //                )
                       //            </pre>

print_str($arrayVar);  // Результат: <pre>
                       //                Array (
                       //                      [key1] => 'value1'
                       //                      [key2] => 'value2'
                       //                      [key3] => Array (
                       //                                      [subkey1] => 'subvalue1',
                       //                                      [subkey2] => 'subvalue2',
                       //                                )
                       //                )
                       //            </pre>
print_str($stringVar); // "Some text"

# Вывод через return
return print_str($stringVar, true);

# Оборачиваем вывод
print_str('Строка, обёрнутая тегом div', false, 'div'); //<div>Строка, обёрнутая тегом div</div>
// Если второй параметр FALSE, то его можно опустить
print_str('Строка, обёрнутая тегом div', 'div'); //<div>Строка, обёрнутая тегом div</div>
# Указываем шаблон для одноразового вывода
print_str($stringVar, '<div style="color:red">[[+output]]</div>');

Можно настроить постоянный шаблон для всех сообщений. Для этого нужно в системной настройке modhelpers.print_template указать желаемый шаблон. Например, такой шаблон

// Переменная будет подставлена в плейсхолдер [[+output]]
<div style="color:yellow;backgroud-color:darkblue;padding:10px">[[+output]]</div>

будет выводить сообщения желтым цветом на синем фоне. Заметно и удобно для отладки

processor()

Это короткий вызов метода $modx->runProcessor().

Параметры функции:

  • string Процессор. Обязательный.
  • array Параметры. Необязательный.
  • array Опции. Необязательный.
$response = processor('имя_процессора', $params, $options); 

query()

Функция для работы с сырыми SQL запросами. Принимает один параметр:

  • string Sql запрос. Обязательный.

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

  • bind(). Используется для привязки плейсхолдеров. Магический. Данные можно передавать или в массиве или через запятую.
  • execute(). Выполняет запрос. Возвращается массив с данными или false в случае ошибки запроса.
  • count(). Выводит количество строк выполненного запроса. Возвращает false в случае ошибки запроса.
  • first(). Возвращает массив с данными первой строки из полученных данных.
  • toString(). Возвращает строковое представление полученных данных. Выводится через print_r().
// Неподготовленный запрос
$array = query('select * from ' . table_name('modUser'). ' WHERE id < 10')->execute();
// Подготовленный запрос
$array = query('select * from ' . table_name('modUser'). ' WHERE id < ?')->execute(10);

// Количество пользователей
$count = query('select * from ' . table_name('modUser'). ' WHERE id BETWEEN ? AND ?')->bind(10,20)->count();
// или так
$count = query('select * from ' . table_name('modUser'). ' WHERE id BETWEEN ? AND ?')->count(10,20);
// или так
$count = query('select * from ' . table_name('modUser'). ' WHERE id BETWEEN ? AND ?')->count(array(10,20));

quote()

Заключает строку в кавычки и экранирует специальные символы. Короткий синтаксис метода $modx->quote().

Параметры функции:

  • string Строка. Обязательный.
  • integer Тип параметра. Необязательный. По-умолчанию, принимает значение PDO::PARAM_STR.
$string = "Д'артаньян";
echo quote(); // 'Д\'артаньян'

redirect()

Переадресация на указанную страницу. Расширяет метод $modx->sendRedirect(). В качестве параметра можно передавать не только адрес, но и id страницы сайта.

Параметры функции:

  • string|integer Url или id ресурса. Обязательный.
  • array|string Опции. Указывается массив опций или название контекста. Контекст указывается в случае переадресации на id ресурса. Необязательный.
redirect('about.html');
// Переадресация на страницу с id=5
redirect(5);
// В другой контекст
$options = ['context'=>'en']
redirect(5, $options); 
// Или так
redirect(5, 'en');

Контекст имеет значение только если первым параметром передаётся id ресурса.

request()

Используется для работы с текущим HTTP запросом. Если функция вызывана без агрументов, то она вернёт экземпляр менеджера HTTP запроса. При использовании аргументов позволяет получить значение переменной запроса.

Аргументы функции:

  • string Имя POST или GET переменной запроса. Необязательный.
  • mixed Значение по-умолчанию, если указанной переменной запроса не существует. Необязательный.
# Получение переменной запроса
$key = request('key', 'Значение по-умолчанию');
// или
$request = request();
// через свойство менеджера запросов
$key = $request->input('key'); 
// через динамическое свойство менеджера запросов
$key = $request->key;
// используя менеджер запросов как массив 
$key = $request['key'];

Подробнее о возможностях этой функции можно прочитать в описании менеджера HTTP запросов.

resource()

Является упрощённым вариантом функции object() для ресурсов. Возвращает объект или массив с данными указанного ресурса.

Параметры функции:

  • array|integer Критерии. id ресурса или массив ключей. Необязательный.
  • bool Выводить как объект. True - вывести как объект, false - как массив. По-умолчанию выводится объект.

Если вызвать без агрументов, то выведется объект менеджера. В этом случае можно использовать методы конструктора запросов или менеджера объекта first(), last(), toArray() и т.д.)

$resourceObject = resource(15);
$pagetitle = resource(15)->get('pagetitle'); //Можно так: resource(15)->pagetitle

// resource($id) - выводит объект modResource. Поэтому можно использовать стандартные методы класса xPDOObject:
// toArray(), getOne(), addOne(), save() и т.д.
$resourceArray = resource(15)->toArray();
$pagetitle = resource(15, false)['pagetitle'];

$resource = resource([
            'pagetitle:LIKE' => 'Samsung Note*',
]);
// Последний ресурс
$resourceObject = resource()->last();

// Объект текущего ресурса
$resourceObject = resource(resource_id());

resources()

Выводит коллекцию объектов или массивов с данными ресурсов.

Параметры функции:

  • array Критерии. Массив ключей. Необязательный.
  • bool Выводить объекты. True - вывести объекты, false - массивы. По-умолчанию выводится коллекция массивов для экономии памяти.

Если вызвать без агрументов, то выведется объект коллекции. В этом случае можно использовать его методы и методы конструктора запросов MODX. Т.е. resources() равносилен collection('modResource').

// Массив ресурсов
$resources = resources(['id:>'=>20]);
// то же, что и
$resources = resources()->where(['id:>'=>20])->get();

// Массив с данными ресурсов в виде массива
$resources = resources(['id:>'=>20], false);
// то же, что и
$resources = resources()->where(['id:>'=>20])->toArray();

В качестве первого аргумента можно передать сложный массив с определёнными ключами:

array(
    'select' => 'field1,field2',
    'sortby' => 'field,direction', // direction можно не указывать. Тогда будет 'ASC'.
    'limit'  => 'number,offset',  // offset можно не указывать.
    'where'  => array('id'=>5)  // ключи для поиска
)

Если первый аргумент является массивом, но в нём нет указанных ключей ('select', 'sortby', 'limit', 'where'), то считается, что это условие для where.

resource_exists()

Проверяет наличие ресурса. Принимает всего один параметр:

  • integer|array Id ресурса или массив ключей.

Возвращает true или false.

if (resource_exists(5) {
    //Ресурс с id = 5 существует
}

resource_id()|res_id()

Выводит id текущего ресурса. Если вызвать до того, как MODX получит объект ресурса, в качестве результата вернётся false.

response()

Предназначена для подготовки ответа на запрос пользователя. Возвращает менеджер запросов - объект класса modHelpers/Response.

// Вернуть данные в JSON формате
response()->json(['success'=>true, 'message'=>'Сообщение']);

// Вернуть содержимое файла
response()->file('path/to/file.txt');

// Скачать файл
response()->download('path/to/image.jpg');

script()

Регистрирует скрипты для страницы. Позволяет добавлять атрибуты к тегу script за исключением аттрибута src. Объединяет функционал методов $modx->regClientScript() и $modx->regClientStartupScript(). Второй параметр отвечает за вариант подключения: true - в секции HEAD, false (по-умолчанию) - добавляется в конец BODY.

Метод магический. Атрибуты для тега можно указать или вторым или третим параметром.

Параметры функции:

  • string Источник. Можно указать пусть к файлу или скрипт, обёрнутый в тег script. Обязательный.
  • bool|string Подключить в head. True - подключить в секции head, false - в конец секции body. По-умолчанию, скрипт подключается в конец body. Если указать строку, то она будет добавлена как атрибут тега script, т.е. будет работать как третий параметр.
  • string|array Атрибуты. Строка или массив аттрибутов, которые будут добавлены к тегу script Необязательный.
script('assets/js/main.js'); 
script('<script>var params = ' . json_encode($params) . ';</script>', true); // Добавиться в <head>.

// Добавить файл скрипта в конец страницы с асинхронной загрузкой
script('/path/to/script.js', 'async'); // <script async type="text/javascript" src="/path/to/script.js"></script>
// Добавить файл скрипта в секцию head с последовательной асинхронной загрузкой
script('/path/to/script.js', true, 'async defer'); // <script async defer src="/path/to/script.js"></script>
// Добавить файл скрипта в секцию head с аттрибутами
script('/path/to/script.js', true, ['async', 'defer', 'type' => 'text/javascript']); // <script async defer type="text/javascript" src="/path/to/script.js"></script>

session()

Функция для работы с сессиями. Причём ключ можно указывать по точечной нотации. Этот режим используется по-умолчанию.

Параметры функции:

  • string|array Ключ. Необязательный.
  • mixed Значение по-умолчанию, если данные в сессии не существуют. Магический. В случае записи данных в сессию используется как третий параметр (выключатель парсинга точечной нотации). Необязательный.
  • bool Выключатель парсинга точечной нотации. По-умолчанию, false. Необязательный.

Чтобы получить значение из сессии, нужно указать ключ в виде строки. Второй параметр используется для указания значения по-умолчанию, которое вернётся, если указанного ключа в сессии не существует. Для записи данных в сессию нужно передать массив в формате array(['key1' => 'value1', 'key2' => 'value2']). Если вызвать без параметров, то выведется весь массив $_SESSION

//# Получить значение из сессии
$value = session('key1.key2'); 
// равносильно следующему коду
$value = $_SESSION['key1']['key2']

//# Записать значение в сессию
session(['key1.key2' => 'value']); 
// равносильно следующему коду
$_SESSION['key1']['key2'] = $value;

//# Обнулить ключ
session(['key1.key2' => null]); // Теперь isset($_SESSION['key1']['key2'] вернёт false

Третий параметр используется, если не нужно разбивать ключ по точкам (MODX использует ключи с точками для данных пользователя - modx.user.0.attributes).

// Сохраняем в сессию без использования точечной нотации
session(['key1.key2' => 'value'], true); // $_SESSION['key1.key2'] = 'value';
// Получаем данные из сессию без использования точечной нотации
$data = session('key1.key2', 'Значение по-умолчанию', true); // $data = isset($_SESSION['key1.key2']) ? $_SESSION['key1.key2'] : 'Значение по-умолчанию';

session_pull()

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

Например, в php скрипте записываем сообщение в сессию

if ($someError) {
	session(['error.message' => "Это сообщение будет показано только один раз!"]);
}

А в HTML разметке выводим через шаблонизатор (например, Fenom)

<div>
    {$.php.session_pull('error.message')} 
</div>

Также эту функцию можно использовать для удаления данных из сессии.

snippet()

Это замена метода $modx->runSnippet() с небольшой доработкой. Отличие от базового метода заключается в возможности вызова сниппета из файла. Путь к файлу можно указать как полный, так и относительный (должен начинаться с "./"). В последнем случае путь к файлу формируется относительно пути, указанного в системной настройке modhelpers_snippets_path.

И кроме того, результат работы сниппета можно сохранить в кэше.

Параметры функции:

  • string Имя сниппета. Обязательный.
  • array Парамметры. Необязательный.
  • array|string|integer Опции кэширования. Можно передать или время кэширования в секундах, или папку для кэширования, или массив опций (см. фукнцию cache()). Необязательный.
$output = snippet('mySnippet', $params); 
// Сохранение результата в кэш на 1 минуту
$output = snippet('mySnippet', $params, 60); // Пригодится для сложных сниппетов
// Вызов файлового сниппета с указанием полного пути
$output = snippet(MODX_CORE_PATH . 'snippets/mySnippet.php', $params);
// Вызов файлового сниппета с указанием относительного пути
$output = snippet('./mySnippet.php', $params);

str_between()

Возвращает подстроку, найденную между указанными тегами.

Параметры функции:

  • string Строка. Обязательный.
  • string Начальный тег. Обязательный.
  • string Конечный тег. Обязательный.
  • bool Жадный режим. По-умолчанию true. Необязательный.
$string = "My first name is [[+firstname]] and my last name is [[+lastname]]. ";
// Жадный режим
echo str_between($string,'[[+',']]'); // firstname]] and my last name is [[+lastname
// Нежадный режим (ленивый)
echo str_between($string,'[[+',']]', false); // firstname

$string = "<p>Lorem ipsum <span>dolor</span> sit amet</p>";
echo str_between($string,'<span>','</span>'); // dolor

str_clean()

Очищает строку от указанных символов. Альтернатива методу $modx->sanitizeString(), но менее строгая. Также имеет 3 параметра:

  • string Строка для обработки.
  • string|array Набор символов, которые нужно вырезать. Данный параметр магический. По-умолчанию, набор символов такой /\'"();><. Обратный слеш экранирует одинарную ковычку.
  • array Разрешённые теги. Используется для php функции strip_tag().

Если нужно указать разрешённые теги, а при этом стандартный набор символов менять не нужно, то теги можно передать вторым параметром.

str_clean('<div>Он сказал: "Привет, Пятачок!"</div>'); //Он сказал: Привет, Пятачок!
str_clean('<div>Он сказал: "Привет, Пятачок!"</div>',':",!'); //Он сказал Привет Пятачок
str_clean('<div>Он сказал: "Привет, Пятачок!"</div>', ['<div>']); //divОн сказал: Привет, Пятачок!div 
str_clean('<div>Он сказал: "Привет, Пятачок!"</div>',':",!', ['<div>']); //<div>Он сказал Привет Пятачок</div>

Чтобы просто вырезать HTML теги, вторым параметром нужно передать пустую строку. Тогда будет работать как strip_tags().

str_concat()

Функция склеивает все указанные через запятую строковые аргументы в единую строку.

$dolar = 'dolar';
str_concat('Lorem', ' ', 'ipsum', ' ',  $dolar);  // Lorem ipsum dolar

str_contains()

Проверяет, содержится ли указанная подстрока в исходной строке.

Параметры функции:

  • string Исходная строка. Обязательный.
  • string|array Подстрока или массив подстрок для поиска. Обязательный.
  • bool Учитывать регистр. Необязательный.
$str = "Здравствуйте, дорогая редакция!";
return str_contains($str, 'дорогая'); // TRUE
# Несколько подстрок
return str_contains($str, ['редакция','передача','прощай']); // TRUE

str_ends()

Проверяет, является ли указанная подстрока окончанием строки.

Параметры функции:

  • string Исходная строка. Обязательный.
  • string|array Подстрока или массив подстрок для проверки. Обязательный.
  • bool Учитывать регистр. Необязательный.
$str = "Здравствуйте, дорогая редакция!";
return str_ends($str, 'акция!'); // TRUE
# С учетом регистра
return str_ends($str, 'Редакция!', true); // FALSE
# Несколько подстрок
return str_ends($str, ['мама!','тёща!','ия!']); // TRUE

str_limit()

Возвращает строку указанной длины и добавляет завершающую строку — по-умолчанию многоточие.

Параметры функции:

  • string Исходная строка. Обязательный.
  • integer Длина. По-умолчанию 100. Необязательный.
  • string Добавить в конец строки. По-умолчанию "...". Необязательный.

str_match()

Проверяет строку на соответствие паттерну регулярного выражения. В качестве модификатора любого символа можно использовать звёздочку (*).

Параметры функции:

  • string Исходная строка. Обязательный.
  • string Паттерн. Обязательный.
  • bool Учитывать регистр. Необязательный.
$str = "А я милого узнаю по походке.";
return str_match($str, '*милого*'); // TRUE
return str_match($str, 'милого*'); // FALSE

str_starts()

Проверяет, является ли указанная подстрока началом строки.

Параметры функции:

  • string Исходная строка. Обязательный.
  • string|array Подстрока или массив подстрок для проверки. Обязательный.
  • bool Учитывать регистр. Необязательный.
$str = "Здравствуйте, дорогая редакция!";
return str_starts($str, 'здр'); // TRUE
# С учетом регистра
return str_starts($str, 'здр', true); // FALSE
# Несколько подстрок
return str_starts($str, ['привет','здрасьте','здравств']); // TRUE

string()

Функция позволяет выполнять некоторые манипуляции со строкой цепочкой методов. Она принимает в качестве аргумента строку.

$string = string('Some String')
                               ->toLower()                 // some string
                               ->replaceAll(' ', '_')      // some_string
                               ->replace('some', 'new')    // new_string
                               ->first(4)                  // new_
                               ->sha1(10)                  // cdabae2ca0
                               ->undo()                    // Some String
                               ->wrap('<div>','</div>')    // <div>Some String</div>
                               ->erase(0, 5)               // Some String</div>
                               ->length();                 // 17
							
echo $string->origin(); // Some String
echo $string;           // Some String</div>

switch_context()

Переключает контекст. Функция принимает 2 агрумента:

  • string|array|callable Имя контекста, условие или замыкание, которое должно вернуть имя контекста. Обязательный.
  • array Контексты для исключения. Необязательный.
# Простой вариант
switch_context($context_key); // аналогично $modx->switchContext()

# Переключение контекстов на субдоменах. У контекстов должна быть определена настройка http_host
switch_context(['http_host' => $_SERVER['HTTP_HOST']]); // или  request()->getHost()

# Переключение контекстов на директориях. У контекстов должна быть определена настройка base_url
switch_context(['base_url' => request()->segment(1)]);

# Использование замыкания
switch_context(function($modx) {
    // Определение контекста
    // $ctx = ...
    return $ctx;
});

Пример настройки контекстов можно посмотреть в официальной документации.

table_name()

Выводит название таблицы для указанного класса. Замена $modx->getTableName().

Параметры функции:

  • string Имя класса объекта. Обязательный.
  • bool Полное имя. Добавить название базы данных к таблице. По-умолчанию false.
table_name('modResource'); //modx_site_content

template_id()

Выводит id шаблона текущего ресурса. Если ресурс ещё не определился, то вернётся false.

tv()

Выводит TV текущего ресурса.

Функция принимает один аргумент:

  • mixed TV. В качестве параметра можно указать название TV или id.

url()

Функция формирует url и является синонимом метода $modx->makeUrl().

Параметры функции:

  • integer Id ресурса. Обязательный.
  • string Контекст. Необязательный.
  • array Аргументы ссылки. Необязательный.
  • mixed Схема. Возможные значения: -1,0,1,full,abs,http,https. Необязательный.
  • array Опции. Используются для замены системных настроек при формировании ссылок. Необязательный.
$resourceId = 5;
$url = url($resourceId);

user()

Является обёрткой функции object() для пользователей. Возвращает объект или массив.

Параметры функции:

  • array|integer Критерии. id пользователя или массив ключей. Необязательный.
  • bool Выводить как объект. True - вывести как объект, false - как массив. По-умолчанию выводится объект.

Если вызвать без агрументов, то выведется объект менеджера. В этом случае можно использовать конструктор запросов или использовать методы менеджера.

Поля профиля подгружаются автоматически.

$userID = 1;
$userObject = user($userID);
$email = user($userID)->get('email'); 

// user($userID) - выводит объект modUser. Поэтому можно использовать стандартные методы класса xPDOObject:
// toArray(), getOne(), addOne(), save() и т.д.
$userArray = user($userID)->toArray();
$username = user($userID, false)['username'];

$user = user([
            'username:LIKE' => 'Admin',
]);
// Текущий пользователь
$username = user(user_id())->username;

user_exists()

Проверяет наличие пользователя по условию. Принимает всего один параметр:

  • integer|array Id пользователя или массив ключей.

Возвращает true или false. В случае ошибки запроса возвращает NULL.

if (user_exists(['email'=>'admin@mail.ru']) {
    // Пользователь с таким email существует
}

if (user_exists(5) {
    // Пользователь с таким id существует
}

user_id()

Выводит id текущего пользователя.

users()

Аналогичен методу resources(). Выводит коллекцию объектов или массивов с данными пользователей.

  • array Критерии. Массив ключей. Необязательный.
  • bool Выводить коллекцию объектов. True - вывести объекты, false - массивы. По-умолчанию данные выводятся в виде массивов для экономии памяти.

Если вызвать без агрументов, то выведется объект коллекции. В этом случае можно использовать его методы и методы конструктора запросов MODX. Т.е. users() равносилен collection('modUser').

// Массив объектов пользователей
$users = users(['active'=>true]);
// то же, что и
$users = users()->where(['active'=>true])->get();

// Коллекция массивов 
$users = users(['active'=>true], false);

// Массив id активных пользователей
$IDs = users()->where(['active'=>true])->get('id');

В качестве первого аргумента можно передать сложный массив с определёнными ключами:

array(
    'select' => 'field1,field2',
    'sortby' => 'field,direction', // direction можно не указывать. Тогда будет 'ASC'.
    'limit'  => 'number,offset',  // offset можно не указывать.
    'where'  => array('id'=>5)  // ключи для поиска
)

Если первый аргумент является массивом, но в нём нет указанных ключей ('select', 'sortby', 'limit', 'where'), то считается, что это условие для where.

В отличие от функции user() в коллекции данные профиля нужно подключать отдельным методом profile().

$users = users()->profile()->select('username, email')->where(['Profile.blocked'=>1])->get();

Функции логирования

log_error()

Записывает сообщение в журнал ошибок для уровня логирования ERROR.

    Параметры:
  • string|array|object Сообщение или переменная. Может быть строкой, массивом или объектом, у которого определён метод toArray(). Массив выведется через функцию print_r().
  • bool Изменить уровень. Если указать true, то уровень логирования временно переключится, и после записи восстановиться обратно. Магический. Можно указать третий параметр.
  • string Место логирования. Возможные значения: '' - используется текущее значение, 'FILE' - сообщение записывается в файл лога, 'HTML' - ошибка выводится на странице файла.
log_error('Сообщение об ошибке');
// Вывести сообщение об ошибке на странице сайта вместо записи в файл лога.
log_error('Сообщение об ошибке', 'HTML');

log_warn()

Записывает сообщение в журнал ошибок для уровня логирования WARN.

    Параметры:
  • string|array|object Сообщение или переменная. Может быть строкой, массивом или объектом, у которого определён метод toArray(). Массив выведется через функцию print_r().
  • bool Изменить уровень. Если указать true, то уровень логирования временно переключится, и после записи восстановиться обратно. Магический. Можно указать третий параметр.
  • string Место логирования. Возможные значения: '' - используется текущее значение, 'FILE' - сообщение записывается в файл лога, 'HTML' - ошибка выводится на странице файла.
log_warn('Сообщение с предупреждением');

log_info()

Записывает сообщение в журнал ошибок для уровня логирования INFO.

    Параметры:
  • string|array|object Сообщение или переменная. Может быть строкой, массивом или объектом, у которого определён метод toArray(). Массив выведется через функцию print_r().
  • bool Изменить уровень. Если указать true, то уровень логирования временно переключится, и после записи восстановиться обратно. Магический. Можно указать третий параметр.
  • string Место логирования. Возможные значения: '' - используется текущее значение, 'FILE' - сообщение записывается в файл лога, 'HTML' - ошибка выводится на странице файла.
log_info('Информационное сообщение', true); // Переключить уровень
// Запись в журнале будет выглядеть так
// [2016-12-24 19:59:59] (INFO @ /www/core/model/modx/modx.class.php : 777) Информационное сообщение

log_debug()

Записывает сообщение в журнал ошибок для уровня логирования DEBUG.

    Параметры:
  • string|array|object Сообщение или переменная. Может быть строкой, массивом или объектом, у которого определён метод toArray(). Массив выведется через функцию print_r().
  • bool Изменить уровень. Если указать true, то уровень логирования временно переключится, и после записи восстановиться обратно. Магический. Можно указать третий параметр.
  • string Место логирования. Возможные значения: '' - используется текущее значение, 'FILE' - сообщение записывается в файл лога, 'HTML' - ошибка выводится на странице файла.
log_debug('Отладочная информация', true);

Это глобальные функции. Поэтому использовать эти функции можно везде - и в классах, и в сниппетах, и даже в чанках/ресурсах/шаблонах через шаблонизатор Fenom.

Подключение

Есть 2 варианта библиотеки - пакет для MODX и пакет для Composer (на данный момент не поддерживается). Первый подключается через установщик MODX. А способ подключения второго рассмотрен в этой статье.

Выделите опечатку и нажмите Ctrl + Enter, чтобы отправить сообщение об ошибке.