[modHelpers] Улучшения работы с почтой и сессией

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

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

Функция session()

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

session($key = null, $default = null, $flat = false)

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

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();

На этом всё. Кому пригодятся данные возможности, плюсуйте.