Файл BaseController.php в Cotonti CMF

Опубликовано в: Cotonti - чтиво. Документация.

Назначение класса `BaseController` в Cotonti CMF

Класс BaseController является базовым контроллером в системе Cotonti CMF. Он задает структуру и общий функционал для всех контроллеров, обеспечивая стандартизированный подход к обработке действий (actions) и предоставляя механизмы для выполнения подготовительных и завершающих операций вокруг выполнения действия.

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

Основное назначение файла и его место в системе

Назначение: Файл /system/controllers/BaseController.php содержит абстрактный базовый класс контроллера, который служит основой для создания всех контроллеров в Cotonti CMF. Это базовый компонент, необходимый для реализации MVC-архитектуры фреймворка.
Место в системе:
- Этот класс входит в слой контроллеров фреймворка.
- Используется для маршрутизации запросов, вызова действий, обработки ошибок и подготовки/завершения выполнения действий.
- Расположен в директории, отвечающей за контроллеры, что указывает на его ключевую роль в обработке запросов.

Суть содержания кода

Основные функции класса:
- Управление действиями контроллера: регистрация действий, вызов методов для выполнения действий.
- Обеспечение возможности настроить подготовку (beforeAction) и завершение (afterAction) выполнения действий.
- Предоставление механизма для обработки как встроенных, так и внешних (сторонних) действий.
- Конвертация идентификаторов действий в CamelCase для стандартизации наименования.
Реализация задач:
- Обработка запроса: Метод runAction принимает идентификатор действия, проверяет его наличие и вызывает соответствующий метод для выполнения.
- Подготовка и завершение: Методы beforeAction и afterAction могут быть переопределены в наследниках для выполнения дополнительных операций.
- Работа с внешними действиями: Реализован механизм запуска внешних действий (например, подключение классов, которые содержат свои методы run).
- Конвертация имен действий: Утилитарный метод prepareName преобразует идентификаторы в формат CamelCase для обеспечения стандарта.

Задачи и условия, выполняемые классом

Обеспечивает стандартный интерфейс для реализации контроллеров.
Проверяет доступность действия перед его вызовом.
Управляет порядком выполнения операций:
1. Выполнение предварительных операций перед запуском действия.
2. Основное выполнение действия.
3. Завершающие операции после выполнения действия.
Обрабатывает ошибки и исключения, такие как отсутствие метода действия или неправильная конфигурация.

Список классов в файле

В данном файле содержится только один класс:

BaseController – абстрактный базовый класс для всех контроллеров в Cotonti CMF.

Список методов и функций в файле

Статические методы:
- static actions(): array – Возвращает список внешних действий, доступных в контроллере.
- static prepareName(string $name, string $separator = '-'): string – Преобразует строку идентификатора в формат CamelCase.
Публичные методы:
- beforeAction(): bool – Выполняется перед запуском действия, возвращает true, если действие должно продолжаться.
- afterAction(?string $result): ?string – Выполняется после завершения действия, возвращает результат выполнения действия.
- runAction(string $actionId): ?string – Основной метод выполнения действия, принимает идентификатор действия и вызывает соответствующий метод или внешний класс.
Защищенные методы:
- protected runStandAloneAction(string $actionId): ?string – Выполняет внешние действия, определенные в методе actions().

Итог

BaseController – это ключевой компонент MVC-архитектуры Cotonti CMF, который задает основу для всех контроллеров. Он предоставляет инструменты для обработки действий, управления выполнением и стандартизации вызовов, что делает его важной частью фреймворка.

BaseController.php в Cotonti CMF, находится по адресу: /system/controllers/BaseController.php движка php-фреймворка

<?php

declare(strict_types=1); // Строгая типизация включена, чтобы предотвратить неявные преобразования типов.

namespace cot\controllers; // Объявление пространства имен для организации кода и предотвращения конфликтов имен.

use BadMethodCallException; // Подключение встроенного исключения, вызываемого при некорректном вызове метода.
use cot\exceptions\InvalidConfigException; // Подключение исключения, связанного с некорректной конфигурацией объектов.
use cot\extensions\ExtensionsDictionary; // Подключение справочника расширений Cotonti для работы с действиями.

/**
 * Base controller class
 * @package Cotonti
 * @copyright (c) Cotonti Team
 * @license https://github.com/Cotonti/Cotonti/blob/master/License.txt
 */
// Базовый класс контроллера, предоставляющий общую функциональность для других контроллеров. Лицензия указана.

abstract class BaseController // Определение абстрактного класса BaseController, который нельзя инстанцировать.
{
    /**
     * @var ?string the ID of the action that is used when the action ID is not specified in the request.
     * Defaults to 'index'.
     */
    public static $defaultAction = ExtensionsDictionary::DEFAULT_ACTION_ID; 
    // Статическое свойство для хранения идентификатора действия по умолчанию.
    // Значение берется из справочника расширений, где обычно задается действие "index".

    /**
     * Объявляет внешние действия для контроллера.
     *
     * Этот метод может быть переопределен для объявления внешних действий.
     * Метод возвращает массив, где ключи — это идентификаторы действий, а значения — соответствующие имена классов действий.
     * Пример:
     * ```php
     * return [
     *   'action1' => 'cot\modules\someExt\controllers\Action1', // Класс, связанный с действием "action1".
     *   'action2' => [ // Определение действия с дополнительными параметрами.
     *     'class' => 'cot\modules\someExt\controllers\Action2', // Класс для действия "action2".
     *     'argument1' => 'value1', // Параметр "argument1" со значением "value1".
     *     'argument2' => 'value2', // Параметр "argument2" со значением "value2".
     *   ],
     * ];
     * ```
     * @return array<string, class-string|array<string, class-string|string>> // Метод возвращает массив с описанием действий.
     */
    public static function actions(): array // Метод объявляет доступные внешние действия контроллера.
    {
        return []; // Возвращает пустой массив по умолчанию, если действия не заданы.
    }

/**
 * Этот метод вызывается перед выполнением метода `runAction()`. 
 * Вы можете переопределить его для выполнения подготовительных действий перед запуском действия. 
 * Если метод возвращает false, выполнение действия будет отменено.
 *
 * @return bool определяет, выполнять ли действие.
 */
public function beforeAction(): bool
{
    return true; // Возвращает true, что указывает на то, что выполнение действия может быть продолжено.
}

/**
 * Этот метод вызывается после выполнения метода `runAction()`. 
 * Вы можете переопределить его для выполнения пост-обработки после выполнения действия.
 *
 * @param ?string $result Результат выполнения действия, который можно обработать или изменить.
 * @return ?string Возвращает (возможно изменённый) результат выполнения действия.
 */
public function afterAction(?string $result): ?string
{
    return $result; // Возвращает результат выполнения действия без изменений.
}

/**
 * Выполняет указанное действие контроллера.
 *
 * @param string $actionId Идентификатор действия, которое нужно выполнить.
 * @return ?string Результат выполнения действия, либо null, если действие было отменено.
 * @throws BadMethodCallException Если действие с указанным ID не найдено.
 */
public function runAction(string $actionId): ?string
{
    // Вызывает метод `beforeAction()` для выполнения подготовки перед запуском действия.
    if (!$this->beforeAction()) { 
        return null; // Если `beforeAction()` возвращает false, выполнение действия отменяется.
    }

    // Формирует имя метода действия на основе идентификатора действия.
    $actionName = 'action' . static::prepareName($actionId); 

    if (method_exists($this, $actionName)) { 
        // Если метод действия существует в текущем классе, вызывает его.
        $result = $this->$actionName(); 
    } elseif (array_key_exists($actionId, static::actions())) { 
        // Если действие определено как внешнее (в массиве `actions()`), выполняет его.
        $result = $this->runStandAloneAction($actionId); 
    } else {
        // Если действие не найдено, выбрасывает исключение.
        throw new BadMethodCallException(
            'Action "' . $actionId . '" not found in controller "' . get_class($this) . '"' // Сообщение об ошибке.
        );
    }

    // Вызывает метод `afterAction()` для обработки результата действия и возвращает итоговый результат.
    return $this->afterAction($result); 
}

/**
 * Выполняет внешнее (стороннее) действие, определенное в контроллере.
 *
 * @param string $actionId Идентификатор действия, которое нужно выполнить.
 * @return ?string Результат выполнения действия, либо null, если выполнение было отменено.
 * @throws BadMethodCallException Если действие не найдено в контроллере.
 * @throws InvalidConfigException Если конфигурация действия неверна или отсутствует метод run().
 */
protected function runStandAloneAction(string $actionId): ?string
{
    // Получает список внешних действий, определенных в массиве actions().
    $actions = static::actions(); 

    if (!array_key_exists($actionId, $actions)) { 
        // Если действие не найдено, выбрасывает исключение.
        throw new BadMethodCallException(
            'Action "' . $actionId . '" not found in controller "' . get_class($this) . '"' // Сообщение об ошибке.
        );
    }

    // Проверяет, корректно ли определена конфигурация действия как массив с элементом "class".
    if (isset($actions[$actionId]) && is_array($actions[$actionId]) && !isset($actions[$actionId]['class'])) { 
        throw new InvalidConfigException(
            'Action configuration must be an array containing a "class" element.' // Сообщение об ошибке конфигурации.
        );
    }

    // Получает имя класса действия.
    $actionClassName = is_string($actions[$actionId]) ? $actions[$actionId] : $actions[$actionId]['class']; 

    if (!method_exists($actionClassName, 'run')) { 
        // Если метод run() не определен в классе действия, выбрасывает исключение.
        throw new InvalidConfigException($actionClassName . ' must define a "run()" method.'); 
    }

    // Подготавливает аргументы для выполнения действия.
    $arguments = []; 
    if (is_array($actions[$actionId]) && count($actions[$actionId]) > 1) { 
        $arguments = $actions[$actionId]; // Берет все элементы конфигурации.
        unset($arguments['class']); // Удаляет ключ 'class', чтобы оставить только параметры.
    }

    /** @var BaseAction $action Создает экземпляр класса действия. */
    $action = new $actionClassName(); 

    // Выполняет метод beforeRun() перед запуском действия.
    if ($action->beforeRun()) { 
        // Вызывает метод run() действия с аргументами и сохраняет результат.
        $result = call_user_func_array([$action, 'run'], $arguments); 

        // Выполняет метод afterRun() после выполнения действия.
        $action->afterRun(); 

        return $result; // Возвращает результат выполнения действия.
    }

    return null; // Возвращает null, если выполнение действия было отменено.
}

/**
 * Преобразует строку идентификатора в формат CamelCase.
 * Пример: 'post-comment' преобразуется в 'PostComment'.
 *
 * @param string $name Строка, которую нужно преобразовать.
 * @param string $separator Разделитель слов в исходной строке. По умолчанию '-'.
 * @return string Преобразованная строка в формате CamelCase.
 */
public static function prepareName(string $name, string $separator = '-'): string
{
    // Использует функцию ucwords для преобразования первой буквы каждого слова в верхний регистр.
    // Затем удаляет разделитель из строки, объединяя слова в одну строку.
    return ucfirst(str_replace($separator, '', ucwords($name, $separator))); 
    // ucfirst делает первую букву строки заглавной.
}

8 минут чтения Administrator

Комментарии (0)

Комментарии отсутствуют

Добавление комментариев доступно только зарегистрированным пользователям

Автор контента

Оффлайн

Administrator

Последняя авторизация: 05.07.2026 18:32

Страница размещена: 28.01.2025 12:50
Последнее обновление: 28.01.2025 12:50

Похожих страниц не найдено

Справка и поддержка

Статьи и блоги

Файл BaseController.php в Cotonti CMF

Назначение класса `BaseController` в Cotonti CMF

Основное назначение файла и его место в системе

Суть содержания кода

Задачи и условия, выполняемые классом

Список классов в файле

Список методов и функций в файле

Итог

Комментарии (0)

Автор контента

Administrator

Справка и поддержка

Статьи и блоги

Файл BaseController.php в Cotonti CMF

Назначение класса BaseController в Cotonti CMF

Основное назначение файла и его место в системе

Суть содержания кода

Задачи и условия, выполняемые классом

Список классов в файле

Список методов и функций в файле

Итог

Комментарии (0)

Автор контента

Administrator

Назначение класса `BaseController` в Cotonti CMF