Yii app - приложения фреймворка

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

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

Конфигурация приложений

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

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

// загрузка конфигурации приложения
$config = require(__DIR__ . '/../config/web.php');

// создание и настраивание приложения
(new yii\web\Application($config))->run();

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

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

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

Необходимые свойства:

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

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

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

Вы можете формировать свойство basePath, используя путь к директории или псевдоним пути.

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

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

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

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

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

Эта свойство обеспечено так, чтобы вы могли определить псевдоним в условиях конфигурации приложения, а не при помощи вызова метода Yii::setAlias().

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

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

  • компонент ID приложения, определенный через компоненты
  • модуль ID, определенный через модули
  • имя класса
  • массив конфигурации
  • анонимная функция, которая создает и возвращает компонент

Пример:

[
    'bootstrap' => [
        // идентификатор компонента приложения или идентификатор модуля
        'demo',

        // имя класса
        'app\components\Profiler',

        // массив конфигурации
        [
            'class' => 'app\components\Profiler',
            'level' => 3,
        ],

        // анонимная функция
        function () {
            return new app\components\Profiler();
        }
    ],
]

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

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

if (YII_ENV_DEV) {
    // настройки конфигурации для среды 'dev'
    $config['bootstrap'][] = 'debug';
    $config['modules']['debug'] = 'yii\debug\Module';

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

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 - это свойство сопоставляет ID контроллера для произвольного класса контроллера. По умолчанию Yii отображает идентификаторы контроллера к контроллеру классов на основе конвенции (например, идентификатор сообщения будет отображаться в  app\controllers\PostController). При настройке этого свойства, вы можете разорвать свойство для конкретных контроллеров. В следующем примере, учетная запись будет отображаться в app\controllers\UserController,, в то время как статья будет отображаться в app\controllers\PostController.

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

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

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

Важно, чтобы полностью определенные классы контроллера были автозагружаемыми, а пространство имен классов контроллера соответствовало значению этого свойства. В противном случае вы получите ошибку "Page Not Found" при обращении к приложению.

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

modules - это свойство определяет модули, которые содержит приложение. Свойство принимает массив классов модулей или конфигураций с массивом идентификаторов модуля. Например:

[
    'modules' => [
        // модуль "booking", указанный с классом модуля
        'booking' => 'app\modules\booking\BookingModule',

        // модуль "comment", заданный с помощью массива конфигурации
        'comment' => [
            'class' => 'app\modules\comment\CommentModule',
            'db' => 'db',
        ],
    ],
]

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

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

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

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

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

sourceLanguage - определяет язык, на котором написан код программы. Значение по умолчанию "EN-US", что означется английский язык (Соединенные Штаты Америки). Это свойство можно настроить в том случае, если содержание текста в коде не на английском языке.

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

timeZone - свойство позволяющее задать часовой пояс.

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

version - позволяет задать версию приложения. По умолчанию это '1.0'.

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

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

charset - это свойство определяет кодировку приложения. По умолчанию используется 'UTF-8'.

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

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

[
    'extensions' => [
        [
            'name' => 'extension name',
            'version' => 'version number',
            'bootstrap' => 'BootstrapClassName',  // необязательно, также может быть массивом конфигурации
            'alias' => [  // optional
                '@alias1' => 'to/path1',
                '@alias2' => 'to/path2',
            ],
        ],

        // ... больше расширений, как указано выше ...

    ],
]

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

layoutPath - это свойство определяет путь к файлу макета, который нужно отображать. По умолчанию файл макета берется из каталога layouts.

runtimePath - определяет путь, по которому временные файлы, такие как файлы журналов и кэш-файлы, могут генерироваться. По умолчанию каталог временных файлов определяется псевдонимом @app/runtime.

viewPath - свойство определяет каталог, где расположены файлы отображения. По умолчанию каталог определяется псеводонимом @app/views.

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

enableCoreCommands - это свойство поддерживается только консольным приложением. Оно определяет, должны ли быть включены основные команды в релиз Yii. По умолчанию установлено значение true.

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

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

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

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

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

EVENT_BEFORE_REQUEST

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

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

EVENT_AFTER_REQUEST

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

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

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) {
            // изменение $event->result
        } else {
        }
    },
]