访问请求对象

CakeRequest 提供了数种访问请求参数的接口。一是使用对象属性，二是使用数组索引，三是通过 $this->request->params：

1 $this->request->controller;
2 $this->request['controller'];
3 $this->request->params['controller'];

除了 路由元素 ，还经常需要访问 传递参数 和 命名参数。这此在请求对象中也都可用：

1 $this->request->controller;
2 $this->request['controller'];
3 $this->request->params['controller'];

• plugin 处理请求的插件，没有插件时为空（null）。
• controller 处理当前请求的控制器。
• action 处理当前请求的动作。
• prefix 当前动作的前缀。更多信息参见 前置路由 。
• bare 在请求来自 requestAction() 并且包含 bare 选项时出现。Bare 请求没有要渲染的布局。
• requested 当动作来自 requestAction 时出现并被设置为 true。

访问 query 参数

query 参数可以用 CakeRequest::$query 读取：

1 // url 为 /posts/index?page=1&sort=title
2 $this->request->query['page'];
3
4 // 也可以用数组形式来访问
5 $this->request['url']['page']; // BC 存取器，将在未来版本中被废弃

1 $foo = $this->request->query('value_that_does_not_exist');
2 // $foo === null

所有的 POST 数据都可以用 CakeRequest::$data 访问。包含 data 前缀的任意数据，其数据前缀都会被删除。例如：

1 // An input with a name attribute equal to 'data[MyModel][title]' is accessible at
2 $this->request->data['MyModel']['title'];

1 $foo = $this->request->data('Value.that.does.not.exist');
2 // $foo == null

2.2 新版功能.

在创建 REST 服务时，常常在 PUT 和 DELETE 接受请求数据。2.2 版中，所有 application/x-www-form-urlencoded请求的主体数据将自动解析并且设置为 $this->data 的 PUT 和 DELETE 请求。如果你接收 JSON 或者 XML 数据，参看后文中如何访问这些请求的部分。

访问 XML 或者 JSON 数据

应用程序经常使用 REST 非 URL 编码的 post 体之间交换数据。你可以以任意格式使用 CakeRequest::input() 访问 input 数据。 通过提供解码功能，你可以接受反序列化形式的内容：

1 // 获取提交给 PUT/POST 动作的 JOSN 编码数据
2 $data = $this->request->input('json_decode');

1 // Get Xml encoded data submitted to a PUT/POST action
2 $data = $this->request->input('Xml::build', array('return' => 'domdocument'));

CakeRequest 还提供关于应用程序路径的有用信息。 CakeRequest::$base 和 CakeRequest::$webroot 用于生成 url，并确定应用程序是否在一个子文件夹内。

检查请求

以前使用 RequestHandlerComponent 检测各种请求条件。这些方法已经被移到 CakeRequest，并且新的接口（包含多个与回调兼容的用法）：

1 $this->request->is('post');
2 $this->request->isPost();

• 环境值对比 - 一个环境值对比，对比来自 env() 的值和环境变量中已知的值是否来检测所提供的值是否相等。
• 模式值对比 - 模式值对比允许你对比来自 env() 的值和正则表达式。
• 基于选项的对比 - 基于选项的对比使用一个选项列表建立一个正则表达式。后续调用加入一个已经定义选项的探察器来合并选项。
• 回调探察器 - 回调发现都允许你提供一个 ‘回调’ 类型来处理检测。回调将接受请求对象作为它的唯一参数。

这有一些例子：

 1 // 添加环境探察器。
 2 $this->request->addDetector('post', array('env' => 'REQUEST_METHOD', 'value' => 'POST'));
 3
 4 // 添加模式值探察器。
 5 $this->request->addDetector('iphone', array('env' => 'HTTP_USER_AGENT', 'pattern' => '/iPhone/i'));
 6
 7 // 添加选项探察器。
 8 $this->request->addDetector('internalIp', array(
 9     'env' => 'CLIENT_IP',
10     'options' => array('192.168.0.101', '192.168.0.100')
11 ));
12
13 // 添加回调探察器。可以是匿名函数或者定时调用。
14 $this->request->addDetector('awesome', array('callback' => function ($request) {
15     return isset($request->awesome);
16 }));

下面是一些可用的内置探察器：

• is('get') 检测当前的请求是否是一个 GET。
• is('put') 检测当前的请求是否是一个 PUT.
• is('post') 检测当前的请求是否是一个 POST.
• is('delete') 检测当前的请求是否是一个 DELETE.
• is('head') 检测当前的请求是否是一个 HEAD.
• is('options') C检测当前的请求是否是 OPTIONS.
• is('ajax') 检测当前的请求是否是来自 X-Requested-with = XmlHttpRequest.
• is('ssl') 检测当前的请求是否经过 SSL
• is('flash') 检测当前的请求是否有一个 Flash 用户代理
• is('mobile') 检测当前的请求是否来自移动代理。

CakeRequest 和 RequestHandlerComponent

由于``CakeRequest`` 提供的过去用于 RequestHandlerComponent 的一些特性，被要求反思如何仍然适合图片。对于 2.0， RequestHandlerComponent 扮演了一个甜心爹爹的角色。在 CakeRequest 提供的功能的顶层挂了一层糖。所谓的糖就是在 RequestHandlerComponent 范围内，基于内容的类型或者 ajax 切换布局和视图。这种分隔两类的工具和糖，让你更易于区分和选择你想要的和你需要的。

与其它层面的请求互动

你可以使用 CakeRequest 反观关于请求的各种事物。除了探察器，你还能找到来自各种属性和方法的其他信息。

• $this->request->webroot 表示 web 根目录。
• $this->request->base 表示基目录。
• $this->request->here 表示当前请求的完整地址。
• $this->request->query 包含 query 字符串参数。

CakeRequest API

class CakeRequest

CakeRequest 压制 request 参数句柄和反视。

CakeRequest::domain($tldLength = 1)

返回正在运行的应用程序的域。

CakeRequest::subdomains($tldLength = 1)

以数组形式返回应用程序的子域。

CakeRequest::host()

返回应用程序的主机。

CakeRequest::method()

返回请求所用的 HTTP 方式。

CakeRequest::onlyAllow($methods)

设置允许的 HTTP 方式，如果不匹配则抛出 MethodNotAllowexException。 这个伴随传送方法的 405 输出包含必须的 ‘Allow’ 头。 The 405 response will include the required ‘Allow’ header with the passed methods

2.3 新版功能.

CakeRequest::referer($local = false)

返回请求的来源地址。

CakeRequest::clientIp($safe = true)

返回当前访问者的 IP 地址。

CakeRequest::header($name)

允许你使用此请求访问任意的 HTTP_* 头。

1 $this->request->header('User-Agent');

将返回此请求使用的用户代理。

CakeRequest::input($callback[, $options])

从请求中获取 input 数据，并且可以向其传递一个解码函数。附加的参数中的解码函数可以被作为传递给 input()。

CakeRequest::data($name)

提供 点表示法 访问请求数据。允许读取和修改请求数据，调用也可以串联在一起：

1 // 修改部分请求数据，以使你能够预一些表单域。
2 $this->request->data('Post.title', 'New post')
3     ->data('Comment.1.author', 'Mark');
4
5 // 你也能读出数据。
6 $value = $this->request->data('Post.title');

CakeRequest::query($name)

提供 点表示法 访问 url query 数据：

1 // url 为 /posts/index?page=1&sort=title
2 $value = $this->request->query('page');

2.3 新版功能.

CakeRequest::is($type)

检查一个请求是否符合某个标准。应用内置的匹配规则或者通过 CakeRequest::addDetector() 定义的任意附加规则。

CakeRequest::addDetector($name, $options)

添加一个用于 is() 的探察器。更多信息参见 检查请求 。

CakeRequest::accepts($type = null)

找出客户端接受的内容类型，或者检测它们接受的特定内容的类型。

获取全部类型

1 $this->request->accepts();

检查单个类型

1 $this->request->accepts('application/json');

static CakeRequest::acceptLanguage($language = null)

获取客户端期望的全部语言，或者检测被接受的一个特定语言。

获取被接受的语言的列表

1 CakeRequest::acceptLanguage();

检测一个指定的被接受的语言

1 CakeRequest::acceptLanguage('es-es');

property CakeRequest::$data

POST 数据的数组。作为防止错误提示的一种方式，你可以使用 CakeRequest::data() 读取这个属性。

property CakeRequest::$query

query 字符串参数数组。

property CakeRequest::$params

路由元素和请求参数数组。

property CakeRequest::$here

返回当前请求的 uri。

property CakeRequest::$base

应用程序的基路径，通常是 /，除非你的应用程序放在子目录中。

property CakeRequest::$webroot

当前 web 根目录

变化中的响应类

CakePHP 默认使用 CakeResponse。 CakeResponse 对于使用类是灵活透明的。不过如果你需要在应用程序的特定类中替换它，你使用自己的类覆盖或替换 CakeResponse 。通过替换在 index.php 中使用的 CakePHPResponse。

这会使你的应用程序中的所有控制器都用 CustomResponse 代替 CakeResponse。 你也可以在控制器中设置 $this->response 来替换 response 实例。 在测试过程中覆盖这个 response 对象很有用，它允许你 stub 与 header() 一起工作的方法。 更多的信息请参见 CakeResponse 与测试 一节。

处理内容类型

你可以使用 CakeResponse::type() 控制应用程序响应的 内容类型（Content-Type）。如果你的应用程序需要处理没有内置在 CakeResponse 中的内容类型，你还可以使用 type() 映射它们：

1 // 添加 vCard 类型
2 $this->response->type(array('vcf' => 'text/v-card'));
3
4 // 将响应的 Content-Type 设置为 vcard.
5 $this->response->type('vcf');

传输文件

有时候你需要为请求发送文件作为对其的响应。 在 2.3 版之前你可以使用 媒体视图 来实现。 在 2.3 版，MediaView 被废弃，现在你可以使用 CakeResponse::file() 传送文件来响应：

1 public function sendFile($id) {
2     $file = $this->Attachment->getFile($id);
3     $this->response->file($file['path']);
4 }

如果你只想让文件显示在浏览器中，禁止文件被下载，可以指定如下选项：

1 $this->response->file($file['path'], array('download' => true, 'name' => 'foo'));

设置 headers 使用的是 CakeResponse::header() 方法。 它能以不同的参数配置调用：

1 // 设置单个 header
2 $this->response->header('Location', 'http://example.com');
3
4 // 设置多个 headers
5 $this->response->header(array('Location' => 'http://example.com', 'X-Extra' => 'My header'));
6 $this->response->header(array('WWW-Authenticate: Negotiate', 'Content-type: application/pdf'));

与浏览器缓存交互

有时你需要禁止浏览器缓存控制器动作的结果。 CakeResponse::disableCache() 就是用来干这个的：:

1 public function index() {
2     // do something.
3     $this->response->disableCache();
4 }

你也可以使用 CakeResponse::cache() 告诉客户端你想要它们缓存响应：

1 public function index() {
2     //do something
3     $this->response->cache('-1 minute', '+5 days');
4 }

HTTP 缓存微调

提高应用程序的访问速度的一个又好又容易的办法是使用 HTTP 缓存。 在这种模式下，你只需要通过设置几个 header （如编辑时间、响应实体及其它）来帮助客户端决定是否使用响应的缓存副本。

反对使用代码逻辑处理 缓存和在数据改变时失效（刷新），HTTP 的过期和校验两种模式常常比自己管理缓存更简单。

除了 CakeResponse::cache() ，你还可以使用另外一些方法实现 HTTP 缓存头来利用浏览器或反向代理缓存。

1 Cache-Control: private, max-age=3600, must-revalidate

 1 public function view() {
 2     ...
 3     // set the Cache-Control as public for 3600 seconds
 4     $this->response->sharable(true, 3600);
 5 }
 6
 7 public function my_data() {
 8     ...
 9     // set the Cache-Control as private for 3600 seconds
10     $this->response->sharable(false, 3600);
11 }

1 public function view() {
2     $this->response->expires('+5 days');
3 }

1 public function index() {
2     $articles = $this->Article->find('all');
3     $this->response->etag($this->Article->generateHash($articles));
4     if ($this->response->checkNotModified($this->request)) {
5         return $this->response;
6     }
7     ...
8 }

1 public function view() {
2     $article = $this->Article->find('first');
3     $this->response->modified($article['Article']['modified']);
4     if ($this->response->checkNotModified($this->request)) {
5         return $this->response;
6     }
7     ...
8 }

1 $this->response->vary('User-Agent');
2 $this->response->vary('Accept-Encoding', 'User-Agent');
3 $this->response->vary('Accept-Language');

CakeResponse 的最大的胜利也许是来自它使测试控制器和组件变得更容易了。代替遍布多个对象的方法，仅使用一个 mock 对象作为委托给控制器和组件的 CakeResponse 。这会帮助你走近 ‘unit’ 测试并使测试控制器更容易：

1 public function testSomething() {
2     $this->controller->response = $this->getMock('CakeResponse');
3     $this->controller->response->expects($this->once())->method('header');
4     // ...
5 }

CakeResponse API

class CakeResponse

CakeResponse 提供了一些与你传送给客户端的响应交互的有用的方法。

CakeResponse::header($header = null, $value = null)

允许你直接设置一个或多个与响应同时传送的 header。

CakeResponse::charset($charset = null)

设置在响应中使用的字符集。

CakeResponse::type($contentType = null)

设置响应的内容类型。你可以使用已知类型的别名或者类型的命名。

CakeResponse::cache($since, $time = '+1 day')

允许你在响应中设置 cache header。

CakeResponse::disableCache()

设置这个 header 将禁止客户端缓存响应。

CakeResponse::sharable($public = null, $time = null)

将 Cache-Control header 设置成 public 或者 private ，选择性的设置资源的 max-age 指令。

2.1 新版功能.

CakeResponse::expires($time = null)

允许你将 Expires header 设置为确切日期。

2.1 新版功能.

CakeResponse::etag($tag = null, $weak = false)

为响应资源设置唯一的 Etag 标识。

2.1 新版功能.

CakeResponse::modified($time = null)

以正确的格式将 Last-Modified header 设置为一个确切日期。

2.1 新版功能.

CakeResponse::checkNotModified(CakeRequest $request)

比较请求对象的 cache header 和 响应的 cache header，确定其是否仍然有效。如果仍然有效，则删除所有响应内容，并传送 304 Not Modified header。

2.1 新版功能.

CakeResponse::compress()

为请求撕开 gzip 压缩。

CakeResponse::download($filename)

允许你以附件的形式传送响应，并设置文件名。

CakeResponse::statusCode($code = null)

允许你设置响应的状态码。

CakeResponse::body($content = null)

为响应设置内容主体。

CakeResponse::send()

一旦你建立了响应，调用 send() 将传送全部 heaer 和主体内容。在每个请求中，这是通过 Dispatcher 自动完成的。

CakeResponse::file($path, $options = array())

允许你为显示或下载设置一个文件。

2.3 新版功能.