«Исключенные» функции G-Drive

В 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).

Решили пока не включать в файл my/collection.php функции для получения списка или количества элементов. Но обсудить эти функции вполне уместно. В качестве основной функции получения списка можно использовать функцию с именем page (порядок аргументов можно изменить):

function page(
  $col = null,
  $pn = 0,
  $pp = 10,
  $filter = [],
  $meta = [],
  $order = ['id' => ORDER_ASC]
)

Аргумент $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.

Комментарии: 3

Админ

19.05.2025 08:19

Вместо использования конфигурационного параметра $report_mode можно вызывать функцию mysqli_report прямо в конфигурационном файле. Это напоминание о том, что конфигурационный файл по сути является функцией обратного вызова (callback). Он подключается в самом начале функции db_open и выполняет предварительную настройку для подключения к базе данных.
Админ

19.05.2025 08:34
Не запрещается генерировать исключения, прежде всего mysqli_sql_exception, внутри функции db_open. Но для этого нужно изменить каркас приложения, например убрать конструкцию блока if ($link = db_open()) и соответствующий блок else, поместив вызов db_open внутрь блока try:
```
try
{
    $link = db_open();
    ...
}
catch (Exception $e)
{
    ...
}
db_close($link);
```
Вызов функции db_close не будет приводить к ошибке, даже если переменная $link останется неопределенной из-за генерации исключения внутри функции db_open.
Админ

20.05.2025 12:22
Решили пока не включать в файл my/collection.php функции для получения списка или количества элементов. Но обсудить эти функции вполне уместно. В качестве основной функции получения списка можно использовать функцию с именем page (порядок аргументов можно изменить):
```
function page(
  $col = null,
  $pn = 0,
  $pp = 10,
  $filter = [],
  $meta = [],
  $order = ['id' => ORDER_ASC]
)
```
Аргумент $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.