Headers
云策文档标注
概述
Headers 类是一个大小写不敏感的字典，专为处理 HTTP 头部设计，继承自 CaseInsensitiveDictionary。它提供了获取、设置和扁平化头部值的方法，遵循 RFC2616 规范。
关键要点
- Headers 类继承自 CaseInsensitiveDictionary，确保头部名称大小写不敏感。
- 提供了 offsetGet、offsetSet、getValues、flatten 和 getIterator 等核心方法，用于操作头部数据。
- offsetGet 方法返回字符串值，将多个值用逗号连接；getValues 方法返回数组值。
- flatten 方法将数组值转换为逗号分隔的字符串，符合 HTTP 头部折叠规则。
- getIterator 方法返回迭代器，在迭代时自动扁平化多值头部。
代码示例
public function offsetGet($offset) {
if (is_string($offset)) {
$offset = strtolower($offset);
}
if (!isset($this->data[$offset])) {
return null;
}
return $this->flatten($this->data[$offset]);
}注意事项
- offsetGet 方法返回字符串，适用于大多数头部，但应避免在值中可能包含未引号逗号的情况（如 Set-Cookie 头部）。
- offsetSet 方法不允许将字典用作列表，设置时需提供有效的偏移量。
- getValues 方法要求偏移量为字符串或整数类型，否则会抛出 InvalidArgument 异常。
- flatten 方法仅接受字符串或数组作为输入，其他类型会抛出异常。
原文内容
Case-insensitive dictionary, suitable for HTTP headers
Methods
| Name | Description |
|---|---|
| Headers::flatten | Flattens a value into a string |
| Headers::getIterator | Get an iterator for the data |
| Headers::getValues | Get all values for a given header |
| Headers::offsetGet | Get the given header |
| Headers::offsetSet | Set the given item |
Source
class Headers extends CaseInsensitiveDictionary {
/**
* Get the given header
*
* Unlike <a href="https://developer.wordpress.org/reference/classes/WpOrgRequestsResponseHeaders/getValues/">WpOrgRequestsResponseHeaders::getValues()</a>, this returns a string. If there are
* multiple values, it concatenates them with a comma as per RFC2616.
*
* Avoid using this where commas may be used unquoted in values, such as
* Set-Cookie headers.
*
* @param string $offset Name of the header to retrieve.
* @return string|null Header value
*/
public function offsetGet($offset) {
if (is_string($offset)) {
$offset = strtolower($offset);
}
if (!isset($this->data[$offset])) {
return null;
}
return $this->flatten($this->data[$offset]);
}
/**
* Set the given item
*
* @param string $offset Item name
* @param string $value Item value
*
* @throws WpOrgRequestsException On attempting to use dictionary as list (`invalidset`)
*/
public function offsetSet($offset, $value) {
if ($offset === null) {
throw new Exception('Object is a dictionary, not a list', 'invalidset');
}
if (is_string($offset)) {
$offset = strtolower($offset);
}
if (!isset($this->data[$offset])) {
$this->data[$offset] = [];
}
$this->data[$offset][] = $value;
}
/**
* Get all values for a given header
*
* @param string $offset Name of the header to retrieve.
* @return array|null Header values
*
* @throws WpOrgRequestsExceptionInvalidArgument When the passed argument is not valid as an array key.
*/
public function getValues($offset) {
if (!is_string($offset) && !is_int($offset)) {
throw InvalidArgument::create(1, '$offset', 'string|int', gettype($offset));
}
if (is_string($offset)) {
$offset = strtolower($offset);
}
if (!isset($this->data[$offset])) {
return null;
}
return $this->data[$offset];
}
/**
* Flattens a value into a string
*
* Converts an array into a string by imploding values with a comma, as per
* RFC2616's rules for folding headers.
*
* @param string|array $value Value to flatten
* @return string Flattened value
*
* @throws WpOrgRequestsExceptionInvalidArgument When the passed argument is not a string or an array.
*/
public function flatten($value) {
if (is_string($value)) {
return $value;
}
if (is_array($value)) {
return implode(',', $value);
}
throw InvalidArgument::create(1, '$value', 'string|array', gettype($value));
}
/**
* Get an iterator for the data
*
* Converts the internally stored values to a comma-separated string if there is more
* than one value for a key.
*
* @return ArrayIterator
*/
public function getIterator() {
return new FilteredIterator($this->data, [$this, 'flatten']);
}
}