php/yii2
1
0
Fork 0
mirror of https://github.com/yiisoft/yii2.git synced 2025-12-01 23:51:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

Finished filter section [skip ci]

Browse Source
This commit is contained in:
Qiang Xue
2014-06-21 21:04:30 -04:00
parent 02e3746013
commit 60b38a1a33
7 changed files with 305 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/guide/concept-behaviors.md
View File

@@ -136,8 +136,20 @@ $component->attachBehaviors([
]); ]);
``` ```
You may also attach behaviors through [configurations](concept-configurations.md). For more details, please You may also attach behaviors through [configurations](concept-configurations.md) like the following. For more details,
refer to the [Configurations](concept-configurations.md#configuration-format) section. please refer to the [Configurations](concept-configurations.md#configuration-format) section.
```php
[
'as myBehavior2' => MyBehavior::className(),
'as myBehavior3' => [
'class' => MyBehavior::className(),
'prop1' => 'value1',
'prop2' => 'value2',
],
]
```
Detaching Behaviors <a name="detaching-behaviors"></a> Detaching Behaviors <a name="detaching-behaviors"></a>

12
docs/guide/concept-events.md
View File

@@ -162,6 +162,18 @@ $foo->on(Foo::EVENT_HELLO, function ($event) {
}, $data, false); }, $data, false);
``` ```
Besides calling the `on()` method, you may also attach event handlers in [configurations](concept-configurations.md)
like the following. For more details, please refer to the [Configurations](concept-configurations.md#configuration-format)
section.
```php
[
'on hello' => function ($event) {
echo 'hello event is triggered';
}
]
```
Detaching Event Handlers <a name="detaching-event-handlers"></a> Detaching Event Handlers <a name="detaching-event-handlers"></a>
------------------------ ------------------------

11
docs/guide/structure-controllers.md
View File

@@ -2,10 +2,13 @@ Controllers
=========== ===========
Controllers are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture. Controllers are part of the [MVC](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) architecture.
They are objects responsible for processing requests and generating responses. In particular, after They are objects of classes extending from [[yii\base\Controller]] and are responsible for processing requests and
taking over the control from [applications](structure-applications.md), controllers will analyze incoming request data, generating responses. In particular, after taking over the control from [applications](structure-applications.md),
pass them to [models](structure-models.md), inject model results into [views](structure-views.md), controllers will analyze incoming request data, pass them to [models](structure-models.md), inject model results
and finally generate outgoing responses. into [views](structure-views.md), and finally generate outgoing responses.
## Actions <a name="actions"></a>
Controllers are composed by *actions* which are the most basic units that end users can address and request for Controllers are composed by *actions* which are the most basic units that end users can address and request for
execution. A controller can have one or multiple actions. execution. A controller can have one or multiple actions.

288
docs/guide/structure-filters.md
View File

@@ -1,22 +1,215 @@
Filters Filters
======= =======
> Note: This section is under development. Filters are objects that run before and/or after [controller actions](structure-controllers.md#actions). For example,
an access control filter may run before actions to ensure that they are allowed to be accessed by particular end users;
a content compression filter may run after actions to compress the response content before sending them out to end users.
You may apply some action filters to controller actions to accomplish tasks such as determining A filter may consist of a pre-filter (filtering logic applied *before* actions) and/or a post-filter (logic applied
who can access the current action, decorating the result of the action, etc. *after* actions).
An action filter is an instance of a class extending [[yii\base\ActionFilter]].
To use an action filter, attach it as a behavior to a controller or a module. The following ## Using Filters <a name="using-filters"></a>
example shows how to enable HTTP caching for the `index` action:
Filters are essentially a special kind of [behaviors](concept-behaviors.md). Therefore, using filters is the same
as [using behaviors](concept-behaviors.md#attaching-behaviors). You can declare filters in a controller class
by overriding its [[yii\base\Controller::behaviors()|behaviors()]] method like the following:
```php ```php
public function behaviors() public function behaviors()
{ {
return [ return [
'httpCache' => [ [
'class' => \yii\filters\HttpCache::className(), 'class' => 'yii\filters\HttpCache',
'only' => ['index', 'view'],
'lastModified' => function ($action, $params) {
$q = new \yii\db\Query();
return $q->from('user')->max('updated_at');
},
],
];
}
```
By default, filters declared in a controller class will be applied to *all* actions in that controller. You can,
however, explicitly specify which actions the filter should be applied to by configuring the
[[yii\base\ActionFilter::only|only]] property. In the above example, the `HttpCache` filter only applies to the
`index` and `view` actions. You can also configure the [[yii\base\ActionFilter::except|except]] property to blacklist
some actions from being filtered.
Besides controllers, you can also declare filters in a [module](structure-modules.md) or [application](structure-applications.md).
When you do so, the filters will be applied to *all* controller actions belonging to that module or application,
unless you configure the filters' [[yii\base\ActionFilter::only|only]] and [[yii\base\ActionFilter::except|except]]
properties like described above.
> Note: When declaring filters in modules or applications, you should use [routes](structure-controllers.md#routes)
instead of action IDs in the [[yii\base\ActionFilter::only|only]] and [[yii\base\ActionFilter::except|except]] properties.
This is because action IDs alone cannot fully specify actions within the scope of a module or application.
When multiple filters are configured for a single action, they are applied according to the rules described below,
* Pre-filtering
- Apply filters declared in the application in the order they are listed in `behaviors()`.
- Apply filters declared in the module in the order they are listed in `behaviors()`.
- Apply filters declared in the controller in the order they are listed in `behaviors()`.
- If any of the filters cancel the action execution, the filters (both pre-filters and post-filters) after it will
not be applied.
* Running the action if it passes the pre-filtering.
* Post-filtering
- Apply filters declared in the controller in the reverse order they are listed in `behaviors()`.
- Apply filters declared in the module in the reverse order they are listed in `behaviors()`.
- Apply filters declared in the application in the reverse order they are listed in `behaviors()`.
## Creating Filters <a name="creating-filters"></a>
To create a new action filter, extend from [[yii\base\ActionFilter]] and override the
[[yii\base\ActionFilter::beforeAction()|beforeAction()]] and/or [[yii\base\ActionFilter::afterAction()|afterAction()]]
methods. The former will be executed before an action runs while the latter after an action runs.
The return value of [[yii\base\ActionFilter::beforeAction()|beforeAction()]] determines whether an action should
be executed or not. If it is false, the filters after this one will be skipped and the action will not be executed.
The following example shows a filter that logs the action execution time:
```php
namespace app\components;
use Yii;
use yii\base\ActionFilter;
class ActionTimeFilter extends ActionFilter
{
private $_startTime;
public function beforeAction($action)
{
$this->_startTime = microtime(true);
return parent::beforeAction($action);
}
public function afterAction($action, $result)
{
$time = microtime(true) - $this->_startTime;
Yii::trace("Action '{$action->uniqueId}' spent $time second.");
return parent::afterAction($action, $result);
}
}
```
## Core Filters <a name="core-filters"></a>
Yii provides a set of commonly used filters, found primarily under the `yii\filters` namespace. In the following,
we will briefly introduce these filters.
### [[yii\filters\AccessControl|AccessControl]] <a name="access-control"></a>
AccessControl provides simple access control based on a set of [[yii\filters\AccessControl::rules|rules]].
In particular, before an action is executed, AccessControl will examine the listed rules and find the first one
that matches the current context variables (such as user IP address, user login status, etc.) The matching
rule will dictate whether to allow or deny the execution of the requested action. If no rule matches, the access
will be denied.
The following example shows how to allow authenticated users to access the `create` and `update` actions
while denying all other users from accessing these two actions.
```php
use yii\filters\AccessControl;
public function behaviors()
{
return [
'access' => [
'class' => AccessControl::className(),
'only' => ['create', 'update'],
'rules' => [
// allow authenticated users
[
'allow' => true,
'roles' => ['@'],
],
// everything else is denied by default
],
],
];
}
```
For more details about access control in general, please refer to the [Authorization](security-authorization.md) section.
### [[yii\filters\ContentNegotiator|ContentNegotiator]] <a name="content-negotiator"></a>
ContentNegotiator supports response format negotiation and application language negotiation. It will try to
determine the response format and/or language by examining `GET` parameters and `Accept` HTTP header.
In the following example, ContentNegotiator is configured to support JSON and XML response formats, and
English (United States) and German languages.
```php
use yii\filters\ContentNegotiator;
use yii\web\Response;
public function behaviors()
{
return [
[
'class' => ContentNegotiator::className(),
'formats' => [
'application/json' => Response::FORMAT_JSON,
'application/xml' => Response::FORMAT_XML,
],
'languages' => [
'en-US',
'de',
],
],
];
}
```
Response formats and languages often need to be determined much earlier during
the [application lifecycle](structure-applications.md#application-lifecycle). For this reason, ContentNegotiator
is designed in a way such that it can also be used as a [bootstrap component](structure-applications.md#bootstrap)
besides filter. For example, you may configure it in the [application configuration](structure-applications.md#application-configurations)
like the following:
```php
use yii\filters\ContentNegotiator;
use yii\web\Response;
[
'bootstrap' => [
[
'class' => ContentNegotiator::className(),
'formats' => [
'application/json' => Response::FORMAT_JSON,
'application/xml' => Response::FORMAT_XML,
],
'languages' => [
'en-US',
'de',
],
],
],
];
```
### [[yii\filters\HttpCache|HttpCache]] <a name="http-cache"></a>
HttpCache implements client-side caching by utilizing the `Last-Modified` and `Etag` HTTP headers.
For example,
```php
use yii\filters\HttpCache;
public function behaviors()
{
return [
[
'class' => HttpCache::className(),
'only' => ['index'], 'only' => ['index'],
'lastModified' => function ($action, $params) { 'lastModified' => function ($action, $params) {
$q = new \yii\db\Query(); $q = new \yii\db\Query();
@@ -27,21 +220,70 @@ public function behaviors()
} }
``` ```
You may use multiple action filters at the same time. These filters will be applied in the Please refer to the [HTTP Caching](caching-http.md) section for more details about using HttpCache.
order they are declared in `behaviors()`. If any of the filter cancels the action execution,
the filters after it will be skipped.
When you attach a filter to a controller, it can be applied to all actions of that controller;
If you attach a filter to a module (or application), it can be applied to the actions of any controller
within that module (or application).
To create a new action filter, extend from [[yii\base\ActionFilter]] and override the ### [[yii\filters\PageCache|PageCache]] <a name="page-cache"></a>
[[yii\base\ActionFilter::beforeAction()|beforeAction()]] and [[yii\base\ActionFilter::afterAction()|afterAction()]]
methods. The former will be executed before an action runs while the latter after an action runs.
The return value of [[yii\base\ActionFilter::beforeAction()|beforeAction()]] determines whether
an action should be executed or not. If `beforeAction()` of a filter returns false, the filters after this one
will be skipped and the action will not be executed.
The [authorization](authorization.md) section of this guide shows how to use the [[yii\filters\AccessControl]] filter, PageCache implements server-side caching of whole pages. In the following example, PageCache is applied
and the [caching](caching.md) section gives more details about the [[yii\filters\PageCache]] and [[yii\filters\HttpCache]] filters. to the `index` action to cache the whole page for maximum 60 seconds or until the count of entries in the `post`
These built-in filters are also good references when you learn to create your own filters. table changes. It also stores different versions of the page depending on the chosen application language.
```php
use yii\filters\PageCache;
use yii\caching\DbDependency;
public function behaviors()
{
return [
'pageCache' => [
'class' => PageCache::className(),
'only' => ['index'],
'duration' => 60,
'dependency' => [
'class' => DbDependency::className(),
'sql' => 'SELECT COUNT(*) FROM post',
],
'variations' => [
\Yii::$app->language,
]
],
];
}
```
Please refer to the [Page Caching](caching-page.md) section for more details about using PageCache.
### [[yii\filters\RateLimiter|RateLimiter]] <a name="rate-limiter"></a>
RateLimiter implements a rate limiting algorithm based on the [leaky bucket algorithm](http://en.wikipedia.org/wiki/Leaky_bucket).
It is primarily used in implementing RESTful APIs. Please refer to the [Rate Limiting](rest-rate-limiting.md) section
for details about using this filter.
### [[yii\filters\VerbFilter|VerbFilter]] <a name="verb-filter"></a>
VerbFilter checks if the HTTP request methods are allowed by the requested actions. If not allowed, it will
throw an HTTP 405 exception. In the following example, VerbFilter is declared to specify a typical set of allowed
request methods for CRUD actions.
```php
use yii\filters\VerbFilter;
public function behaviors()
{
return [
'verbs' => [
'class' => VerbFilter::className(),
'actions' => [
'index' => ['get'],
'view' => ['get'],
'create' => ['get', 'post'],
'update' => ['get', 'put', 'post'],
'delete' => ['post', 'delete'],
],
],
];
}
```

2
docs/internals/translation-status.md
View File

@@ -21,7 +21,7 @@ structure-controllers.md | Yes
structure-views.md | Yes structure-views.md | Yes
structure-models.md | Yes structure-models.md | Yes
structure-modules.md | Yes structure-modules.md | Yes
structure-filters.md | structure-filters.md | Yes
structure-widgets.md | structure-widgets.md |
structure-assets.md | structure-assets.md |
structure-extensions.md | structure-extensions.md |

6
framework/filters/HttpCache.php
View File

@@ -12,11 +12,11 @@ use yii\base\ActionFilter;
use yii\base\Action; use yii\base\Action;
/** /**
* The HttpCache provides functionality for caching via HTTP Last-Modified and Etag headers. * HttpCache implements client-side caching by utilizing the `Last-Modified` and `Etag` HTTP headers.
* *
* It is an action filter that can be added to a controller and handles the `beforeAction` event. * It is an action filter that can be added to a controller and handles the `beforeAction` event.
* *
* To use AccessControl, declare it in the `behaviors()` method of your controller class. * To use HttpCache, declare it in the `behaviors()` method of your controller class.
* In the following example the filter will be applied to the `list`-action and * In the following example the filter will be applied to the `list`-action and
* the Last-Modified header will contain the date of the last update to the user table in the database. * the Last-Modified header will contain the date of the last update to the user table in the database.
* *
@@ -24,7 +24,7 @@ use yii\base\Action;
* public function behaviors() * public function behaviors()
* { * {
* return [ * return [
* 'httpCache' => [ * [
* 'class' => 'yii\filters\HttpCache', * 'class' => 'yii\filters\HttpCache',
* 'only' => ['index'], * 'only' => ['index'],
* 'lastModified' => function ($action, $params) { * 'lastModified' => function ($action, $params) {

7
framework/filters/PageCache.php
View File

@@ -13,15 +13,14 @@ use yii\base\Action;
use yii\caching\Dependency; use yii\caching\Dependency;
/** /**
* The PageCache provides functionality for whole page caching * PageCache implements server-side caching of whole pages.
* *
* It is an action filter that can be added to a controller and handles the `beforeAction` event. * It is an action filter that can be added to a controller and handles the `beforeAction` event.
* *
* To use PageCache, declare it in the `behaviors()` method of your controller class. * To use PageCache, declare it in the `behaviors()` method of your controller class.
* In the following example the filter will be applied to the `list`-action and * In the following example the filter will be applied to the `index` action and
* cache the whole page for maximum 60 seconds or until the count of entries in the post table changes. * cache the whole page for maximum 60 seconds or until the count of entries in the post table changes.
* It also stores different versions of the page depended on the route ([[varyByRoute]] is true by default), * It also stores different versions of the page depending on the application language.
* the application language and user id.
* *
* ~~~ * ~~~
* public function behaviors() * public function behaviors()