HTTP 消息?

消息類為HTTP消息中的請求和響應的實現提供了一個通用的接口，包括消息體，協議版本，處理消息頭的工具和一些進行內容協商的方法。

該類是 請求類 和 響應類 共有的父類。 因此某些方法，例如內容協商方法等，可能只適用于請求和響應，而對于其他方法不適用，但是我們將其聚合在該類中 從而使得處理頭的方法可以定義在相同的位置。

什么是內容協商?

內容協商的核心機制，其實只是HTTP實現的一個簡單的部分，即允許單個資源適用于不止一種內容類型，從而允許客戶端選擇適合自己的數據類型。

一個典型的案例就是，該瀏覽器無法播放PNG格式的文件，并且只能請求GIF或者JPEG格式的圖片文件。而當資源服務器接收到該請求時， 它將會檢查可用的文件類型是否能滿足客戶端所請求的，并選擇本身所支持的格式中，最為適合的圖片格式，在本例中就可能會返回一個JPEG的圖片文件。

同樣的協商方式會在以下四種數據類型中提現:

  • 媒體/文檔類型 - 可以是圖片的類型格式，或者是HTML、XML或JSON.
  • 字符集Character Set - 該文檔所屬的字符集，通常是UTF-8
  • 文檔編碼Document Encoding - 通常是返回結果的壓縮類型（譯者注：例如gzip）
  • 文檔語言Document Language - 對于支持多語言的站點，有助于決定返回哪種語言格式

類的參考文檔?

CodeIgniter\HTTP\Message
body()?
返回:當前的消息體
返回類型:string

返回當前消息的實體部分，如果實體不存在或者已經被發送過，返回null:

echo $message->body();
setBody([$str])?
參數:
  • $str (string) – 消息體對應的字符串.
返回:

該消息實例，用于鏈式調用
返回類型:

CodeIgniter\HTTP\Message 實例.

設置當前請求的實體內容
populateHeaders()?
返回:void

掃描并處理SERVER數據中找到的請求頭內容，并將其存儲以供下次使用。該方法用于 請求類 Class 從而使得當前的請求頭內容可被使用.

這里所指的請求頭實際上是所有以 HTTP_ 開頭的SERVER數據，例如 HTTP_POST 。每個消息都會從被從標準的大小寫格式轉換為首字母大寫并以橫線(-)連接的格式。 并移除了開頭的 HTTP_ 部分，故而 HTTP_ACCEPT_LANGUAGE 變成了 Accept-Language 。

getHeaders()?
返回:一個包括了所有能確定的頭部的數組.
返回類型:array

返回所有能確定或者是先前設定過的頭

getHeader([$name[, $filter = null]])?
參數:
  • $name (string) – 你想要獲取對應的值的頭的名字
  • $filter (int) – 所需要使用的過濾器類型。可供使用的過濾器見表 過濾器 。
返回:

當前頭的值。如果該頭有多個值，就會以數組的形式返回
返回類型:

string|array|null

使你可以獲取單個消息頭的當前值。 $name 對應的是大小寫敏感的頭名。由于在上述例子中已經對頭進行了內部轉換，你可以通過任何大小寫方式格式來傳值:

// 這些都等同:
$message->getHeader('HOST');
$message->getHeader('Host');
$message->getHeader('host');

如果該頭有多個值，就會以數組的形式返回. 你可以使用 headerLine() 方法來將這些數據轉換為字符串的形式來返回:

echo $message->getHeader('Accept-Language');

// 輸出如下:
[
        'en',
        'en-US'
]

你可以通過將過濾器的值作為第二個參數傳遞給該函數:

$message->getHeader('Document-URI', FILTER_SANITIZE_URL);
headerLine($name)?
參數:
  • $name (string) – 需要獲取的頭的名字.
返回:

頭所對應的值（字符串形式）
返回類型:

string

將該頭對應的值以字符串形式返回。該方法使得你可以在該頭對應多個值時，將頭對應的值輕松地以字符串形式返回。值以逗號分隔形式:

echo $message->headerLine('Accept-Language');

// 輸出:
en, en-US
setHeader([$name[, $value]])
參數:
  • $name (string) – 需要設置值的頭的名字
  • $value (mixed) – 需要設置的值
返回:

當前消息實例
返回類型:

CodeIgniter\HTTP\Message

為單個頭賦值。 $name 是該頭所對應的大小寫敏感的命名。如果該頭部當前不存在就會被創建。$value 可以是字符串或者一個字符串數組:

$message->setHeader('Host', 'codeigniter.com');
removeHeader([$name])?
參數:
  • $name (string) – 需要移除的頭的名字.
返回:

當前消息實例
返回類型:

CodeIgniter\HTTP\Message

從消息中移除指定頭. $name 是該頭所對應的大小寫敏感的命名:

$message->remove('Host');
appendHeader([$name[, $value]]))?
參數:
  • $name (string) – 需要修改的頭的名字
  • $value (mixed) – 需要為該頭增加的值
返回:

當前消息實例
返回類型:

CodeIgniter\HTTP\Message

為一個現存的頭增加值。該頭的值不可以是單個字符串，必須是一個數組。如果是單個字符串的話會拋出一個 LogicException 異常

$message->appendHeader('Accept-Language', 'en-US; q=0.8');
protocolVersion()?
返回:當前HTTP協議版本
返回類型:string

返回當前消息對應的HTTP 協議版本，如果沒有設定過的話就會返回 null ，可選值為 1.0 和 1.1 。

setProtocolVersion($version)?
參數:
  • $version (string) – HTTP協議版本
返回:

當前消息實例
返回類型:

CodeIgniter\HTTP\Message

為當前消息所使用的HTTP協議設定版本。可賦值為 1.0 或 1.1:

$message->setProtocolVersion('1.1');
negotiateMedia($supported[, $strictMatch=false])?
參數:
  • $supported (array) – 系統所支持的媒體類型構成的數組
  • $strictMatch (bool) – 是否需要嚴格匹配
返回:

對于所請求的媒體格式，返回程序支持的媒體類型
返回類型:

string

用于處理 Accept 請求頭并將其與應用程序所支持的媒體類型進行對比來給出最合適的類型。本方法會返回一個合適的媒體類型，第一個參數是應用程序所支持的類型，用于和客戶端所請求的類型進行比對:

$supported = [
        'image/png',
        'image/jpg',
        'image/gif'
];
$imageType = $message->negotiateMedia($supported);

$supported 數組里成員的順序應該以程序優先返回的順序進行定義，其中第一個成員應該是應用程序所期待的返回類型，其余降序排列。如果和請求的類型匹配不上，就默認返回數組里的第一個成員。

根據 RFC ，協商匹配可以選擇以返回一個默認值（就如該方法所做的那樣），或者是返回一個空字符串。如果你希望進行嚴格匹配并返回一個空字符串的話，請為第二個參數傳值 true

// 如果匹配不到就返回一個空字符串
$imageType = $message->negotiateMedia($supported, true);

匹配流程實際上同時考慮到了請求類型的優先級和在RFC中的明確性。這就意味著請求頭的值越明確，所對應的優先級就越高，（除非通過 q 的值來修改） 更多細節請閱讀 appropriate section of the RFC

negotiateCharset($supported)?
參數:
  • $supported (array) – 系統所支持的字符集構成的數組
返回:

對于所請求的字符集類型，所能匹配到的最優先的字符集
返回類型:

string

和 negotiateMedia() 方法一樣，只是用于匹配 Accept-Charset 請求頭:

$supported = [
        'utf-8',
        'iso-8895-9'
];
$charset = $message->negotiateCharset($supported);

匹配不到的情況下，返回默認的 utf-8 字符集。

negotiateEncoding($supported)?
參數:
  • $supported (array) – 系統所支持的字符編碼構成的數組
返回:

對于所請求的字符編碼，所能匹配到的最優先的字符編碼
返回類型:

string

與上述兩個方法類似，用于匹配 Accept-Encoding 請求頭；無法匹配時返回 $supported 數組的第一個元素:

$supported = [
        'gzip',
        'compress'
];
$encoding = $message->negotiateEncoding($supported);
negotiateLanguage($supported)?
參數:
  • $supported (array) – 系統所支持的語言構成的數組
返回:

對于所請求的語言，所能匹配到的最優先的語言
返回類型:

string

與上述三個個方法類似，用于匹配 Accept-Language 請求頭；無法匹配時返回 $supported 數組的第一個元素:

$supported = [
        'en',
        'fr',
        'x-pig-latin'
];
$language = $message->negotiateLanguage($supported);

關于語言標記的更多信息，請參閱 RFC 1766 。