Хуки в Cotonti. Функция cot_getextplugins

Этот код представляет собой функцию cot_getextplugins, которая возвращает список плагинов, зарегистрированных для определённого хука (события). Давайте разберём каждую строку с комментариями.
Это описание функции. Она возвращает список плагинов, зарегистрированных для указанного хука. Сама функция имеет вид:

/**
 * Returns a list of plugins registered for a hook
 *
 * @param string $hook Hook (event) name
 * @param bool $checkExistence Check if hook file exists
 * @param ?string $extensionCode Get hook files (event handlers) for this extension only
 * @param string $permission Permissions
 * @return string[] Hook files list
 */
function cot_getextplugins(
    string $hook,
    bool $checkExistence = true,
    ?string $extensionCode = null,
    string $permission = 'R'
): array {
    // Class Cot may be not initialized yet
    global $cfg, $sys, $L, $cache;

    global $cot_plugins, $cotHooksFired;

    if ($cfg['debug_mode']) {
        $cotHooksFired[] = $hook;
    }

    $extPlugins = [];
    if (isset($cot_plugins[$hook]) && is_array($cot_plugins[$hook])) {
        foreach ($cot_plugins[$hook] as $handler) {
            if ($handler['pl_module']) {
                $dir = $cfg['modules_dir'];
                $cat = $handler['pl_code'];
                $opt = 'a';
            } else {
                $dir = $cfg['plugins_dir'];
                $cat = 'plug';
                $opt = $handler['pl_code'];
            }

            if (
                ($extensionCode !== null && $extensionCode !== $handler['pl_code'])
                || !cot_auth($cat, $opt, $permission)
            ) {
                continue;
            }

            $fileName = $dir . '/' . $handler['pl_file'];
            $fullFileName = $sys['baseDir'] . '/' . $fileName;
            if (
                $checkExistence
                && (!isset($cfg['checkHookFileExistence']) || $cfg['checkHookFileExistence'])
                && !is_readable($fullFileName)
            ) {
                $extType = $handler['pl_module'] ? 'mod' : 'pl';
                $extUrl = cot_url('admin', ['m' => 'extensions', 'a' => 'details', $extType => $handler['pl_code']]);

                // Language file can be not loaded yet
                $message = $L['hookFileNotFound']
                    ?? '<strong>{$title}</strong>, event - {$hook}: file {$fileName} not found. '
                    . 'Please <a href="{$url}">update the extension</a>';

                $messageText = cot_rc(
                    $message,
                    ['title' => $handler['pl_title'], 'hook' => $hook, 'fileName' => $fileName, 'url' => $extUrl]
                );
                cot_log($messageText, $handler['pl_code'], 'hook-include', 'error');
                if (!empty($usr['isadmin'])) {
                    cot_message($messageText, 'warning');
                }
                continue;
            }
            $extPlugins[] = $fullFileName;
        }
    }

    // Trigger cache handlers
    if (!empty($cache)) {
        $cache->trigger($hook);
    }

    return $extPlugins;
}

$hook: Название хука (события), для которого нужно получить плагины.
$checkExistence: Если true, проверяется наличие файла хуков на сервере.
$extensionCode: Опциональный параметр. Если указан, то файлы хуков будут возвращены только для указанного расширения.
$permission: Параметр, который определяет разрешения для проверки доступа.
Возвращаемое значение: Массив путей к файлам хуков.

function cot_getextplugins(
    string $hook,
    bool $checkExistence = true,
    ?string $extensionCode = null,
    string $permission = 'R'
): array {

Объявление самой функции. Функция принимает параметры, указанные в предыдущем комментарии.

// Class Cot may be not initialized yet
global $cfg, $sys, $L, $cache;
global $cot_plugins, $cotHooksFired;

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

    if ($cfg['debug_mode']) {
        $cotHooksFired[] = $hook;
    }

Если режим отладки включен (debug_mode), то текущий хук добавляется в список уже вызванных хуков. Это может помочь в отладке или логировании.

$extPlugins = [];

Инициализация пустого массива $extPlugins, в который будут добавляться пути к файлам плагинов.

if (isset($cot_plugins[$hook]) && is_array($cot_plugins[$hook])) {

Проверяется, существует ли хук в массиве $cot_plugins, и является ли он массивом. Это массив, в котором хранятся все плагины, зарегистрированные для разных хуков.

foreach ($cot_plugins[$hook] as $handler) {

Для каждого обработчика (плагина), зарегистрированного для данного хука, выполняется цикл.

if ($handler['pl_module']) {
	$dir = $cfg['modules_dir'];
	$cat = $handler['pl_code'];
	$opt = 'a';
} else {
	$dir = $cfg['plugins_dir'];
	$cat = 'plug';
	$opt = $handler['pl_code'];
}

В зависимости от того, является ли плагин модулем (pl_module), выбирается директория для плагинов или модулей.
Если это модуль, то используется директория для модулей (modules_dir), а категория (cat) устанавливается в код модуля.
Если это плагин, то используется директория для плагинов (plugins_dir), а категория устанавливается как 'plug'.

if (
	($extensionCode !== null && $extensionCode !== $handler['pl_code'])
	|| !cot_auth($cat, $opt, $permission)
) {
	continue;
}

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

$fileName = $dir . '/' . $handler['pl_file'];
$fullFileName = $sys['baseDir'] . '/' . $fileName;

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

if (
	$checkExistence
	&& (!isset($cfg['checkHookFileExistence']) || $cfg['checkHookFileExistence'])
	&& !is_readable($fullFileName)
)

Если необходимо проверить существование файла ($checkExistence), и если эта проверка разрешена конфигурацией, то проверяется, существует ли файл плагина и доступен ли он для чтения.

$extType = $handler['pl_module'] ? 'mod' : 'pl';
$extUrl = cot_url('admin', ['m' => 'extensions', 'a' => 'details', $extType => $handler['pl_code']]);

Если файл плагина не найден, формируется тип расширения (mod или pl) и URL для страницы администрирования этого расширения, чтобы пользователь мог обновить его.

// Language file can be not loaded yet
$message = $L['hookFileNotFound']
?? '<strong>{$title}</strong>, event - {$hook}: file {$fileName} not found. '
. 'Please <a href="{$url}">update the extension</a>';

Формируется сообщение об ошибке, если файл не найден. Используется языковая переменная $L['hookFileNotFound'], если она определена, или сообщение по умолчанию.

$messageText = cot_rc(
$message,
['title' => $handler['pl_title'], 'hook' => $hook, 'fileName' => $fileName, 'url' => $extUrl]
);
cot_log($messageText, $handler['pl_code'], 'hook-include', 'error');
if (!empty($usr['isadmin'])) {
cot_message($messageText, 'warning');
}
continue;

Сообщение форматируется с помощью cot_rc(), и записывается в лог через cot_log(). Если пользователь — администратор, сообщение также выводится на экран.

$extPlugins[] = $fullFileName;

Если плагин существует и доступен, его полный путь добавляется в массив $extPlugins.

// Trigger cache handlers
if (!empty($cache)) {
$cache->trigger($hook);
}

Если используется кэш, вызывается триггер для обработки кэшированных данных для данного хука.

return $extPlugins;

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