В G-Drive версии 3.15 встроенные функции перенесены в подключаемые файлы (кроме error). Причем состав этих функций расширен и будет расширяться еще. В статье представлено описание всех встроенных функций кроме error, которое в дальнейшем будет дополняться. Несмотря на исключение данных функций из основного файла движка, их по-прежнему можно называть встроенными. Хотя только функции ядра (из файла core.php) не требуется подключать явно.
Местоположение подключаемых файлов определяет константа INCLUDE_PATH. По умолчанию это каталог mods/exclude.
Ядро (файл core.php)
Условная константа ROOT_TABLE
Содержит имя корневой таблицы (таблицы категорий). Имеет значение "_root", если не определена заранее в основном файле, в котором по умолчанию имеет значение "site_categories".
Условная константа TABLE_PREFIX
Содержит табличный префикс всех таблиц кроме корневой. Имеет значение "_", если не определена заранее в основном файле, в котором по умолчанию имеет значение "site_".
Класс HttpException
Расширяет базовый класс Exception. Не переопределяет конструктор и другие методы базового класса. Семантически переопределяет свойства и параметры конструктора $message и $code.
Свойство $message содержит сообщение об ошибке.
Свойство $code содержит код (статуса) ответа HTTP. Соответствующий параметр конструктора наследует значение по умолчанию 0. Это значение совпадает со значением по умолчанию параметра $response_code встроенной функции PHP http_response_code.
Функция abort
function abort($code = 0, $message = '')
Генерирует исключение класса HttpException.
Функция table
function table($category = null)
Получает имя таблицы по символьному идентификатору категории (коллекции). Значение null позволяет получить имя корневой таблицы (таблицы категорий).
Правило формирования имени таблицы: берется символьный идентификатор категории, в котором все дефисы заменяются на символы подчеркивания, после чего к нему добавляется табличный префикс из константы TABLE_PREFIX. Если параметр $category содержит значение по умолчанию null, функция возвратит имя корневой таблицы из константы ROOT_TABLE.
Функция extra
function extra($k = null, $v = null)
В зависимости от числа указанных параметров выполняет три разных действия:
extra(key, value)
– установка значения, связанного с указанным ключом;extra(key)
– получение значения, связанного с указанным ключом;extra()
– перезагрузка всех значений из конфигурационного файла.
Во избежание «смешения действий» не рекомендуется передавать в функцию в любом из параметров значение null за исключением третьего действия, которое позволяет указать в первом параметре null, чтобы указать во втором параметре имя конфигурационного файла, отличное от используемого по умолчанию.
Выражение extra(key)
можно называть переменной реестра. На данный момент в G-Drive определена только одна подобная переменная: extra('layout')
. В ней содержится имя основного шаблона (относительно PATH и без расширения .php).
Файл my/collection.php
Образует пространство имен collection. Зависит от файла my/find.php.
Функция collection\item
function item($id, $col = null, $soft = false)
Получает элемент коллекции из базы данных. Значение null параметра $col позволяет получить запись корневой таблицы, т.е. категорию, а не объект.
Строковый параметр $id позволяет передавать как числовой, так и символьный идентификатор. Также в параметре можно передавать непосредственно число, т.к. сейчас с целью реализации заявленной совместимости не используются ни строгая типизация, ни декларация типа. Число будет преобразовано в строку внутри функции, а обратное преобразование числового идентификатора будет выполнено сервером баз данных.
Логический параметр $soft со значением true позволяет отключить контроль уникальности идентификатора объекта, используемый при выборе объектов с числовыми идентификаторами.
Внимание! Это обобщенная функция для itemStrict и itemSoft. Настоятельно рекомендуется явно передавать параметр $soft. Значение по умолчанию false экспериментальное и может быть в будущем изменено на true.
Внимание! Функция небезопасна при использовании произвольных значений параметров $id или $col. Не используются подготовленные выражения или экранирование. Не проверяется символьный идентификатор коллекции.
Возвращает элемент коллекции (объект) или запись корневой таблицы в виде ассоциативного массива. При возникновении ошибки генерирует исключение класса HttpException с кодом 404 или исключения функции find.
Функция collection\itemStrict
function itemStrict($id, $col = null)
Получает элемент коллекции из базы данных. Действует аналогично функции collection\item с параметром $soft, равным false. Это полный аналог функции collection\item, вызываемой без третьего параметра. Наличие этой функции обусловлено тем, что она появилась раньше функции collection\item и имеет незначительное преимущество в скорости из-за отсутствия третьего параметра.
Функция collection\itemSoft
function itemSoft($id, $col = null)
Получает элемент коллекции из базы данных. Действует аналогично функции collection\item с параметром $soft, равным true.
Файл my/find.php
Зависит от файла my/db.php. Могут генерироваться исключения функции query.
Функция find
function find($query)
Выполняет запрос SELECT, текст которого указан в $query, и получает первую запись результата запроса в виде ассоциативного массива. Если в результате запроса нет записей, возвращает null.
Функция findOrFail
function findOrFail($query)
Выполняет запрос SELECT, текст которого указан в $query, и получает первую запись результата запроса в виде ассоциативного массива. Если в результате запроса нет записей, генерирует исключение класса HttpException с кодом 404.
Файл my/db.php
Функция db_open
function db_open($config = 'include/dbconfig.php')
Открывает соединение с сервером баз данных в соответствии с параметрами из указанного конфигурационного файла, базовый каталог которого определяется константой PATH. Поддерживаются следующие параметры конфигурационного файла (в виде локальных переменных): $host, $user, $pw, $db и необязательные параметры $charset, $report_mode. Для G-Drive версии 3.15 при использовании PHP 8.1+ параметр $report_mode фактически обязателен, причем в его значении должен быть сброшен флаг MYSQLI_REPORT_STRICT.
Внимание! В будущем формат конфигурационного файла может быть изменен.
Возвращает объект типа mysqli или false в случае ошибки.
Функция db_close
function db_close(&$link)
Закрывает соединение с сервером баз данных, если параметр $link не равен null. В параметре, передаваемом по ссылке, должен находиться объект mysqli или null.
Не пытайтесь использовать показанный ниже синтаксис заголовка функции.
function db_close(mysqli &$link = null)
В PHP 8.4 он объявлен устаревшим.
Функция query
function query($query)
Выполняет запрос к базе данных, текст которого указан в $query.
В текущей реализации использует соединение из глобальной переменной $link.
В зависимости от типа запроса возвращает объект mysqli_result или true. Если при выполнении запроса возникла ошибка, генерирует исключение Exception (либо mysqli_sql_exception, когда установлен флаг MYSQLI_REPORT_STRICT).
Вместо использования конфигурационного параметра $report_mode можно вызывать функцию mysqli_report прямо в конфигурационном файле. Это напоминание о том, что конфигурационный файл по сути является функцией обратного вызова (callback). Он подключается в самом начале функции db_open и выполняет предварительную настройку для подключения к базе данных.
Не запрещается генерировать исключения, прежде всего mysqli_sql_exception, внутри функции db_open. Но для этого нужно изменить каркас приложения, например убрать конструкцию блока
if ($link = db_open())
и соответствующий блокelse
, поместив вызов db_open внутрь блокаtry
:Вызов функции db_close не будет приводить к ошибке, даже если переменная $link останется неопределенной из-за генерации исключения внутри функции db_open.
Решили пока не включать в файл my/collection.php функции для получения списка или количества элементов. Но обсудить эти функции вполне уместно. В качестве основной функции получения списка можно использовать функцию с именем page (порядок аргументов можно изменить):
Аргумент $pn определяет номер «страницы», т.е. номер фрагмента списка. Страницы нумеруются с 1. Значение 0 позволяет получить полный список.
Аргумент $pp определяет размер «страницы» (максимальное количество элементов в ней). Значение 0 зарезервировано. Значение 0 можно использовать, как значение по умолчанию, чтобы получать фактическое значение размера из другого источника, например из конфигурации приложения.
Аргумент $filter позволяет выполнить простую фильтрацию – выбрать элементы с указанными в фильтре значениями полей. Для более сложной фильтрации можно использовать отдельную функцию с именем filter.
Аргумент $meta позволяет дополнить выбираемые элементы полями с метаданными из словарных коллекций, например при связывании с коллекцией category элементы будут дополнены полями category_id и category_name. Для более сложного выбора метаданных можно использовать отдельную функцию с именем meta(data).
Аргумент $order позволяет упорядочить выбираемые элементы. При этом константы ORDER_ASC и ORDER_DESC должны быть определены в файле my/db.php.
Возвращаемым значением может быть как массив элементов, так и объект, например типа mysqli_result.
Можно использовать не только функцию получения количества элементов itemCount, но и функцию получения количества страниц pageCount.