CodeIgniter4 HTTP 消息

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

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

什么是內容協(xié)商

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

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

同樣的協(xié)商方式會在以下四種數(shù)據(jù)類型中提現(xiàn):

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

類的參考文檔

CodeIgniter\HTTP\Message

body()

返回當前消息的實體部分，如果實體不存在或者已經(jīng)被發(fā)送過，返回null:

echo $message->body();

setBody([$str])

populateHeaders()

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

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

getHeaders()

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

getHeader([$name[, $filter = null]])

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

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

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

echo $message->getHeader('Accept-Language');
// 輸出如下:
[
        'en',
        'en-US'
]

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

$message->getHeader('Document-URI', FILTER_SANITIZE_URL);

headerLine($name)

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

echo $message->headerLine('Accept-Language');
// 輸出:
en, en-US

setHeader([$name[, $value]])

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

$message->setHeader('Host', 'codeigniter.com');

removeHeader([$name])

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

$message->remove('Host');

appendHeader([$name[, $value]]))

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

$message->appendHeader('Accept-Language', 'en-US; q=0.8');

protocolVersion()

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

setProtocolVersion($version)

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

$message->setProtocolVersion('1.1');

negotiateMedia($supported[, $strictMatch=false])

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

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

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

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

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

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

negotiateCharset($supported)

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

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

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

negotiateEncoding($supported)

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

$supported = [
        'gzip',
        'compress'
];
$encoding = $message->negotiateEncoding($supported);

negotiateLanguage($supported)

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

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

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