[modHelpers] Небольшие улучшения

В данной версии расширены возможности работы с сессией и почтовыми уведомлениями. Вот список изменений:

• Изменена сигнатура функции «session». Это очень важное изменение.
• Добавлена функция «session_pull».
• Добавлена функция «default_if».
• Добавлен метод «tpl» к классу modHelpersMailer.
• Добавлен метод «log» к классу modHelpersMailer.
• Добавлен метод «toArray» к классу modHelpersMailer.

Теперь давайте пробежимся по порядку.

Функция session()

Теперь она имеет следующую сигнатуру

Теперь чтобы записать значение в сессию нужно передать значение через массив:

session(['key' => 'value']);

Получить значение:

session('key', 'default');

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

Третий параметр $flat используется для отключения парсинга точечной нотации ключа (по-умолчанию он включён).

// С парсингом
session(['key1.key2' => 'value']); // $_SESSION['key1']['key2'] = 'value';
// Без парсинга
session(['key1.key2' => 'value'], true); // $_SESSION['key1.key2'] = 'value';

Эта возможность иногда может пригодится, так как MODX пишет некоторые ключи с точками — 'modx.user.0.attributes'.

Функция session_pull()

Данная функция получает из сессии значение по указанному ключу и удаляет этот ключ из сессии. Это пригодится для вывода одноразовых сообщений на странице. Например, в php скрипте записываем сообщение в сессию

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

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

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

Функция default_if()

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

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

Теперь это же можно сделать так

$var = default_if($var, 'default');

Или вместо того, чтобы писать так

$var = isset($object->method()) ? $object->method() : 'default'; 

пишем так

$var = default_if($object->method(), 'default'); 

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

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

$message = default_if($data, 'Массив пустой!', array()); 
// замена следующему коду
if (isset($data) && $data == array()) {
    $message = 'Массив пустой!';
}

Мне эта функция пригодилась. Возможно ещё кому-нибудь понравиться.

Уведомления

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

Первое — добавлен метод tpl(), который позволяет добавлять чанк (стандартный или файловый) для контента.

email()
    ->to('user1@mail.ru')
    ->toUser(5)
    ->cc('user2@mail.ru') 
    ->subject('Subject')
    ->tpl('chunkName or file', $params) // игнорируется, если контент указан методом content()
    ->from('Administrator')
    ->replyTo('admin@mysite.com')
    ->attach('path/to/file1.jpg')
    ->send();

Два остальных метода пригодятся при тестировании email уведомлений. Особенно это актуально для локальной разработки.

• Метод log() используется для вывода массива данных уведомления в лог системы. Если передать аргумент true, то вывод будет в формате JSON.
• Метод toArray() используется для получения данных уведомления. Если передать аргумент true, то массив выведется через print_r().

Оба эти метода конечные и используются вместо метода send().

email()
    ->to('user1@mail.ru')
    ->toUser(5)
    ->cc('user2@mail.ru') 
    ->subject('Subject')
    ->tpl('chunkName or file', $params)
    ->from('Administrator')
    ->replyTo('admin@mysite.com')
    ->attach('path/to/file1.jpg')
    ->log();

На этом всё.