Rest 控制器 - 一般

Rest 控制器是什幺？

Rest 控制器是 Base 控制器的扩充并内建支援 RESTful。 这能让你轻鬆建立 API。

请注意： 如果你在你的 REST 控制器使用 before() 或 router 方法， 你 必须 呼叫父层方法 parent::before()（或路由）以保持正常运作。

使用 Rest 控制器

如同所有的控制器，你在 fuel/app/classes/controller 目录里建立一个类别。 它们需要扩充 Controller_Rest 类别并且预设前缀为 "Controller_"。 下面是一个控制器 "test" 的範例：

class Controller_Test extends Controller_Rest
{

	public function get_list()
	{
		return $this->response(array(
'foo' => Input::get('foo'),
'baz' => array(
	1, 50, 219
),
'empty' => null
		));
	}
}

此控制器的 "list" 方法被以下的 URL 呼叫：

http://localhost/test/list.json?foo=bar

你会注意到，Rest 控制器使用 HTTP 方法做为前缀，而不是常见的 "action_"。 当没有发现相对应于 HTTP 方法前缀的方法时，将退回到 "action_" 前缀。 Rest 控制器支援所有常见的 HTTP 方法，比如：

这不是一个限制性的清单，FuelPHP 框架接受任何你网页伺服器接受的 HTTP 方法。

输出

{
	"foo":"bar",
	"baz":[1,50,219],
	"empty":null
}

这输出为 json，因为副档名被定义在 URL。预设情况下， 回应将被格式化为 XML 或其他设定在 fuel/core/config/rest.php 中的格式。

配置

REST 控制器可以透过 fuel/core/config/rest.php 配置档案全域地配置。 它已经填入了一个预设配置。你可以透过添加一个同名的配置档案到你应用程序的 config 目录来覆写此配置， 并在这里设定你想要变更的值。 这些将覆写核心配置，但保留你没有覆写的部份。

以下的全域配置值可以被定义：

'xml'

'xml'

'REST API'

''

array('admin' => '1234')

false

支援格式

• xml - 几乎任何程式语言可以阅读 XML
• json - 对 JavaScript 和越来越多的 PHP 应用程序来说很有用
• csv - 用试算表程式开启
• html - 任何经由你方法回传的字串
• php - 可以被 eval() 执行的 PHP 程式码表示形式
• serialize - 可以在 PHP 中被反序列化的序列化资料

如果你的控制器方法回传一个阵列，但请求的输出格式是阵列不能被转换的（例如 html）， 当你的应用程序运行在一个生产环境时，你会得到一个 406 NOT ACCEPTABLE 状态， 或在任何其他环境时， 是一个警告讯息以及一个阵列倒出的 JSON。

确定格式

要确定结果应该被回传的格式，REST 控制器使用以下的演算法：

• 使用 protected 特性 $format 如果它包含一个支援的格式
• 使用 URL 扩充如果它包含一个支援的格式
• 使用被指定在路径中的 :format 变数的格式如果它包含一个支援的格式
• 使用指定在请求 format 变数中的格式
• 使用定义在 HTTP_ACCEPT 表头的格式
• 使用你类别的 $rest_format 特性所定义的预设值
• 使用定义在全域配置档案的 default_format 值

在大多数情况下，HTTP_ACCEPT 会呈现并包含（至少）text/html，这是一个有效的结果格式。 这意味着 $rest_format、以及任何定义在 rest.php 配置档案中的全域预设， 将永远不会被使用。

要停用 HTTP_ACCEPT 做为一个有效的格式来源， 设定在 rest.php 里的 ignore_http_accept 配置键为 true。

请注意，在你的 REST 控制器硬写任何结果格式被认为是不好的做法。 它应该是由客户端指定应该回传的结果格式。在 HTTP_ACCEPT 的情况下，大多数 ajax 解决方案，例如 jQuery.ajax()，允许你设定接收表头为 application/json。

XML 基本节点名称

当使用 XML 输出你可以透过设定 $xml_basenode 参数来设定 XML 基本节点。

class Controller_Test extends Controller_Rest
{
	// 设定给全控制器
	protected $xml_basenode = 'my_basenode';

	// 或在你的控制器函式内
	public function get_items()
	{
		$this->xml_basenode = 'other_basenode';

		return $this->response(array(
'foo' => Input::get('foo'),
'baz' => array(
	1, 50, 219
),
'empty' => null
		));
	}
}

特殊控制器方法