类响应
响应包含HTTP响应的响应文本、状态和头信息。
存在一些外部包,例如fig/http-message-util
,它们提供HTTP状态码常量。这些常量可以与任何接受或返回状态码整数的方法一起使用。请注意,这些常量可能包含现在不允许的错误码,这将抛出\InvalidArgumentException
。
属性摘要
-
$_cacheDirectives protected
array<string, mixed>
保存所有将在发送请求时转换为头的缓存指令
-
$_charset protected
string
响应主体编码的字符集
-
$_cookies protected
Cake\Http\Cookie\CookieCollection
要发送给客户端的cookie集合
-
$_file protected
SplFileInfo|null
要作为响应读出的文件的File对象
-
$_fileRange protected
array<int>
文件范围。用于请求文件的范围。
-
$_mimeTypes protected
array<string, mixed>
保存已知mime类型的类型键到mime类型映射。
-
$_reasonPhrase protected
string
原因短语
-
$_status protected
int
要发送给客户端的状态码
-
$_statusCodes protected
array<int, string>
允许的HTTP状态码及其默认描述。
-
$_streamMode protected
string
流模式选项。
-
$_streamTarget protected
resource|string
流目标或资源对象。
-
$headerNames protected
array
规范化的头名称到用于注册头的原始名称的映射。
-
$headers protected
array
所有已注册头的列表,作为键=>值的数组。
方法摘要
-
__construct() public
构造函数
-
__debugInfo() public
返回一个数组,可用于描述此对象的内部状态。
-
__toString() public
字符串转换。获取响应主体作为字符串。不发送头信息。如果主体是可调用对象,则返回一个空字符串。
-
_clearHeader() protected
清除头信息
-
_createStream() protected
创建流对象。
-
_fileRange() protected
将文件范围应用于文件并设置结束偏移量。
-
_getUTCDate() protected
返回一个以$time参数初始化并使用UTC作为时区的DateTime对象
-
_setCacheControl() protected
辅助方法,用于根据在其他方法中设置的选项生成有效的Cache-Control头信息
-
_setContentType() protected
根据配置的contentType和字符集格式化Content-Type头信息,仅当响应类型为text/*时,字符集才会设置在头信息中
-
_setHeader() protected
设置头信息。
-
_setStatus() protected
响应状态的修饰符
-
compress() public
设置正确的输出缓冲处理程序以发送压缩的响应。如果扩展可用,响应将使用zlib压缩。
-
cors() public
获取CorsBuilder实例以定义CORS头信息。
-
getBody() public
获取消息的主体。
-
getCharset() public
返回当前字符集。
-
getCookie() public
从响应中读取单个cookie。
-
getCookieCollection() public
从响应中获取CookieCollection
-
getCookies() public
获取响应中的所有cookie。
-
getFile() public
获取当前文件(如果存在)。
-
getHeader() public
通过给定的不区分大小写的名称检索消息头值。
-
getHeaderLine() public
检索单个头的值的逗号分隔字符串。
-
getHeaders() public
检索所有消息头。
-
getMimeType() public
返回别名的mime类型定义
-
getProtocolVersion() public
检索HTTP协议版本作为字符串。
-
getReasonPhrase() public
获取与状态码关联的响应原因短语。
-
getStatusCode() public
获取响应状态码。
-
getType() public
返回当前内容类型。
-
hasHeader() public
检查通过给定的不区分大小写的名称是否存在头信息。
-
isNotModified() public
根据“If-None-Match”(Etags)和“If-Modified-Since”(最后修改日期)请求头检查响应是否未被修改。
-
mapType() public
将内容类型映射回别名
-
outputCompressed() public
返回生成的输出是否将被PHP压缩
-
resolveType() protected
翻译和验证内容类型。
-
setTypeMap() public
将内容类型定义设置到映射中。
-
validateFile() protected
验证文件路径是否是有效的响应主体。
-
withAddedHeader() public
返回一个具有指定头的实例,该头附加了给定的值。
-
withAddedLink() public
创建一个具有设置的Link头信息的新的响应。
-
withBody() public
返回一个具有指定消息主体的实例。
-
withCache() public
创建一个具有启用客户端缓存的头信息的新的实例。
-
withCharset() public
获取一个具有更新字符集的新的实例。
-
withCookie() public
创建一个具有设置的cookie的新的响应。
-
withCookieCollection() public
获取一个具有提供的cookie集合的新的实例。
-
withDisabledCache() public
创建一个具有指示客户端不要缓存响应的头信息的新的实例
-
withDownload() public
创建一个具有设置的Content-Disposition头信息的新的实例。
-
withEtag() public
创建一个具有设置的Etag头信息的新的实例。
-
withExpiredCookie() public
创建一个具有设置的过期cookie的新的响应。
-
withExpires() public
创建一个具有设置的Expires头信息的新的实例。
-
withFile() public
创建一个基于文件的新的实例。
-
withHeader() public
返回一个具有提供的头信息的实例,替换任何具有相同不区分大小写名称的现有头信息的值。
-
withLength() public
创建一个具有设置的Content-Length头信息的新的响应。
-
withLocation() public
返回具有更新位置头的实例。
-
withMaxAge() public
创建一个设置了 Cache-Control max-age 指令的实例。
-
withModified() public
创建一个设置了 Last-Modified 头部的新的实例。
-
withMustRevalidate() public
创建一个设置了 Cache-Control must-revalidate 指令的实例。
-
withNotModified() public
创建一个新的“未修改”实例。
-
withProtocolVersion() public
返回具有指定 HTTP 协议版本的实例。
-
withSharable() public
创建一个设置了 public/private Cache-Control 指令的新的实例。
-
withSharedMaxAge() public
创建一个设置了 Cache-Control s-maxage 指令的新的实例。
-
withStatus() public
返回具有指定状态码(可选)和原因短语的实例。
-
withStringBody() public
将字符串设置为响应主体的便捷方法。
-
withType() public
获取具有设置的内容类型的更新响应。
-
withVary() public
创建一个设置了 Vary 头部的新的实例。
-
withoutHeader() public
返回不具有指定头的实例。
方法详情
__construct() ¶ public
__construct(array<string, mixed> $options = [])
构造函数
参数
-
array<string, mixed>
$options optional 设置响应的参数列表。可能的值是
抛出
InvalidArgumentException
__debugInfo() ¶ public
__debugInfo(): array<string, mixed>
返回一个数组,可用于描述此对象的内部状态。
返回
array<string, mixed>
_fileRange() ¶ protected
_fileRange(SplFileInfo $file, string $httpRange): void
将文件范围应用于文件并设置结束偏移量。
如果请求了无效范围,响应将使用 416 状态码。
参数
-
SplFileInfo
$file 要设置范围的文件。
-
string
$httpRange 要使用的范围。
返回
void
_getUTCDate() ¶ protected
_getUTCDate(DateTimeInterface|string|int|null $time = null): DateTimeInterface
返回一个以$time参数初始化并使用UTC作为时区的DateTime对象
参数
-
DateTimeInterface|string|int|null
$time optional 有效的日期时间字符串或 \DateTimeInterface 实例。
返回
DateTimeInterface
_setCacheControl() ¶ protected
_setCacheControl(): void
辅助方法,用于根据在其他方法中设置的选项生成有效的Cache-Control头信息
返回
void
_setContentType() ¶ protected
_setContentType(string $type): void
根据配置的contentType和字符集格式化Content-Type头信息,仅当响应类型为text/*时,字符集才会设置在头信息中
参数
-
string
$type 要设置的类型。
返回
void
_setHeader() ¶ protected
_setHeader(string $header, string $value): void
设置头信息。
参数
-
string
$header 头键。
-
string
$value 头值。
返回
void
_setStatus() ¶ protected
_setStatus(int $code, string $reasonPhrase = ''): void
响应状态的修饰符
参数
-
int
$code 要设置的状态码。
-
string
$reasonPhrase optional 响应原因短语。
返回
void
抛出
InvalidArgumentException
对于无效的状态码参数。
cors() ¶ public
cors(Cake\Http\ServerRequest $request): Cake\Http\CorsBuilder
获取CorsBuilder实例以定义CORS头信息。
参数
-
Cake\Http\ServerRequest
$request 请求对象
返回
Cake\Http\CorsBuilder
getCookie() ¶ public
getCookie(string $name): array|null
从响应中读取单个cookie。
此方法提供对挂起cookie的读访问。如果设置了Set-Cookie
头,它将不会读取它。
参数
-
string
$name 您要读取的cookie名称。
返回
array|null
getCookieCollection() ¶ public
getCookieCollection(): Cake\Http\Cookie\CookieCollection
从响应中获取CookieCollection
返回
Cake\Http\Cookie\CookieCollection
getCookies() ¶ public
getCookies(): array<string, array>
获取响应中的所有cookie。
返回cookie名称=>cookie数据的关联数组。
返回
array<string, array>
getHeader() ¶ public
getHeader(string $header): string[]
通过给定的不区分大小写的名称检索消息头值。
此方法返回给定不区分大小写头名称的所有头值的数组。
如果消息中没有出现头,此方法必须返回空数组。
参数
-
string
$header 不区分大小写的头字段名称。
返回
string[]
getHeaderLine() ¶ public
getHeaderLine(string $name): string
检索单个头的值的逗号分隔字符串。
此方法返回给定不区分大小写头名称的所有头值,这些值作为使用逗号连接在一起的字符串。
注意:并非所有头值都可以使用逗号连接来适当地表示。对于此类头,请改用 getHeader() 并提供您自己的分隔符以连接。
如果消息中没有出现头,此方法必须返回空字符串。
参数
-
string
$name 不区分大小写的头字段名称。
返回
string
getHeaders() ¶ public
getHeaders(): array
检索所有消息头。
键表示头名称,因为它将通过网络发送,每个值是与头关联的字符串数组。
// 将头表示为字符串 foreach ($message->getHeaders() as $name => $values) { echo $name . ": " . implode(", ", $values); }
// 迭代地发出头: foreach ($message->getHeaders() as $name => $values) { foreach ($values as $value) { header(sprintf('%s: %s', $name, $value), false); } }
返回
array
getMimeType() ¶ public
getMimeType(string $alias): array|string|false
返回别名的mime类型定义
例如getMimeType('pdf'); // 返回 'application/pdf'
参数
-
string
$alias 要映射的内容类型别名
返回
array|string|false
getProtocolVersion() ¶ public
getProtocolVersion(): string
检索HTTP协议版本作为字符串。
字符串必须仅包含 HTTP 版本号(例如,“1.1”,“1.0”)。
返回
string
getReasonPhrase() ¶ public
getReasonPhrase(): string
获取与状态码关联的响应原因短语。
因为原因短语不是响应状态行中的必需元素,所以原因短语值可以为 null。实现可以选择为响应的状态码返回默认的 RFC 7231 建议的原因短语(或 IANA HTTP 状态码注册表中列出的那些)。
返回
string
链接
https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
hasHeader() ¶ public
hasHeader(string $header): bool
检查通过给定的不区分大小写的名称是否存在头信息。
参数
-
string
$header 不区分大小写的头名称。
返回
bool
isNotModified() ¶ public
isNotModified(Cake\Http\ServerRequest $request): bool
根据“If-None-Match”(Etags)和“If-Modified-Since”(最后修改日期)请求头检查响应是否未被修改。
为了与该方法交互,您必须将响应标记为未修改。您需要在调用此方法之前设置至少一个Last-Modified
或Etag
响应头。否则,将无法进行比较。
参数
-
Cake\Http\ServerRequest
$request 请求对象
返回
bool
mapType() ¶ public
mapType(array|string $ctype): array|string|null
将内容类型映射回别名
例如 mapType('application/pdf'); // 返回 'pdf'
参数
-
array|string
$ctype 要映射的字符串内容类型,或类型数组。
返回
array|string|null
resolveType() ¶ protected
resolveType(string $contentType): string
翻译和验证内容类型。
参数
-
string
$contentType 内容类型或类型别名。
返回
string
抛出
InvalidArgumentException
当使用无效的内容类型或别名时。
setTypeMap() ¶ public
setTypeMap(string $type, list<string>|string $mimeType): void
将内容类型定义设置到映射中。
例如:setTypeMap('xhtml', ['application/xhtml+xml', 'application/xhtml'])
这对于 RequestHandlerComponent 和类型识别是必需的。
参数
-
string
$type 内容类型。
-
list<string>|string
$mimeType MIME 类型的定义。
返回
void
validateFile() ¶ protected
validateFile(string $path): SplFileInfo
验证文件路径是否是有效的响应主体。
参数
-
string
$path 文件路径。
返回
SplFileInfo
抛出
Cake\Http\Exception\NotFoundException
withAddedHeader() ¶ public
withAddedHeader(string $name, string|string[] $value): static
返回一个具有指定头的实例,该头附加了给定的值。
将保留指定头的现有值。新值将追加到现有列表中。如果头之前不存在,则会添加它。
此方法必须以保留消息不可变性的方式实现,并且必须返回具有新头和/或值的实例。
参数
-
string
$name 要添加的区分大小写的头字段名称。
-
string|string[]
$value 头值。
返回
static
抛出
Exception\InvalidArgumentException
对于无效的头名称或值。
withAddedLink() ¶ public
withAddedLink(string $url, array<string, mixed> $options = []): static
创建一个具有设置的Link头信息的新的响应。
示例
$response = $response->withAddedLink('http://example.com?page=1', ['rel' => 'prev'])
->withAddedLink('http://example.com?page=3', ['rel' => 'next']);
将生成
Link: <http://example.com?page=1>; rel="prev"
Link: <http://example.com?page=3>; rel="next"
参数
-
string
$url LinkHeader URL。
-
array<string, mixed>
$options optional LinkHeader 参数。
返回
static
withBody() ¶ public
withBody(StreamInterface $body): static
返回一个具有指定消息主体的实例。
主体必须是 StreamInterface 对象。
此方法必须以保留消息不可变性的方式实现,并且必须返回具有新主体流的新实例。
参数
-
StreamInterface
$body 主体。
返回
static
抛出
Exception\InvalidArgumentException
当主体无效时。
withCache() ¶ public
withCache(string|int $since, string|int $time = '+1 day'): static
创建一个具有启用客户端缓存的头信息的新的实例。
参数
-
string|int
$since 响应文本未修改以来的有效时间
-
string|int
$time optional 缓存过期的有效时间
返回
static
withCharset() ¶ public
withCharset(string $charset): static
获取一个具有更新字符集的新的实例。
参数
-
string
$charset 字符集字符串。
返回
static
withCookie() ¶ public
withCookie(Cake\Http\Cookie\CookieInterface $cookie): static
创建一个具有设置的cookie的新的响应。
示例
// add a cookie object
$response = $response->withCookie(new Cookie('remember_me', 1));
参数
-
Cake\Http\Cookie\CookieInterface
$cookie cookie 对象
返回
static
withCookieCollection() ¶ public
withCookieCollection(Cake\Http\Cookie\CookieCollection $cookieCollection): static
获取一个具有提供的cookie集合的新的实例。
参数
-
Cake\Http\Cookie\CookieCollection
$cookieCollection 要设置的 cookie 集合。
返回
static
withDownload() ¶ public
withDownload(string $filename): static
创建一个具有设置的Content-Disposition头信息的新的实例。
参数
-
string
$filename 浏览器将响应下载的文件的名称
返回
static
withEtag() ¶ public
withEtag(string $hash, bool $weak = false): static
创建一个具有设置的Etag头信息的新的实例。
ETag 是 HTTP 客户端可以缓存响应的强有力指示。生成 ETag 的一种错误方法是创建响应输出的哈希值,而是生成标识请求的唯一组件的唯一哈希值,例如修改时间、资源 ID 以及您认为使响应唯一的任何其他内容。
第二个参数用于通知客户端内容已更改,但从语义上讲,它等效于现有缓存值。考虑一个带点击计数器的页面,两个不同的页面视图是等效的,但它们在字节数上有所不同。这允许客户端决定是否应该使用缓存数据。
参数
-
string
$hash 标识此响应的唯一哈希值
-
bool
$weak optional 响应在语义上是否与具有相同哈希值的其他人相同。默认为 false
返回
static
withExpiredCookie() ¶ public
withExpiredCookie(Cake\Http\Cookie\CookieInterface $cookie): static
创建一个具有设置的过期cookie的新的响应。
示例
// add a cookie object
$response = $response->withExpiredCookie(new Cookie('remember_me'));
参数
-
Cake\Http\Cookie\CookieInterface
$cookie cookie 对象
返回
static
withExpires() ¶ public
withExpires(DateTimeInterface|string|int|null $time): static
创建一个具有设置的Expires头信息的新的实例。
示例
// Will Expire the response cache now
$response->withExpires('now')
// Will set the expiration in next 24 hours
$response->withExpires(new DateTime('+1 day'))
参数
-
DateTimeInterface|string|int|null
$time 有效的日期时间字符串或 \DateTime 实例。
返回
static
withFile() ¶ public
withFile(string $path, array<string, mixed> $options = []): static
创建一个基于文件的新的实例。
此方法将增加主体和许多相关头。
如果设置了$_SERVER['HTTP_RANGE']
,则将返回文件的一部分,而不是整个文件。
选项键
- name:备用下载名称
- download:如果为
true
,则设置下载头并强制将文件下载而不是内联显示。
参数
-
string
$path 文件的绝对路径。
-
array<string, mixed>
$options optional 选项参见上文。
返回
static
抛出
Cake\Http\Exception\NotFoundException
withHeader() ¶ public
withHeader(string $name, string|string[] $value): static
返回一个具有提供的头信息的实例,替换任何具有相同不区分大小写名称的现有头信息的值。
虽然头名称不区分大小写,但此函数将保留头的拼写方式,并从 getHeaders() 中返回。
此方法必须以保留消息不可变性的方式实现,并且必须返回具有新和/或更新的头和值的实例。
参数
-
string
$name 不区分大小写的头字段名称。
-
string|string[]
$value 头值。
返回
static
抛出
Exception\InvalidArgumentException
对于无效的头名称或值。
withLength() ¶ public
withLength(string|int $bytes): static
创建一个具有设置的Content-Length头信息的新的响应。
参数
-
string|int
$bytes 字节数
返回
static
withLocation() ¶ public
withLocation(string $url): static
返回具有更新位置头的实例。
如果当前状态码为 200,它将被替换为 302。
参数
-
string
$url 要重定向到的位置。
返回
static
withMaxAge() ¶ public
withMaxAge(int $seconds): static
创建一个设置了 Cache-Control max-age 指令的实例。
max-age 是响应不再被认为是从本地(客户端)缓存中获取的良好候选者的秒数。
参数
-
int
$seconds 缓存响应可以被认为有效的秒数
返回
static
withModified() ¶ public
withModified(DateTimeInterface|string|int $time): static
创建一个设置了 Last-Modified 头部的新的实例。
示例
// Will Expire the response cache now
$response->withModified('now')
// Will set the expiration in next 24 hours
$response->withModified(new DateTime('+1 day'))
参数
-
DateTimeInterface|string|int
$time 有效的日期时间字符串或 \DateTime 实例。
返回
static
withMustRevalidate() ¶ public
withMustRevalidate(bool $enable): static
创建一个设置了 Cache-Control must-revalidate 指令的实例。
设置 Cache-Control must-revalidate 指令。must-revalidate 指示在任何情况下,缓存都不得在没有先与源重新验证的情况下提供陈旧的响应。
参数
-
bool
$enable 如果布尔值设置或取消设置指令。
返回
static
withNotModified() ¶ public
withNotModified(): static
创建一个新的“未修改”实例。
这将删除任何主体内容,将状态码设置为“304”并删除描述响应主体的头。
返回
static
withProtocolVersion() ¶ public
withProtocolVersion(string $version): static
返回具有指定 HTTP 协议版本的实例。
版本字符串必须仅包含 HTTP 版本号(例如,“1.1”,“1.0”)。
此方法必须以保留消息不可变性的方式实现,并且必须返回具有新协议版本的实例。
参数
-
string
$version HTTP 协议版本
返回
static
withSharable() ¶ public
withSharable(bool $public, int|null $time = null): static
创建一个设置了 public/private Cache-Control 指令的新的实例。
参数
-
bool
$public 如果设置为 true,则 Cache-Control 头将设置为 public;如果设置为 false,则响应将设置为 private。
-
int|null
$time optional 响应不再被认为是新鲜的秒数。
返回
static
withSharedMaxAge() ¶ public
withSharedMaxAge(int $seconds): static
创建一个设置了 Cache-Control s-maxage 指令的新的实例。
max-age 是响应不再被认为是从共享缓存(例如在代理服务器中)获取的良好候选者的秒数。
参数
-
int
$seconds 共享 max-age 的秒数
返回
static
withStatus() ¶ public
withStatus(int $code, string $reasonPhrase = ''): static
返回具有指定状态码(可选)和原因短语的实例。
如果没有指定原因短语,实现可以自由选择默认使用 RFC 7231 或 IANA 为响应的状态码推荐的原因短语。
此方法必须以保留消息不可变性的方式实现,并且必须返回具有更新状态和原因短语的实例。
如果状态码是 304 或 204,现有的 Content-Type 头部将被清除,因为这些响应码没有主体。
有一些外部包,例如 fig/http-message-util
,提供了 HTTP 状态码常量。这些常量可以与任何接受或返回状态码整数的方法一起使用。但是,请记住,这些常量可能包含现在不允许的 状态码,这将抛出 \InvalidArgumentException
异常。
参数
-
int
$code 要设置的 3 位整数状态码。
-
string
$reasonPhrase optional 与提供的状态码一起使用的理由短语;如果没有提供,实现 可以使用 HTTP 规范中建议的默认值。
返回
static
抛出
InvalidArgumentException
对于无效的状态码参数。
链接
https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
withStringBody() ¶ public
withStringBody(string|null $string): static
将字符串设置为响应主体的便捷方法。
参数
-
string|null
$string 要发送的字符串。
返回
static
withType() ¶ public
withType(string $contentType): static
获取具有设置的内容类型的更新响应。
如果您尝试在 304 或 204 状态码响应上设置类型,则内容类型将不会生效,因为这些状态码没有内容类型。
参数
-
string
$contentType 文件扩展名(将映射到 mime-type)或具体的 mime-type。
返回
static
withVary() ¶ public
withVary(list<string>|string $cacheVariances): static
创建一个设置了 Vary 头部的新的实例。
如果传递了一个数组,则值将被拼接成一个用逗号分隔的字符串。如果没有传递参数,则返回包含当前 Vary 头部值的数组。
参数
-
list<string>|string
$cacheVariances 单个 Vary 字符串或包含变化列表的数组。
返回
static
withoutHeader() ¶ public
withoutHeader(string $name): static
返回不具有指定头的实例。
头部解析 必须 不区分大小写进行。
此方法 必须 以保留消息不可变性的方式实现,并且 必须 返回一个删除了指定头部的实例。
参数
-
string
$name 要删除的不区分大小写的头部字段名称。
返回
static