Class yii\filters\ContentNegotiator

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

ContentNegotiator 支持响应格式处理和应用程序语言处理.

当指定 支持的格式 属性时, ContentNegotiator 将支持基于 GET 参数 $formatParamAccept HTTP 标头值的响应格式处理. 如果找到匹配项, yii\web\Response::$format 属性将设置为所选格式. yii\web\Response::$acceptMimeType 以及 yii\web\Response::$acceptParams 也将相应的更新.

当指定 支持的语言 时, ContentNegotiator 将基于 GET 参数 $languageParamAccept-Language HTTP 标头值来支持应用程序语言处理. 如果找到匹配项, yii\base\Application::$language 属性将被设置为所选语言.

你可以使用 ContentNegotiator 作为引导组件以及动作过滤器.

以下代码显示了如何将 ContentNegotiator 用作引导组件. 请注意, 在这种情况下, 内容处理适用于整个应用程序.

// 在应用程序配置中
use yii\web\Response;

return [
    'bootstrap' => [
        [
            'class' => 'yii\filters\ContentNegotiator',
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
                'application/xml' => Response::FORMAT_XML,
            ],
            'languages' => [
                'en',
                'de',
            ],
        ],
    ],
];

以下代码显示了如何在控制器或模块中将 ContentNegotiator 用作动作筛选器. 在这种情况下, 内容处理结果仅适用于相应的控制器或模块; 或者如果你配置了过滤器的onlyexcept属性, 则仅适用于特定的动作.

use yii\web\Response;

public function behaviors()
{
    return [
        [
            'class' => 'yii\filters\ContentNegotiator',
            'only' => ['view', 'index'],  // 在控制器中
            // 如果在模块中, 请为用户动作使用以下 ID
            // 'only' => ['user/view', 'user/index']
            'formats' => [
                'application/json' => Response::FORMAT_JSON,
            ],
            'languages' => [
                'en',
                'de',
            ],
        ],
    ];
}

公共属性

隐藏继承的属性

属性类型描述定义在
$except array 此过滤器不适用的动作ID列表, 列表中的动作将不被过滤. yii\base\ActionFilter
$formatParam string 指定响应格式的 GET 参数的名称. yii\filters\ContentNegotiator
$formats array 支持的响应格式列表. yii\filters\ContentNegotiator
$languageParam string 指定 应用程序语言 的 GET 参数的名称. yii\filters\ContentNegotiator
$languages array 支持的语言列表. yii\filters\ContentNegotiator
$only array 此过滤器应适用的动作ID列表, 仅列表中的动作被过滤. yii\base\ActionFilter
$owner yii\base\Component|null 该行为的所有者. yii\base\Behavior
$request yii\web\Request 当前请求. yii\filters\ContentNegotiator
$response yii\web\Response 要发送的响应. yii\filters\ContentNegotiator

公共方法

隐藏继承的方法

方法描述定义在
__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
afterAction() 执行动作后立即调用此方法. yii\base\ActionFilter
afterFilter() yii\base\ActionFilter
attach() 将行为对象附加到组件. yii\base\ActionFilter
beforeAction() 在执行动作之前(在所有可能的过滤器之后)立即调用该方法. yii\filters\ContentNegotiator
beforeFilter() yii\base\ActionFilter
bootstrap() 在应用程序(application)引导阶段要调用的 Bootstrap 方法. yii\filters\ContentNegotiator
canGetProperty() 返回一个值, 指示属性是否可读. yii\base\BaseObject
canSetProperty() 返回一个值, 指示属性是否可写. yii\base\BaseObject
className() 返回此类的完全限定名称. yii\base\BaseObject
detach() 从组件中分离行为对象. yii\base\ActionFilter
events() 声明 所有者 事件的事件处理程序. yii\base\Behavior
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\BaseObject
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\BaseObject
init() 初始化对象. yii\base\BaseObject
negotiate() 处理响应格式和应用程序语言. yii\filters\ContentNegotiator

受保护的方法

隐藏继承的方法

方法描述定义在
getActionId() 通过将 yii\base\Action::$uniqueId 转换为相对于模块的ID来返回动作ID. yii\base\ActionFilter
isActive() 返回一个值, 指示过滤器对于给定动作是否处于活动状态. yii\base\ActionFilter
isLanguageSupported() 返回一个值, 指示请求的语言是否与支持的语言相匹配. yii\filters\ContentNegotiator
negotiateContentType() 处理响应格式. yii\filters\ContentNegotiator
negotiateLanguage() 处理应用程序语言. yii\filters\ContentNegotiator

属性详情

$formatParam public 属性

指定响应格式的 GET 参数的名称.

Note: 如果 $formats 中不存在指定的格式, 则将抛出 yii\web\NotAcceptableHttpException 异常. 如果参数值为空或者此属性为null, 则仅基于Accept HTTP 标头值确定响应格式.

参见 $formats.

public string $formatParam '_format'
$formats public 属性

支持的响应格式列表.

数组键是 MIME 类型(eg. application/json), 而数组值是相应的格式(eg. html, json), 它们必须是在 yii\web\Response::$formatters 中声明的格式.

如果此属性为空或未设置, 将跳过响应格式处理.

public array $formats null
$languageParam public 属性

指定 应用程序语言 的 GET 参数的名称.

Note: 如果指定的语言与 $languages 中的任何一个都不匹配, 则将使用 $languages 中的第一种语言. 如果参数值为空或此属性未null, 则仅基于Accept-Language HTTP 标头值确定应用程序语言.

参见 $languages.

public string $languageParam '_lang'
$languages public 属性

支持的语言列表.

数组键是支持的语言代码(eg. en-GB, en-US), 而数组值是应用程序识别的相应语言代码(eg. en, de).

数组键并非总是必需的. 如果数组值没有键, 则所需语言的匹配将基于语言回退机制. 例如, en的值将匹配en, en_US, en-US, en-GB等.

如果此属性为空或未设置, 则将跳过语言处理.

public array $languages null
$request public 属性

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

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

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

方法详情

beforeAction() public 方法

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

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

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

要执行的动作.

return boolean

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

bootstrap() public 方法

在应用程序(application)引导阶段要调用的 Bootstrap 方法.

public void bootstrap ( $app )
$app yii\base\Application

当前正在运行的应用程序(application).

isLanguageSupported() protected 方法

返回一个值, 指示请求的语言是否与支持的语言相匹配.

protected boolean isLanguageSupported ( $requested, $supported )
$requested string

请求的语言代码.

$supported string

受支持的语言代码.

return boolean

Whether 请求的语言是否支持.

negotiate() public 方法

处理响应格式和应用程序语言.

public void negotiate ( )
negotiateContentType() protected 方法

处理响应格式.

protected void negotiateContentType ( $request, $response )
$request yii\web\Request
$response yii\web\Response
throws yii\web\BadRequestHttpException

如果接收到 GET 参数 $formatParam 数组.

throws yii\web\NotAcceptableHttpException

如果不接受任何请求的内容类型.

negotiateLanguage() protected 方法

处理应用程序语言.

protected string negotiateLanguage ( $request )
$request yii\web\Request
return string

所选的语言.