diff --git a/docs/guide-ru/structure-filters.md b/docs/guide-ru/structure-filters.md index ae132682c0..c08a9e2f25 100644 --- a/docs/guide-ru/structure-filters.md +++ b/docs/guide-ru/structure-filters.md @@ -1,15 +1,19 @@ Фильтры ======= -Фильтры это объекты, которые запускаются перед и/или после [действий контроллера](structure-controllers.md#actions). Например, -фильтр управления доступом может запускаться перед действиями, для того чтобы гарантировать, что запросившему их пользователю разрешен доступ к ним; -фильтр сжатия содержимого, может запускаться после действий, чтобы сжать содержимое ответа перед отправкой его конечному пользователю. +Фильтры — это объекты, которые могут запускаться как перед так и после [действий контроллера](structure-controllers.md#actions). +Например, фильтр управления доступом может запускаться перед действиями удостовериться, что запросившему их пользователю +разрешен доступ; фильтр сжатия содержимого может запускаться после действий для сжатия содержимого ответа перед отправкой +его конечному пользователю. -Фильтр может состоять из *пре-фильтра* (фильтрующая логика применяется *перед* действиями) и/или *пост-фильтра* (логика, применяемая *после* действий). +Фильтр может состоять из *пре-фильтра* (фильтрующая логика применяется *перед* действиями) и/или +*пост-фильтра* (логика, применяемая *после* действий). ## Использование фильтров -Фильтры являются по существу особым видом [поведений](concept-behaviors.md). Поэтому, использование фильтров ничем не отличается от [использования поведений](concept-behaviors.md#attaching-behaviors). Вы можете объявлять фильтры в классе контроллера, путём перекрытия его [[yii\base\Controller::behaviors()|behaviors()]] метода, как на примере ниже: +Фильтры являются особым видом [поведений](concept-behaviors.md). Их использование ничем не отличается от +[использования поведений](concept-behaviors.md#attaching-behaviors). Вы можете объявлять фильтры в классе контроллера +путём перекрытия метода [[yii\base\Controller::behaviors()|behaviors()]]: ```php public function behaviors() @@ -27,15 +31,20 @@ public function behaviors() } ``` -По умолчанию, фильтры объявленные в классе контроллера, будут применяться ко *всем* действиям в этом контроллере. -Тем не менее, вы можете явно указать к каким действиям фильтр следует применять, настроив свойство [[yii\base\ActionFilter::only|only]]. В примере выше, фильтр `HttpCache` применяется только к действиям `index` и `view`. Вы можете также настроить свойство [[yii\base\ActionFilter::except|except]] чтобы указать действия, к которым фильтр не должен применяться. +По умолчанию фильтры, объявленные в классе контроллера, будут применяться ко *всем* его действиям. Тем не менее, вы можете +явно указать и конкретные действия задав свойство [[yii\base\ActionFilter::only|only]]. В примере выше фильтр `HttpCache` +применяется только к действиям `index` и `view`. Вы можете настроить свойство [[yii\base\ActionFilter::except|except]] +чтобы указать действия, к которым фильтр применяться не должен. -Кроме контроллеров, можно также объявлять фильтры в [модуле](structure-modules.md) или в [приложении](structure-applications.md). -Когда вы объявляете их так, эти фильтры будут применяться ко *всем* действиям контроллеров, находящихся в этом модуле или приложении, пока вы не настроите свойства фильтров [[yii\base\ActionFilter::only|only]] и [[yii\base\ActionFilter::except|except]] как было описано выше. +Кроме контроллеров, можно объявлять фильтры в [модуле](structure-modules.md) или в [приложении](structure-applications.md). +В этом случае они применяются ко *всем* действиям контроллеров, находящихся в этом модуле или приложении если не заданы +свойства [[yii\base\ActionFilter::only|only]] и [[yii\base\ActionFilter::except|except]] как было описано выше. -> Примечание: Когда объявляете фильтры в модулях или приложениях, вам следует использовать [маршруты](structure-controllers.md#routes) вместо идентификаторов действий в свойствах [[yii\base\ActionFilter::only|only]] и [[yii\base\ActionFilter::except|except]]. Так как сами по себе, идентификаторы действий не могут полностью определять действия, в пределах области видимости модуля или приложения. +> Примечание: При объявлении фильтров в модулях или приложениях, следует использовать [маршруты](structure-controllers.md#routes) + вместо идентификаторов действий в свойствах [[yii\base\ActionFilter::only|only]] и [[yii\base\ActionFilter::except|except]] + так как сами по себе, идентификаторы действий не могут полностью идентифицировать действие в контексте модуля или приложения. -Когда несколько фильтров указываются для одного действия, они применяются согласно правил, описанных ниже: +Когда несколько фильтров указываются для одного действия, они применяются согласно следующим правилам: * Пре-фильтрация - Применяются фильтры, объявленные в приложении в том порядке, в котором они перечислены в `behaviors()`. @@ -51,9 +60,11 @@ public function behaviors() ## Создание фильтров -При создании нового фильтра действия, нужно наследоваться от [[yii\base\ActionFilter]] и переопределить методы -[[yii\base\ActionFilter::beforeAction()|beforeAction()]] и/или [[yii\base\ActionFilter::afterAction()|afterAction()]]. Предшествующий из них будет выполнен перед выполнением действия, а последующий после выполнения действия. -Возвращаемое значение [[yii\base\ActionFilter::beforeAction()|beforeAction()]] определяет, будет ли действие выполняться или нет. Если вернется *ложь*, то оставшиеся фильтры не будут применены и действие не будет выполнено. +При создании нового фильтра действия, необходимо наследоваться от [[yii\base\ActionFilter]] и переопределить методы +[[yii\base\ActionFilter::beforeAction()|beforeAction()]] и/или [[yii\base\ActionFilter::afterAction()|afterAction()]]. +Первый из них будет вызыван перед выполнением действия, а второй после. Возвращаемое +[[yii\base\ActionFilter::beforeAction()|beforeAction()]] значение определяет, будет ли действие выполняться или нет. +Если вернётся `false`, то оставшиеся фильтры не будут применены и действие выполнено не будет. Пример ниже показывает фильтр, который выводит время выполнения действия: @@ -83,17 +94,22 @@ class ActionTimeFilter extends ActionFilter ``` -## Фильтры ядра +## Стандартные фильтры -Yii предоставляет набор часто используемых фильтров, которые находятся в основном в пространстве имен `yii\filters`. Далее, вы будете кратко ознакомлены с ними. +Yii предоставляет набор часто используемых фильтров, которые находятся, в основном, в пространстве имен `yii\filters`. +Далее вы будете кратко ознакомлены с ними. ### [[yii\filters\AccessControl|AccessControl]] -Фильтр AccessControl обеспечивает простое управление доступом, основанное на на наборе правил [[yii\filters\AccessControl::rules|rules]]. -В частности, перед тем как действие начнет выполнение, фильтр AccessControl будет проверять список указанных правил, пока не найдет первое из них, которое будет соответствовать текущему *контексту* переменных (таких как IP адрес пользователя, *статус пользователя (права)* и тд). Выбранное правило будет указывать разрешить или запретить выполнение запрошенного действия. Если ни одно из правил не подойдет, то доступ будет запрещен. +Фильтр `AccessControl` обеспечивает простое управление доступом, основанное на наборе правил [[yii\filters\AccessControl::rules|rules]]. +В частности, перед тем как действие начинает выполнение, фильтр `AccessControl` проверяет список указанных правил, пока не +найдёт соответствующее текущему контексту переменных (таких как IP адрес пользователя, статус аутентификации и так далее). +Найденное правило указывает, разрешить или запретить выполнение запрошенного действия. Если ни одно из правил не подходит, +то доступ будет запрещён. -Следующий пример показывает, как авторизованным пользователям разрешен доступ к действиям `create` и `update`, в то время как всем другим пользователям запрещен. +В следующем примере авторизованным пользователям разрешен доступ к действиям `create` и `update`, в то время как всем +другим пользователям доступ запрещён. ```php use yii\filters\AccessControl; @@ -105,29 +121,31 @@ public function behaviors() 'class' => AccessControl::className(), 'only' => ['create', 'update'], 'rules' => [ - // allow authenticated users + // разрешаем аутентифицированным пользователям [ 'allow' => true, 'roles' => ['@'], ], - // everything else is denied by default + // всё остальное по умолчанию запрещено ], ], ]; } ``` -Более подробно об управлении доступом, вы можете прочитать в разделе [Авторизация](security-authorization.md). +Более подробно об управлении доступом вы можете прочитать в разделе [Авторизация](security-authorization.md). -### Фильтр Методы Аутентификации +### Фильтр метода аутентификации -Фильтр Методы Аутентификации используется для аутентификации пользователя различными методами, такими как +Фильтр метода аутентификации используется для аутентификации пользователя различными способами, такими как [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication), [OAuth 2](http://oauth.net/2/). Классы данных фильтров находятся в пространстве имён `yii\filters\auth`. -Следующий пример показывает, как использовать [[yii\filters\auth\HttpBasicAuth]] для аутентификации пользователя с помощью токена доступа, основанного на методе Базовой HTTP аутентификации. Обратите внимание, для того чтобы это работало, ваш класс - [[yii\web\User::identityClass|user identity class]] должен реализовывать метод [[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]. +Следующий пример показывает, как использовать [[yii\filters\auth\HttpBasicAuth]] для аутентификации пользователя с помощью +токена доступа, основанного на методе basic HTTP auth. Обратите внимание, что для того чтобы это работало, ваш класс +[[yii\web\User::identityClass|user identity class]] должен реализовывать метод +[[yii\web\IdentityInterface::findIdentityByAccessToken()|findIdentityByAccessToken()]]. ```php use yii\filters\auth\HttpBasicAuth; @@ -142,15 +160,17 @@ public function behaviors() } ``` -Фильтры методов Аутентификации, часто используются при реализации сервисов RESTful API. Более подробную информацию о технологии +Фильтры метода аутентификации часто используются при реализации RESTful API. Более подробную информацию о технологии RESTful, смотрите в разделе [Authentication](rest-authentication.md). ### [[yii\filters\ContentNegotiator|ContentNegotiator]] -ContentNegotiator поддерживает согласование формата ответа и языка приложения. Он пытается определить формат ответа и/или язык, путем проверка параметров `GET` и `Accept` заголовка HTTP. +ContentNegotiator поддерживает согласование формата ответа и языка приложения. Он пытается определить формат ответа +и/или язык, путём проверки `GET` параметров и HTTP заголовка `Accept`. -В примере ниже, ContentNegotiator сконфигурирован чтобы поддерживать форматы ответа JSON и XML, а также Английский (США) и Немецкий языки. +В примере ниже, ContentNegotiator сконфигурирован чтобы поддерживать форматы ответа JSON и XML, а также Английский (США) +и Немецкий языки. ```php use yii\filters\ContentNegotiator; @@ -174,9 +194,10 @@ public function behaviors() } ``` -Часто требуется, чтобы форматы ответа и языки приложения, были определены как можно раньше в его [жизненном цикле](structure-applications.md#application-lifecycle). По этой причине, ContentNegotiator разработан так, что может использоваться как -[компонент предварительной загрузки](structure-applications.md#bootstrap), кроме того что он может использоваться как фильтр. Например, вы можете настроить его в [конфигурации приложения](structure-applications.md#application-configurations) -как показано ниже: +Часто требуется, чтобы форматы ответа и языки приложения были определены как можно раньше в его +[жизненном цикле](structure-applications.md#application-lifecycle). По этой причине, ContentNegotiator разработан так, что +помимо фильтра может использоваться как [компонент предварительной загрузки](structure-applications.md#bootstrap). Например, +вы можете настроить его в [конфигурации приложения](structure-applications.md#application-configurations): ```php use yii\filters\ContentNegotiator; @@ -199,14 +220,14 @@ use yii\web\Response; ]; ``` -> Информация: В случае, если предпочтительный тип содержимого и язык, не могут быть определены из запроса, будут использованы первый формат и язык, описанные в [[formats]] и [[languages]]. +> Информация: В случае, если предпочтительный тип содержимого и язык не могут быть определены из запроса, будут + использованы первый формат и язык, описанные в [[formats]] и [[languages]]. ### [[yii\filters\HttpCache|HttpCache]] -Фильтр HttpCache реализовывает кэширование на стороне клиента, используя HTTP заголовки `Last-Modified` и `Etag`. -Например, +Фильтр HttpCache реализовывает кэширование на стороне клиента, используя HTTP заголовки `Last-Modified` и `Etag`: ```php use yii\filters\HttpCache; @@ -226,13 +247,14 @@ public function behaviors() } ``` -Для более детальной информации об использовании HttpCache смотрите раздел [HTTP Кэширование](caching-http.md). +Подробнее об использовании HttpCache можно прочитать в разделе [HTTP Кэширование](caching-http.md). ### [[yii\filters\PageCache|PageCache]] -Фильтр PageCache реализует кэширование целых страниц на стороне сервера. В следующем примере, PageCache применяется только в действии `index`, для кэширования всей страницы в течение не более чем 60 секунд или пока количество записей в таблице `post` -не изменится. Он также хранит различные версии страницы, в зависимости от выбранного языка приложения. +Фильтр PageCache реализует кэширование целых страниц на стороне сервера. В следующем примере PageCache применяется только +в действии `index` для кэширования всей страницы в течение не более чем 60 секунд или пока количество записей в таблице `post` +не изменится. Он также хранит различные версии страницы в зависимости от выбранного языка приложения. ```php use yii\filters\PageCache; @@ -257,18 +279,21 @@ public function behaviors() } ``` -Для более деатльной информации об использовании PageCache, смотрите раздел [Кэширование страниц](caching-page.md). +Подробнее об использовании PageCache читайте в разделе [Кэширование страниц](caching-page.md). ### [[yii\filters\RateLimiter|RateLimiter]] -Ограничитель количества запросов в единицу времени *(RateLimiter)* реализует алгоритм ограничения запросов, основанный на [leaky bucket algorithm](http://en.wikipedia.org/wiki/Leaky_bucket). -В основном, он используется при создании RESTful API. Для более детальной информации об использовании данного фильтра, смотрите раздел [Ограничение запросов](rest-rate-limiting.md). +Ограничитель количества запросов в единицу времени *(RateLimiter)* реализует алгоритм ограничения запросов, основанный на +[алгоритме leaky bucket](http://en.wikipedia.org/wiki/Leaky_bucket). В основном, он используется при создании RESTful API. +Подробнее об использовании данного фильтра пожно прочитать в разделе [Ограничение запросов](rest-rate-limiting.md). ### [[yii\filters\VerbFilter|VerbFilter]] -Фильтр по типу запроса *(VerbFilter)* проверяет разрешено ли запросам HTTP, выполнять затребованные ими действия. Если такого разрешения нет, то будет выброшено исключение HTTP 405. В следующем примере, в фильтре по типу запроса, указан обычный набор разрешенных методов запроса, при выполнения CRUD операций. +Фильтр по типу запроса *(VerbFilter)* проверяет, разрешено ли запросам HTTP выполнять затребованные ими действия. +Если нет, то будет выброшено исключение HTTP с кодом 405. В следующем примере в фильтре по типу запроса указан обычный +набор разрешённых методов запроса при выполнения CRUD операций. ```php use yii\filters\VerbFilter; @@ -292,11 +317,14 @@ public function behaviors() ### [[yii\filters\Cors|Cors]] -Совместное использование разными источниками [CORS](https://developer.mozilla.org/fr/docs/HTTP/Access_control_CORS) - это механизм, который позволяет использовать различные ресурсы с Веб страницы (шрифты, скрипты, и т.д.) с различных доменов, а не только с тех, где эти ресурсы изначально расположены. -В частности, AJAX вызовы JavaScript могут использовать механизм XMLHttpRequest, хотя в противном случае, такие "междоменные" запросы запрещены, из-за политики безопасности. -CORS определяет путь взаимодействия сервера и браузера, по которому определяется возможность делать междоменные запросы. +Совместное использование разными источниками [CORS](https://developer.mozilla.org/fr/docs/HTTP/Access_control_CORS) - это +механизм, который позволяет использовать различные ресурсы (шрифты, скрипты, и т.д.) с отличных от основного сайта доменов. +В частности, AJAX вызовы JavaScript могут использовать механизм XMLHttpRequest. В противном случае, такие "междоменные" +запросы были бы запрещены из-за политики безопасности same origin. +CORS задаёт способ взаимодействия сервера и браузера, определяющий возможность делать междоменные запросы. -Фильтр [[yii\filters\Cors|Cors filter]] следует определять перед фильтрами Аутентификации / Авторизации, для того чтобы быть уверенными, что заголовки CORS будут всегда посланы. +Фильтр [[yii\filters\Cors|Cors filter]] следует определять перед фильтрами Аутентификации / Авторизации, для того чтобы +быть уверенными, что заголовки CORS будут всегда посланы. ```php use yii\filters\Cors; @@ -314,10 +342,14 @@ public function behaviors() Фильтрация Cors может быть настроена с помощью свойства `cors`. -* `cors['Origin']`: массив, используемый для определения источников. Может принимать значение `['*']` (все) или `['http://www.myserver.net', 'http://www.myotherserver.com']`. По умолчанию значение равно `['*']`. -* `cors['Access-Control-Request-Method']`: массив разрешенных типов запроса, таких как `['GET', 'OPTIONS', 'HEAD']`. Значение по умолчанию `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']`. -* `cors['Access-Control-Request-Headers']`: массив разрешенных заголовков. Может быть `['*']` то есть все заголовки, или один из указанных `['X-Request-With']`. Значение по умолчанию `['*']`. -* `cors['Access-Control-Allow-Credentials']`: определяет, может ли текущий запрос сделан с использованием авторизации. Может принимать значения `true`, `false` или `null` (не установлено). Значение по умолчанию `null`. +* `cors['Origin']`: массив, используемый для определения источников. Может принимать значение `['*']` (все) или + `['http://www.myserver.net', 'http://www.myotherserver.com']`. По умолчанию значение равно `['*']`. +* `cors['Access-Control-Request-Method']`: массив разрешенных типов запроса, таких как `['GET', 'OPTIONS', 'HEAD']`. + Значение по умолчанию `['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']`. +* `cors['Access-Control-Request-Headers']`: массив разрешенных заголовков. Может быть `['*']` то есть все заголовки или + один из указанных `['X-Request-With']`. Значение по умолчанию `['*']`. +* `cors['Access-Control-Allow-Credentials']`: определяет, может ли текущий запрос быть сделан с использованием авторизации. + Может принимать значения `true`, `false` или `null` (не установлено). Значение по умолчанию `null`. * `cors['Access-Control-Max-Age']`: определяет *срок жизни запроса, перед его началом*. По умолчанию `86400`. Например, разрешим CORS для источника : `http://www.myserver.net` с методами `GET`, `HEAD` и `OPTIONS` :