Дополнительно/Функции

Встроенные функции фреймворка

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

Некоторые встроенные функции фреймворка имеют hl_ в начале названия, функции без такого префикса также имеют дубликаты с его добавлением. Поэтому, если вы забыли название нужной функции, напечатайте в нужном месте кода hl_ и ваша IDE должна подсказать доступные варианты.

#Работа с данными маршрутов

Во фреймворке HLEB2 собственная система роутинга. Следующие функции предназначены для того, чтобы взаимодействовать с этой системой. Если вы практикуете назначение маршрутам собственных названий, то они могут здесь пригодиться.

#route_name()

Эта функция возвращает название текущего маршрута или null если оно не назначено.
Несмотря на эту весьма полезную информацию, она может понадобиться только совместно с использованием другой функции по работе с адресами.

#url()

Функция url() возвращает относительный URL-адрес по имени маршрута и подстановкой необходимых параметров.
Аргументы функции:
routeName - название маршрута, для которого нужно получить адрес.
replacements - массив подстановочных частей, если маршрут динамический.
endPart - булево значение, определяющее, имеет ли получаемый адрес последнюю часть, если она в маршруте не обязательна.
method - для какого HTTP-метода нужен адрес. Дело в том, что для некоторых методов маршрут может не подходить и в таком случае вернёт ошибку. По умолчанию 'get'.

При единообразном использовании внутренних URL по их названиям в маршруте достигается возможность для всего приложения менять статические части адресов в маршрутах, не внося изменений в остальной код.

#address()

Функция address() возвращает полный URL-адрес по имени маршрута с подстановкой текущего домена. Так как домен присваивается только текущий, для другого домена используйте конкатенацию с url().
Набор параметров аналогичен функции url(). Благодаря этой функции можно генерировать корректные ссылки на страницы проекта. Однако для переходов внутри приложения лучше использовать относительные URL.

#Получение данных текущего HTTP-запроса

#request_uri()

Возвращает объект с информацией из относительного URL-адреса текущего запроса.
Основой для объекта, возвращаемого функцией request_uri(), взят UriInterface (метод getUri()) из PSR-7, благодаря этому можно получить следующие данные запроса:
request_uri()->getHost() - доменное имя текущего запроса, например - 'mob.example.com'. Может быть вместе с портом, в зависимости от наличия его в запросе.
request_uri()->getPath() - путь из адреса после хоста, например '/ru/example/page' или '/ru/example/page/'.
request_uri()->getQuery() - параметры запроса, например '?param1=value1&param2=value2'.
request_uri()->getPort() - порт запроса.
request_uri()->getScheme() - HTTP-схема запроса, 'http' или 'https'.
request_uri()->getIp() - IP-адрес запроса.

В этих примерах к request_uri() в одном выражении используется два вида составления названий (snake_case и camelCase), но это объясняется тем, что большинство функций фреймворка HLEB2 имеют вид snake_case аналогично функциям в PHP, а методы возвращаемого объекта в camelCase, по PSR-12. Если вам привычен другой формат функций, оберните текущие в необходимый вид.

#request_host()

Функция request_host() позволяет получить текущий хост. Может быть вместе с портом. Например, `example.com` или `example.com:8080` если он передан в URL запроса. Благодаря этому можно генерировать корректные ссылки на страницы проекта. Однако для переходов внутри приложения лучше использовать относительные URL.

#request_path()

Функция request_host() возвращает текущий относительный адрес запроса из URL без GET-параметров. Например `/ru/example/page` или `/ru/example/page/`.

#request_address()

Функция request_address() возвращает текущий полный адрес запроса из URL без GET-параметров. Например `https://example.com/ru/example/page` или `https://example.com/ru/example/page/`.

#Редирект

Перенаправление на другие страницы приложения или другие URL.

#hl_redirect()

При помощи функции hl_redirect() осуществляется редирект при помощи переданного специального заголовка и выхода из скрипта. Таким образом, если до применения этой функции уже был вывод контента, заголовки не будут переданы и будет показано предупреждение вместо редиректа. Работает на основе заголовка 'Location'. При применении в классах на основе фреймворка, например в контроллерах, более уместным будет использование аналогичного способа Redirect::to().

#Получение данных из конфигурации фреймворка

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

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

#config()

Каждый параметр конфигурации распределён по группам по основному названию файла.
Это могут быть как стандартные группы ('common', 'database', 'main', 'system') так и дополнительно созданные для проекта. Первым аргументом функции config() передаётся название такой группы.
Вторым - название самого параметра. Функция возвращает значение этого параметра. Например:

#get_config_or_fail()

Как следует из названия get_config_or_fail(), функция возвращает значение параметра конфигурации или возникает ошибка, если параметр не найден или равен null. Аргументы аналогичны функции config().

#setting()

Так как пользовательские значения рекомендовано добавлять в группу 'main', то для частого использования этой конфигурации предусмотрена отдельная функция setting(). Применение её аналогично функции config() с первым аргументом 'main'.

#hl_db_config()

Специальная функция hl_db_config() представляет собой аналог функции config() с первым аргументом 'database'.

#hl_db_connection()

Функция hl_db_connection() нужна для получения данных любого существующего подключения из списка 'db.settings.list' группы настроек 'database'. Возвращает массив с настройками или выбрасывает ошибку, если они не найдены.

#hl_db_active_connection()

Функция hl_db_active_connection() аналогично функции hl_db_connection() возвращает массив настроек, но для подключения, которое обозначено "активным" в параметре 'base.db.type'.

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

#Отладочные функции

Во фреймворке есть несколько функций для быстрой отладки кода. Они дополняют и расширяют PHP-функцию var_dump() различными способами. Исходя из ситуации можно выбрать подходящую.

#print_r2()

Эта функция осталась ещё из первой версии фреймворка. Она нужна для вывода данных в читаемом виде для отладочной панели. Таким образом, при отключённом режиме DEBUG переданные в функцию отладочные данные не будут отображаться, так как панель отладки отключена. Эту возможность удобно использовать при разработке, не беспокоясь о видимости её вывода вне режима отладки. Вторым аргументом функции print_r2() допустимо добавить описание к выводимым данным, чтобы потом найти их в панели. Пример:

#var_dump2()

Полный аналог функции var_dump(), только var_dump2() выводит информацию более структурированную, а если вывод предназначен для браузера, то сохраняются оригинальные переносы и отступы.

#dump()

Функция dump() - ещё одна обертка над var_dump(), но преобразует результат в HTML-код, который выглядит красивее и информативнее, чем стандартный вывод.

#dd()

Аналогично dump() выводит HTML-код, но после этого завершает работу скрипта. Функцию dd() легко найти на странице приложения, так как её вывод будет в самой нижней части.

#Работа с файловой системой

Во фреймворке HLEB2 организована работа с файлами и папками на уровне относительных путей от корня проекта. Такие пути начинаются со знака '@/' и обозначают начало корневой директории. Это используется во многих стандартных сервисах фреймворка и рекомендуется для применения. Следующие функции представляют собой обертки над соответствующими функциями в PHP и добавляют возможность использования метки '@'.

#hl_file_exists()

Функция hl_file_exists() аналог PHP функции file_exists(), но дополнительно может принимать специальные пути с '@' в начале.

#hl_file_get_contents()

Функция hl_file_get_contents() аналог PHP функции file_get_contents(), но позволяет использовать и специальные пути начинающиеся с '@'.

#hl_file_put_contents()

Функция hl_file_put_contents() аналог PHP функции file_put_contents(), но также принимает дополнительные пути с начальным '@'.

#hl_is_dir()

Функция hl_is_dir() аналог PHP функции is_dir(), но может принимать также пути с '@' в начале.

#Защита от CSRF-атак

Подробно про реализацию предохранения от CSRF-атак во фреймворке.

#csrf_token()

Функция csrf_token() возвращает защищённый токен для защиты от CSRF-атак.

#csrf_field()

Функция csrf_field() возвращает HTML-контент для вставки в форму для защиты от CSRF-атак.

#Шаблоны

Несмотря на то, что фреймворк позволяет подключить шаблонизатор Twig, имеются простая реализация встроенных шаблонов, не использующих собственной разметки, отличающейся от стандартного PHP или HTML. Подробнее о стандартных шаблонах фреймворка.

#insertTemplate()

Благодаря функции insertTemplate() сформированный шаблон добавляется в том месте файла, где расположена эта функция. Основные параметры:
viewPath - специальный путь к файлу шаблона. Формат аналогичен тем типам путей, которые используются в функции view().
extractParams - именованный массив значений, который будет преобразован в переменные шаблона.

#template()

Функция template() возвращает текстовое представление шаблона фреймворка. Это нужно, если необходимо передать содержимое далее, например если это шаблон письма. Параметры аналогичны функции insertTemplate().

#insertCacheTemplate()

Функция insertCacheTemplate() похожа на insertTemplate() с тем отличием, что шаблон кешируется на указанное количество секунд, указанное в параметре sec. Остальные аргументы аналогичны функции insertTemplate().

#Дополнительно

Различные узкоспециальные функции.

#is_empty()

Проверяет более избирательно значение на пустоту, чем PHP функция empty(). Функция is_empty вернёт false только в четырёх случаях: передана пустая строка, null, false или пустой массив. При передаче не объявленной переменной будет ошибка, поэтому для аналогии с оригинальной функцией можно подавить эту ошибку добавлением '@' перед функцией, например:

Хотя использование подавителя ошибок плохая практика, в коде функции is_empty() не подразумевается возникновение других ошибок.

#logger()

Функция для отправки в лог logger() возвращает объект с методами логирования данных по различным уровням.

#once()

Функция once() позволяет выполнять часть кода только единожды для одного запроса, а при повторном обращении возвращает прежний результат.
Результат выполнения хранится в памяти в течении всего запроса.
В этом сценарии анонимная функция, переданная в once(), будет выполнена при первом вызове once:

#param()

Возвращает объект с данными динамического запроса по имени параметра с возможностью выбора формата значения.
Например, если в динамическом маршруте был указан параметр `/{test}/`, а запрос был в виде `/example/`, то param('test')->value вернет 'example'.
param('test')->value; - прямое получение значения.
param('test')->value(); - прямое получение значения.
param('test')->asInt(); - возвращение значения, преобразованного в integer, при отсутствии равно null.
param('test')->asInt($default); - возвращение значения, преобразованного в integer, при отсутствии будет возвращено $default.
Если последняя часть маршрута является необязательным переменным значением, то это значение будет равно null.
Необходимо быть осторожными с пользовательскими данными, полученными в качестве прямого значения.

#Тестирование функций фреймворка

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