README

扩展 Symfony 的 StreamedResponse，以支持服务 Range: 和其他请求。

使用方法

在 Symfony、Laravel 或任何其他依赖 Symfony HttpFoundation 组件的框架中，您可以从本包返回 StreamedResponse 作为响应，它将自动处理响应包含 Range: 标头的请求中的部分内容。

例如

<?php
class Controller
{
	public function getFile()
	{
		$fileStream = \Nucleardog\Streams\ReadStream::fromPath('/my/file.zip');
		return new \Nucleardog\StreamedResponse\StreamedResponse($fileStream);
	}
}

尽可能，您还应该在返回之前在响应上调用 setEtag 和 setLastModified 方法，以便客户端可以使用 If-Range 标头。

您可能还想要设置 Content-Type 标头。

错误处理

对于此库遇到的问题（即不是底层流库或实现中的问题），将抛出扩展自 \Nucleardog\StreamedResponse\Exceptions\StreamedResponseException 的异常。这些问题通常是“头部格式不正确”或“用户请求的范围不存在于此流”之类的。

基本类添加了四个方法，以简化在大多数情况下处理这些错误

• getStatusCode(): int：在此情况下应用的 HTTP 状态码。
• response(): Response：生成具有正确设置的状态码的 Symfony 响应。这可以直接返回给用户。
• isUserError(): bool：此错误是否由用户引起，通常这意味着“这是用户可以通过更改其请求来修复的事情”。
• isSystemError(): bool：此错误是否由我们的程序或逻辑引起，通常这意味着“这是用户无法修复的事情”。

例如

<?php
class Controller
{
	public function getFile()
	{
		$fileStream = \Nucleardog\Streams\ReadStream::fromPath('/my/file.zip');
		try
		{
			return new \Nucleardog\StreamedResponse\StreamedResponse($fileStream);
		}
		catch (\Nucleardog\StreamedResponse\Exceptions\StreamedResponseException $ex)
		{
			return $ex->response();
		}
	}
}

覆盖

如果您出于任何原因想要覆盖处理响应的一些方式，有一些选项可供您选择。必须在您或您的框架调用 prepare() 之前调用这些选项。

• StreamedResponse->setFormatter(formatter)：显式设置用于输出请求的格式化程序。
• StreamedResponse->setOutputStream(writeable)：设置用于写入响应体的输出流。如果没有设置，则默认为 php://output。

扩展

将流实际发送到浏览器的任务落在“格式化程序”上。接口（src/Contracts/Formatter.php）要求以下内容

• handles(request, response): bool：如果此格式化程序适用于此请求和响应，则返回 true。
• prepare(request, response): void：在我们开始发送之前对响应进行任何必要的修改（例如，设置头部）。
• format(request, response, stream): void：将响应体输出到提供的流。
• always(request, response): void：在每次响应的每个格式化程序上调用，允许它执行诸如广告其功能之类的操作。（例如，添加 Accept-Ranges 头以广告可以使用 Range: 头）

一旦您实现了一个格式化程序，您就可以将其添加到 StreamedResponse 类将考虑的格式化程序列表中。有一些方法可用

• prependFormatter(formatter)，appendFormatter(formatter)：将传递的格式化程序添加到列表的开始（首先尝试）或末尾（最后尝试）。
• clearFormatters()：清除当前格式化程序列表并不要恢复默认列表。在追加或预追加之前调用此操作允许您删除所有默认格式化程序。
• setFormatters(formatters)：覆盖格式化程序列表。不对数组元素进行验证。确保它们都是 Formatter 接口的实现。
• setFallbackFormatter(formatter)：设置当没有匹配的格式化器时使用的格式化器。
• clearFallbackFormatter()：清除后备格式化器，恢复默认设置。

默认情况下，响应使用以下格式化器

• MultipartRangeFormatter
• RangeFormatter
• SimpleFormatter（后备）

测试

PHPUnit 包含在单独的 composer 文件中，必须显式安装

$ cd tools/phpunit/
$ composer install

安装完成后，可以从根包文件夹使用以下命令运行测试

$ composer test

Legal

版权所有 2024 Adam Pippin hello@adampippin.ca

许可协议：Apache License，版本 2.0（“许可协议”）；除非遵守许可协议，否则不得使用本项目。您可以在以下地址获得许可协议副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可协议下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。有关许可协议中规定的具体许可权限和限制，请参阅许可协议。