Приложения

Приложения — это объекты, которые управляют общей структурой и жизненным циклом систем приложений Yii. Каждая система приложений Yii содержит один объект приложения, который создаётся в скрипте входа и доступен глобально через выражение \Yii::$app.

Информация: В зависимости от контекста, под «приложением» может подразумеваться либо объект приложения, либо система приложения.

Существует два типа приложений: веб-приложения и приложения консоли. Как следует из названий, первые в основном обрабатывают веб-запросы, а вторые — запросы команд консоли.

Настройки приложений

Когда скрипт входа создаёт приложение, он загрузит настройки и применит их к приложению, как показано ниже:

require(__DIR__ . '/../vendor/autoload.php');
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');

// load application configuration
$config = require(__DIR__ . '/../config/web.php');

// instantiate and configure the application
(new yii\web\Application($config))->run();

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

Свойства приложений

Существует множество важных свойств приложения, которые необходимо настроить в настройках приложения. Эти свойства, как правило, описывают среду, в которой работают приложения. Например, приложениям нужно знать, как загружать контроллеры, куда сохранять временные файлы и т. д. Далее мы подведём итог этим свойствам.

Обязательные свойства

В любом приложении необходимо, как минимум, настроить два свойства: id и basePath.

id

Свойство id определяет уникальный идентификатор, который отличает одно приложение от другого. Оно в основном используется программно. Хотя это не обязательно, для наилучшей совместимости рекомендуется использовать только буквенно-цифровые символы при указании идентификатора приложения.

basePath

Свойство basePath указывает корневой каталог приложения. Это каталог, содержащий весь защищённый исходный код системы приложения. В этом каталоге обычно находятся подкаталоги, такие как models, views, и controllers, которые содержат исходный код, соответствующий паттерну MVC.

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

Свойство basePath часто используется для получения других важных путей (например, пути к каталогу кеша). По этой причине предварительно определён псевдоним пути @app, представляющий этот путь. Затем производные пути можно сформировать с помощью этого псевдонима (например, @app/runtime для ссылки на каталог кеша).

Важные свойства

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

aliases

Это свойство позволяет вам определить набор псевдонимов в виде массива. Ключи массива — имена псевдонимов, а значения — соответствующие определения путей. Например:

[
    'aliases' => [
        '@name1' => 'path/to/path1',
        '@name2' => 'path/to/path2',
    ],
]

Это свойство предоставляет возможность определения псевдонимов в настройках приложения вместо вызова метода Yii::setAlias().

bootstrap

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

Каждый компонент, указанный в этом свойстве, может быть задан в одном из следующих форматов:

• идентификатор компонента приложения, как указано в components,
• идентификатор модуля, как указано в modules,
• имя класса,
• массив конфигурации,
• анонимная функция, которая создаёт и возвращает компонент.

Например:

[
    'bootstrap' => [
        // an application component ID or module ID
        'demo',

        // a class name
        'app\components\Profiler',

        // a configuration array
        [
            'class' => 'app\components\Profiler',
            'level' => 3,
        ],

        // an anonymous function
        function () {
            return new app\components\Profiler();
        }
    ],
]

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

[
    function () {
        return Yii::$app->getModule('user');
    },
]

Во время процесса инициализации каждый компонент будет создан. Если класс компонента реализует yii\base\BootstrapInterface, его метод bootstrap() также будет вызван.

Другим практическим примером является конфигурация приложения для шаблона базового проекта, где модули debug и gii настраиваются как компоненты инициализации, когда приложение работает в среде разработки:

if (YII_ENV_DEV) {
    // configuration adjustments for 'dev' environment
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';

    $config['bootstrap'][] = 'gii';
    $config['modules']['gii'] = 'yii\gii\Module';
}

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

catchAll

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

Конфигурация — это массив, первый элемент которого задаёт маршрут действия. Остальные элементы массива (парные ключ-значение) задают параметры, которые должны быть привязаны к действию. Например:

[
    'catchAll' => [
        'offline/notice',
        'param1' => 'value1',
        'param2' => 'value2',
    ],
]

Информация: Панель отладки в среде разработки не будет работать при включении этого свойства.

components

Это одно из самых важных свойств. Оно позволяет зарегистрировать список именованных компонентов, называемых компонентами приложения, которые можно использовать в других местах. Например:

[
    'components' => [
        'cache' => [
            'class' => 'yii\caching\FileCache',
        ],
        'user' => [
            'identityClass' => 'app\models\User',
            'enableAutoLogin' => true,
        ],
    ],
]

Каждый компонент приложения задаётся как пара ключ-значение в массиве. Ключ представляет собой идентификатор компонента, а значение — имя класса компонента или настройки.

Вы можете зарегистрировать любой компонент в приложении, и к нему можно будет позже обратиться глобально, используя выражение \Yii::$app->componentID.

Подробности можно найти в разделе Компоненты приложения.

controllerMap

Это свойство позволяет сопоставлять идентификатор контроллера с произвольным классом контроллера. По умолчанию Yii сопоставляет идентификаторы контроллеров с классами контроллеров на основе конвенции (например, идентификатор post будет сопоставлен с app\controllers\PostController). Настроив это свойство, вы можете нарушить конвенцию для определённых контроллеров. В следующем примере account будет сопоставлен с app\controllers\UserController, а article — с app\controllers\PostController.

[
    'controllerMap' => [
        'account' => 'app\controllers\UserController',
        'article' => [
            'class' => 'app\controllers\PostController',
            'enableCsrfValidation' => false,
        ],
    ],
]

Ключи массива этого свойства представляют собой идентификаторы контроллеров, а значения — соответствующие имена классов контроллеров или настройки.

controllerNamespace

Это свойство указывает на стандартный namespace, в котором должны находиться классы контроллеров. По умолчанию оно равно app\controllers. Если идентификатор контроллера post, по конвенции соответствующее имя класса контроллера (без namespace) должно быть PostController, а полное имя класса — app\controllers\PostController.

Классы контроллеров также могут находиться в подкаталогах каталога, соответствующего этому namespace. Например, для идентификатора контроллера admin/post, соответствующий полный класс контроллера будет app\controllers\admin\PostController.

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

В случае необходимости нарушения конвенции, описанной выше, можно настроить свойство controllerMap.

language

Это свойство задаёт язык, на котором приложение должно отображать контент для конечных пользователей. Значение по умолчанию — en, что означает английский язык. Необходимо настроить это свойство, если ваше приложение должно поддерживать несколько языков.

Значение этого свойства определяет различные аспекты интернационализации, включая перевод сообщений, форматирование дат, форматирование чисел и т. д. Например, виджет yii\jui\DatePicker по умолчанию использует значение этого свойства для определения языка отображения календаря и форматирования дат.

Рекомендуется указывать язык в формате IETF-тега языка. Например, en означает английский язык, а en-US — английский язык (США).

Дополнительные сведения об этом свойстве можно найти в разделе Интернационализация.

modules

Это свойство определяет модули, которые содержит приложение.

Свойство принимает массив классов модулей или настроек, где ключи массива — идентификаторы модулей. Например:

[
    'modules' => [
        // a "booking" module specified with the module class
        'booking' => 'app\modules\booking\BookingModule',

        // a "comment" module specified with a configuration array
        'comment' => [
            'class' => 'app\modules\comment\CommentModule',
            'db' => 'db',
        ],
    ],
]

Дополнительные сведения см. в разделе Модули.

name

Это свойство определяет имя приложения, которое может отображаться конечным пользователям. В отличие от свойства id, которое должно принимать уникальное значение, значение этого свойства предназначено в основном для отображения; оно не должно быть уникальным.

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

params

Это свойство определяет массив глобально доступных параметров приложения. Вместо того, чтобы использовать жёстко закодированные числа и строки повсюду в своём коде, рекомендуется определить их как параметры приложения в одном месте и использовать параметры в нужных местах. Например, вы можете определить размер миниатюрного изображения как параметр следующим образом:

[
    'params' => [
        'thumbnail.size' => [128, 128],
    ],
]

Затем в вашем коде, где вам нужно использовать значение размера, вы можете просто использовать код, подобный следующему:

$size = \Yii::$app->params['thumbnail.size'];
$width = \Yii::$app->params['thumbnail.size'][0];

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

sourceLanguage

Это свойство определяет язык, на котором написан код приложения. Значение по умолчанию — 'en-US', что означает английский язык (США). Вам следует настроить это свойство, если текстовое содержимое вашего кода не на английском языке.

Как и свойство language, это свойство следует настраивать с помощью метки языка IETF. Например, en обозначает английский язык, а en-US — английский язык (США).

Дополнительные сведения об этом свойстве можно найти в разделе Международная локализация.

timeZone

Это свойство предоставляет альтернативный способ установки зоны времени по умолчанию среды выполнения PHP. Настройка этого свойства по существу эквивалентна вызову функции PHP date_default_timezone_set(). Например:

[
    'timeZone' => 'America/Los_Angeles',
]

version

Это свойство определяет версию приложения. По умолчанию оно равно '1.0'. Вам не нужно настраивать это свойство, если ни один из фрагментов кода не использует его.

Полезные свойства

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

charset

Это свойство определяет кодировку символов, используемую приложением. Значение по умолчанию — 'UTF-8', которое следует сохранять в большинстве приложений, если вы не работаете с устаревшей системой, использующей много не-Unicode данных.

defaultRoute

Это свойство определяет маршрут, который приложение должно использовать, если в запросе не указан маршрут. Маршрут может содержать идентификатор дочернего модуля, идентификатор контроллера и/или идентификатор действия. Например, help, post/create, или admin/post/create. Если идентификатор действия не указан, это свойство примет значение по умолчанию, указанное в yii\base\Controller::$defaultAction.

Для веб-приложений значение по умолчанию для этого свойства — 'site', что означает, что должен использоваться контроллер SiteController и его действие по умолчанию. В результате, если вы обратитесь к приложению без указания маршрута, будет отображаться результат app\controllers\SiteController::actionIndex().

Для консольных приложений значение по умолчанию — 'help', что означает, что должно использоваться основное командное действие yii\console\controllers\HelpController::actionIndex(). В результате, если вы выполните команду yii без аргументов, будет отображена справочная информация.

extensions

Это свойство определяет список расширений, которые установлены и используются приложением. По умолчанию оно примет массив, возвращаемый файлом @vendor/yiisoft/extensions.php. Файл extensions.php генерируется и поддерживается автоматически при использовании Composer для установки расширений. Поэтому в большинстве случаев вам не нужно настраивать это свойство.

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

[
    'extensions' => [
        [
            'name' => 'extension name',
            'version' => 'version number',
            'bootstrap' => 'BootstrapClassName',  // optional, may also be a configuration array
            'alias' => [  // optional
                '@alias1' => 'to/path1',
                '@alias2' => 'to/path2',
            ],
        ],

        // ... more extensions like the above ...

    ],
]

Как видите, свойство принимает массив спецификаций расширений. Каждое расширение задаётся массивом, состоящим из name и version элементов. Если расширение нужно запустить во время процесса инициализации, можно указать элемент bootstrap с именем класса инициализации или массивом конфигурации конфигурации. Расширение также может определять несколько псевдонимов.

layout

Это свойство определяет имя шаблона по умолчанию, который должен использоваться при отображении представления. Значение по умолчанию — 'main', что означает, что должен использоваться файл шаблона main.php в пути шаблонов. Если и путь шаблонов, и путь представлений принимают значения по умолчанию, файл шаблона по умолчанию может быть представлен как алиас пути @app/views/layouts/main.php.

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

layoutPath

Это свойство определяет путь, где следует искать файлы шаблонов. Значение по умолчанию — подкаталог layouts в пути представлений. Если путь представлений принимает значение по умолчанию, путь шаблона по умолчанию может быть представлен как алиас пути @app/views/layouts.

Вы можете настроить его как каталог или алиас пути пути.

runtimePath

Это свойство определяет путь к временным файлам, таким как файлы журналов и кеша. Значение по умолчанию — каталог, представленный псевдонимом @app/runtime.

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

Для упрощения доступа к этому пути Yii предоставил предварительно определённый псевдоним пути @runtime.

viewPath

Это свойство определяет корневой каталог, где расположены файлы представлений. Значение по умолчанию — каталог, представленный псевдонимом @app/views. Вы можете настроить его как каталог или алиас пути пути.

vendorPath

Это свойство определяет каталог vendor, управляемый Composer. Он содержит все сторонние библиотеки, используемые вашим приложением, включая фреймворк Yii. Значение по умолчанию — каталог, представленный псевдонимом @app/vendor.

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

Для упрощения доступа к этому пути Yii предоставил предварительно определённый псевдоним пути @vendor.

enableCoreCommands

Это свойство поддерживается только консольными приложениями. Оно определяет, должны ли быть включены командные действия, включенные в выпуск Yii. Значение по умолчанию — true.

События приложения

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

[
    'on beforeRequest' => function ($event) {
        // ...
    },
]

Использование синтаксиса on eventName описано в разделе Конфигурации.

В качестве альтернативы, вы можете прикрепить обработчики событий во время процесса инициализации после создания экземпляра приложения. Например:

\Yii::$app->on(\yii\base\Application::EVENT_BEFORE_REQUEST, function ($event) {
    // ...
});

EVENT_BEFORE_REQUEST

Это событие срабатывает перед тем, как приложение обработает запрос. Фактическое имя события — beforeRequest.

Когда это событие срабатывает, экземпляр приложения был настроен и инициализирован. Это хорошее место для вставки вашего пользовательского кода с помощью механизма событий для перехвата процесса обработки запроса. Например, в обработчике события вы можете динамически установить свойство yii\base\Application::$language на основе некоторых параметров.

EVENT_AFTER_REQUEST

Это событие срабатывает после завершения обработки запроса приложением, но перед отправкой ответа. Фактическое имя события — afterRequest.

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

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

EVENT_BEFORE_ACTION

Это событие срабатывает перед выполнением каждого действия контроллера. Фактическое имя события — beforeAction.

Параметр события — экземпляр yii\base\ActionEvent. Обработчик события может установить свойство yii\base\ActionEvent::$isValid на false для остановки выполнения действия. Например:

[
    'on beforeAction' => function ($event) {
        if (some condition) {
            $event->isValid = false;
        } else {
        }
    },
]

Обратите внимание, что то же самое beforeAction событие также срабатывает в модулях и контроллерах. Объекты приложения являются первыми, которые вызывают это событие, за ними следуют модули (если таковые имеются), а затем контроллеры. Если обработчик события устанавливает yii\base\ActionEvent::$isValid в false, все последующие события НЕ будут срабатывать.

EVENT_AFTER_ACTION

Это событие срабатывает после выполнения каждого действия контроллера. Фактическое имя события — afterAction.

Параметр события — экземпляр yii\base\ActionEvent. С помощью свойства yii\base\ActionEvent::$result обработчик события может получить доступ к результату действия или изменить его. Например:

[
    'on afterAction' => function ($event) {
        if (some condition) {
            // modify $event->result
        } else {
        }
    },
]

Обратите внимание, что то же самое afterAction событие также срабатывает в модулях и контроллерах. Эти объекты вызывают это событие в обратном порядке по сравнению с beforeAction. То есть контроллеры — первые объекты, вызывающие это событие, за ними следуют модули (если они есть), а затем — приложение.

Жизненный цикл приложения

Когда скрипт входа entry script выполняется для обработки запроса, приложение проходит через следующий жизненный цикл:

1. Скрипт входа загружает конфигурацию приложения в виде массива.
2. Скрипт входа создаёт новый экземпляр приложения:
   • Вызывается preInit(), который настраивает некоторые свойства приложения высокой приоритетности, такие как basePath.
   • Регистрируется обработчик ошибок.
   • Настраиваются свойства приложения.
   • Вызывается init(), который далее вызывает bootstrap() для запуска компонентов инициализации.
3. Скрипт входа вызывает yii\base\Application::run() для запуска приложения:
   • Срабатывает событие EVENT_BEFORE_REQUEST.
   • Обрабатывается запрос: маршрут запроса преобразуется в маршрут и связанные параметры; создаются объекты модуля, контроллера и действия, как указано в маршруте; и выполняется действие.
   • Срабатывает событие EVENT_AFTER_REQUEST.
   • Отправляется ответ конечному пользователю.
4. Скрипт входа получает код завершения из приложения и завершает обработку запроса.