Class yii\filters\Cors

继承yii\filters\Cors » yii\base\ActionFilter » yii\base\Behavior » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/filters/Cors.php

Cors 过滤器实现了 跨源资源共享(Cross Origin Resource Sharing).

请务必仔细阅读 CORS 的操作和不操作. CORS 不保护你的 API, 但允许开发人员授予对第三方代码(来自外部域的 ajax 调用)的访问权限.

你可以通过将 CORS 过滤器作为行为附加到控制器或模块来使用它, 如下所示:

public function behaviors()
{
    return [
        'corsFilter' => [
            'class' => \yii\filters\Cors::className(),
        ],
    ];
}

CORS 过滤器可以专门用于限制参数, 例如 MDN CORS Information.

public function behaviors()
{
    return [
        'corsFilter' => [
            'class' => \yii\filters\Cors::className(),
            'cors' => [
                // 限制访问权限
                'Origin' => ['http://www.myserver.com', 'https://www.myserver.com'],
                // 仅允许 POST 和 PUT 方法
                'Access-Control-Request-Method' => ['POST', 'PUT'],
                // 仅允许标头'X-Wsse'
                'Access-Control-Request-Headers' => ['X-Wsse'],
                // 允许凭据(cookies, authorization headers, 等.)向浏览器公开
                'Access-Control-Allow-Credentials' => true,
                // 允许选项缓存
                'Access-Control-Max-Age' => 3600,
                // 允许将 X-Pagination-Current-Page 表头公开给浏览器
                'Access-Control-Expose-Headers' => ['X-Pagination-Current-Page'],
            ],

        ],
    ];
}

有关如何将 CORS 过滤器添加到控制器的更多信息, 请参阅 权威指南 - 应用结构 - 过滤器(Filters) - Cors.

公共属性

隐藏继承的属性

属性类型描述定义在
$actions array 为特定动作定义特定的 CORS 规则. yii\filters\Cors
$cors array 为 CORS 请求处理的基本标头. yii\filters\Cors
$except array 此过滤器不适用的动作ID列表, 列表中的动作将不被过滤. yii\base\ActionFilter
$only array 此过滤器应适用的动作ID列表, 仅列表中的动作被过滤. yii\base\ActionFilter
$owner yii\base\Component|null 该行为的所有者. yii\base\Behavior
$request yii\web\Request 当前请求. yii\filters\Cors
$response yii\web\Response 要发送的响应. yii\filters\Cors

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的已命名方法. yii\base\BaseObject
__construct() 构造函数. yii\base\BaseObject
__get() 返回对象属性的值. yii\base\BaseObject
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\BaseObject
__set() 设置对象属性的值. yii\base\BaseObject
__unset() 将对象属性设置为null. yii\base\BaseObject
addCorsHeaders() 将 CORS 标头添加到响应(response)中. yii\filters\Cors
afterAction() 执行动作后立即调用此方法. yii\base\ActionFilter
afterFilter() yii\base\ActionFilter
attach() 将行为对象附加到组件. yii\base\ActionFilter
beforeAction() 在执行动作之前(在所有可能的过滤器之后)立即调用该方法. yii\filters\Cors
beforeFilter() yii\base\ActionFilter
canGetProperty() 返回一个值, 指示属性是否可读. yii\base\BaseObject
canSetProperty() 返回一个值, 指示属性是否可写. yii\base\BaseObject
className() 返回此类的完全限定名称. yii\base\BaseObject
detach() 从组件中分离行为对象. yii\base\ActionFilter
events() 声明 所有者 事件的事件处理程序. yii\base\Behavior
extractHeaders() 从请求(request)中提取 CORS 标头. yii\filters\Cors
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\BaseObject
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\BaseObject
init() 初始化对象. yii\base\BaseObject
overrideDefaultSettings() 覆盖特定动作的设置. yii\filters\Cors
prepareHeaders() 为每个 CORS 标头创建特定的响应(response). yii\filters\Cors

受保护的方法

隐藏继承的方法

方法描述定义在
getActionId() 通过将 yii\base\Action::$uniqueId 转换为相对于模块的ID来返回动作ID. yii\base\ActionFilter
headerize() 将任何字符串(包括带有 HTTP 前缀的 php 标头)转换为标头格式. yii\filters\Cors
headerizeToPhp() 将任何字符串(包括带有 HTTP 前缀的 php 标头)转换为表头格式. yii\filters\Cors
isActive() 返回一个值, 指示过滤器对于给定动作是否处于活动状态. yii\base\ActionFilter
prepareAllowHeaders() 处理经典的 CORS 请求, 以避免重复代码. yii\filters\Cors

属性详情

$actions public 属性

为特定动作定义特定的 CORS 规则.

public array $actions = []
$cors public 属性

为 CORS 请求处理的基本标头.

  • Origin: 定义允许来源的数组, 可为['*'](任何用户, 默认), 或['http://www.myserver.net', 'http://www.myotherserver.com'];
  • Access-Control-Request-Method: 允许的动作列表, 如['GET', 'OPTIONS', 'HEAD'], 默认为['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
  • Access-Control-Request-Headers: 允许请求的头部类型列表, 可为['*'](所有类型, 默认), 或指定的类型如['X-Request-With'];
  • Access-Control-Allow-Credentials: 定义当前请求是否使用证书, 可为true, falsenull(不设置, 默认);
  • Access-Control-Max-Age: 定义请求的有效事件, 默认为86400;
  • Access-Control-Expose-Headers: 未知(权威指南没有说明, 待纠正).
public array $cors = ['Origin' => ['*'], 'Access-Control-Request-Method' => ['GET''POST''PUT''PATCH''DELETE''HEAD''OPTIONS'], 'Access-Control-Request-Headers' => ['*'], 'Access-Control-Allow-Credentials' => null'Access-Control-Max-Age' => 86400'Access-Control-Expose-Headers' => []]
$request public 属性

当前请求. 如果未设置, 将使用应用程序请求(request)组件.

public yii\web\Request $request null
$response public 属性

要发送的响应. 如果未设置, 将使用应用程序响应(response)组件.

方法详情

addCorsHeaders() public 方法

将 CORS 标头添加到响应(response)中.

public void addCorsHeaders ( $response, $headers )
$response yii\web\Response
$headers array

已计算的 CORS 头.

beforeAction() public 方法

在执行动作之前(在所有可能的过滤器之后)立即调用该方法.

你可以重写此方法, 以便为该动作做最后的准备.

public boolean beforeAction ( $action )
$action yii\base\Action

要执行的动作.

return boolean

该动作是否应该继续执行.

extractHeaders() public 方法

从请求(request)中提取 CORS 标头.

public array extractHeaders ( )
return array

要处理的 CORS 标头.

headerize() protected 方法

将任何字符串(包括带有 HTTP 前缀的 php 标头)转换为标头格式.

例如:

  • X-PINGOTHER -> X-Pingother
  • X_PINGOTHER -> X-Pingother
protected string headerize ( $string )
$string string

要转换的字符串.

return string

结果为 "header" 格式.

headerizeToPhp() protected 方法

将任何字符串(包括带有 HTTP 前缀的 php 标头)转换为表头格式.

例如:

  • X-Pingother -> HTTP_X_PINGOTHER
  • X PINGOTHER -> HTTP_X_PINGOTHER
protected string headerizeToPhp ( $string )
$string string

要转换的字符串.

return string

结果为 "php $_SERVER header" 格式.

overrideDefaultSettings() public 方法

覆盖特定动作的设置.

public void overrideDefaultSettings ( $action )
$action yii\base\Action

要覆盖的动作设置.

prepareAllowHeaders() protected 方法

处理经典的 CORS 请求, 以避免重复代码.

protected void prepareAllowHeaders ( $type, $requestHeaders, &$responseHeaders )
$type string

我们将处理的表头类型.

$requestHeaders array

客户端请求的 CORS 标头.

$responseHeaders array

发送到客户端的 CORS 响应标头.

prepareHeaders() public 方法

为每个 CORS 标头创建特定的响应(response).

public array prepareHeaders ( $requestHeaders )
$requestHeaders array

检测到的 CORS 标头.

return array

准备发送的 CORS 标头.