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 方法，比如：

HTTP 方法	描述
GET	用於取出關於现有資源的資訊。當你輸入一个 URL 并前往瀏覽，或當你點下一个連結，这会被瀏覽器使用。所以它適合取回在你資源（如使用者）的資訊。表单也可以使用此方法來取回送交查詢字串的資訊（即搜尋表单）。
POST	用於建立新資源。由於 HTML 支援 PUT 方法的不足，它也被用於更新資源。大多数表单使用 POST 方法，除了當它們打算取回送交查詢字串的資訊。
PUT	用於建立或更新有已知 ID 的資源。你被預期傳遞所有特性。遺漏的應該被設为 NULL。較不常用因为還不被 HTML（5）支援。雖然大多数的瀏覽器支援 XMLHttpRequests。
DELETE	用於刪除现有資源。如同 PUT，不被 HTML（5）支援但大多数瀏覽器支援 XMLHttpRequests。
PATCH	用於更新有已知 ID 的資源。你只傳遞你想要更新的特性。較不常用因为還不被 HTML（5）支援。雖然大多数的瀏覽器支援 XMLHttpRequests。

这不是一个限制性的清单，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 目录來覆寫此配置，并在这裡設定你想要變更的值。这些将覆寫核心配置，但保留你沒有覆寫的部份。

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

參数	类型	預設	描述
default_format	字串	`'xml'`	要回傳結果的預設格式。这只用在控制器中沒定義格式，而且所有自动檢测機制失效時。
xml_basenode	字串	`'xml'`	要被用在輸出 XML 結構時的基本節點 XML 标籤。
realm	字串	`'REST API'`	受密码保護的 REST API 顯示在登入對話框的名稱。
auth	字串	`''`	定義所需的認證类型。有效的值有 'basic' 和 'digest'。你也可以定義一个必須被呼叫來檢查認證的控制方法名稱。此方法可能回傳一个布林。（true 将允許請求，false 将回傳一个預設的 401 回應），或一个 Response 物件。留空如果沒有認證需要被执行。
valid_logins	字串	`array('admin' => '1234')`	一个鍵／值配對的陣列，为 'basic' 和 'digest' 授权方法定義有效的使用者名稱及密码。
ignore_http_accept	布林	`false`	HTTP_ACCEPT 表頭是否應該在一个 REST 請求被解析，以確定回傳的格式。

支援格式

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
		));
	}
}

特殊控制器方法

response($data = array(), $http_code = 200)

此方法是用來透過格式化和輸出邏輯傳送你的回應資料。你可以選擇性的設定一个狀態码做为第二參数。