API 響應特性?
現代化的 PHP開發都需要構建 API ，不管它只是為了給 javascript 單頁應用提供數據還是作為獨立的產品。CodeIgniter 提供了一個API響應特性，可用于任何控制器，使公共響應類型簡單，無需記住它的 HTTP 狀態代碼應返回的響應類型。
使用示例?
下面的示例顯示了控制器中常見的使用模式。
<?php namespace App\Controllers;
class Users extends \CodeIgniter\Controller
{
use CodeIgniter\API\ResponseTrait;
public function createUser()
{
$model = new UserModel();
$user = $model->save($this->request->getPost());
// 響應 201 狀態碼
return $this->respondCreated();
}
}
在這個例子中，響應了 201 的HTTP狀態碼，并使用“創建”的通用狀態消息返回。方法存在于最常見的用例中
// 通用響應方式
respond($data, 200);
// 通用錯誤響應
fail($errors, 400);
// 項目創建響應
respondCreated($data);
// 項目成功刪除
respondDeleted($data);
// 客戶端未授權
failUnauthorized($description);
// 禁止動作
failForbidden($description);
// 找不到資源
failNotFound($description);
// Data 數據沒有驗證
failValidationError($description);
// 資源已存在
failResourceExists($description);
// 資源早已被刪除
failResourceGone($description);
// 客戶端請求數過多
failTooManyRequests($description);
處理響應類型?
當您通過以下任何一種方法傳遞數據時，它們將決定基于數據類型來格式化結果:
- 如果 $data 是一個字符串，它將被當作 HTML 發送回客戶端。
- 如果 $data 是一個數組，它將嘗試請求內容類型與客戶端進行協商，默認為 JSON。如果沒有在 ConfigAPI.php 中配置內容。默認使用
$supportedResponseFormats屬性。
需要使用格式化，請修改 Config/Format.php 文件配置。$supportedResponseFormats 包含了一個格式化響應類型列表。默認情況下，系統將會自動判斷并響應 XML 和 JSON 格式:
public $supportedResponseFormats = [
'application/json',
'application/xml'
];
這是在 Content Negotiation 中使用的數組，以確定返回的響應類型。如果在客戶端請求的內容和您支持的內容之間沒有匹配，則返回第一個該數組中的格式。
接下來，需要定義用于格式化數據數組的類。這必須是一個完全合格的類名，類名必須實現 CodeIgniterAPIFormatterInterface。格式化支持 JSON 和 XML
public $formatters = [
'application/json' => \CodeIgniter\API\JSONFormatter::class,
'application/xml' => \CodeIgniter\API\XMLFormatter::class
];
因此，如果您的請求在 Accept 頭中請求 JSON 格式的數據，那么您傳遞的數據數組就可以通過其中任何一個 respond* 或 fail* 方法將由 CodeIgniterAPIJSONFormatter 格式化。由此產生的 JSON 數據將被發送回客戶端。
引用類?
-
respond($data[, $statusCode=200[, $message='']])? 參數: - $data (mixed) – 返回客戶端的數據。字符串或數組。
- $statusCode (int) – 返回的HTTP狀態碼。默認為 200。
- $message (string) – 返回的自定義 “reason” 消息。
這是該特征中所有其他方法用于將響應返回給客戶端的方法。
$data元素可以是字符串或數組。 默認情況下，一個字符串將作為 HTML 返回，而數組將通過 json_encode 運行并返回為 JSON，除非 Content Negotiation 確定它應該以不同的格式返回。如果一個
$message字符串被傳遞，它將被用來替代標準的 IANA 標準碼回應狀態。但不是每個客戶端都會遵守自定義代碼，并將使用 IANA 標準匹配狀態碼。注解
由于它在活動的響應實例上設置狀態碼和正文，所以應該一直作為腳本執行中的最終方法。
-
fail($messages[, int $status=400[, string $code=null[, string $message='']]])? 參數: - $messages (mixed) – 包含遇到錯誤消息的字符串或字符串數組。
- $status (int) – 返回的HTTP狀態碼。 默認為400。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: 以客戶端的首選格式進行多部分響應。
這是用于表示失敗的響應的通用方法，并被所有其他“fail”方法使用。
該
$messages元素可以是字符串或字符串數??組。 該$status參數是應返回的HTTP狀態碼。由于使用自定義錯誤代碼更好地提供了許多 API，因此可以在第三個參數中傳遞自定義錯誤代碼。如果沒有值，它將是一樣的
$status【狀態碼】。如果一個
$message字符串被傳遞，它將被用于代替響應狀態的標準 IANA 碼。不是每個客戶端都會遵守自定義代碼，并且將使用與狀態代碼相匹配的 IANA 標準。這個響應是一個包含兩個元素的數組：
error和messages。error元素包含錯誤的狀態代碼。messages元素包含一組錯誤消息。它看起來像:$response = [ 'status' => 400, 'code' => '321a', 'messages' => [ 'Error message 1', 'Error message 2' ] ];
-
respondCreated($data[, string $message = ''])? 參數: - $data (mixed) – 返回給客戶端的數據。字符串或數組。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置創建新資源時使用的相應狀態代碼，通常為201:
$user = $userModel->insert($data); return $this->respondCreated($user);
-
respondDeleted($data[, string $message = ''])? 參數: - $data (mixed) – 返回給客戶端的數據。字符串或數組
- $message (string) – 自定義的“原因”消息返回。
返回: Response 對象的 send()方法的值。
設置當通過此API調用的結果刪除新資源時使用的相應狀態代碼（通常為200）。
$user = $userModel->delete($id); return $this->respondDeleted(['id' => $id]);
參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置當用戶未被授權或授權不正確時使用的相應狀態代碼。狀態碼為401。
return $this->failUnauthorized('Invalid Auth token');
-
failForbidden(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
不像
failUnauthorized，當請求 API 路徑決不允許采用這種方法。未經授權意味著客戶端被鼓勵再次嘗試使用不同的憑據。禁止意味著客戶端不應該再次嘗試，因為它不會有幫助。狀態碼為403。return $this->failForbidden('Invalid API endpoint.');
-
failNotFound(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于在找不到請求的資源時使用的狀態碼。狀態碼為404。
return $this->failNotFound('User 13 cannot be found.');
-
failValidationError(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于客戶端發送的數據未通過驗證規則時使用的狀態碼。狀態碼通常為400。
return $this->failValidationError($validation->getErrors());
-
failResourceExists(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于當客戶端嘗試創建的資源已經存在時使用的狀態碼。狀態碼通常為409。
return $this->failResourceExists('A user already exists with that email.');
-
failResourceGone(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于當請求的資源先前被刪除并且不再使用時使用的狀態碼。狀態碼通常為410。
return $this->failResourceGone('That user has been previously deleted.');
-
failTooManyRequests(string $description[, string $code=null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于當客戶端調用 API路徑次數過多時使用的狀態碼。這可能是由于某種形式的節流或速率限制。狀態碼通常為400。
return $this->failTooManyRequests('You must wait 15 seconds before making another request.');
-
failServerError(string $description[, string $code = null[, string $message = '']])? 參數: - $description (mixed) – 顯示用戶的錯誤信息。
- $code (string) – 一個自定義的API特定的錯誤代碼。
- $message (string) – 返回的自定義“reason”消息。
返回: Response 對象的 send()方法的值。
設置于當存在服務器錯誤時使用的狀態碼。
return $this->failServerError('Server error.');