README

高级PHP下载包装器

此类提供客户端请求和服务器上的文件之间的PHP包装器。

它智能地处理大多数MIME类型，并正确响应对客户端请求的部分内容，以及检查客户端缓存的文件副本是否仍然有效的请求。

使用此类而不是让服务器仅提供文件只有在文件位于服务器文档根之外时，或者当有条件（如年龄验证或其他相关事项）需要检查文件提供之前时才合理。

该类支持部分内容请求和客户端缓存验证。对于部分内容请求，目前只响应第一个指定的部分内容范围，忽略其他部分。

该类还支持客户端请求，询问其拥有的文件版本是否是最新的。

安装
使用此类
示例用法
可捕获的异常
扩展类
单元测试

安装

您可以通过以下方式将其添加到composer项目中

"require": {
    "awonderphp/filewrapper": "^1.1"
},

只要您的 composer.json 允许 Packagist 存储库，那么在运行命令时应该会拉入这个库

composer install

手动安装

对于手动安装，您需要四个类库，您的自动加载器可以找到它们

FileWrapper.php -- 这是一个类库。
InvalidArgumentException.php -- 一个异常库。
TypeErrorException.php -- 一个异常库。
NullPropertyException.php -- 一个异常库。

所有四个库都使用命名空间 \AWonderPHP\FileWrapper

RPM安装

我已经开始了一个名为 PHP Composer Class Manager 的项目，但它尚未准备好部署，截至今天（2018年3月6日），可能还需要一段时间。

使用此类

类构造函数有一个必需参数和四个可选参数。必需参数是第一个，要提供文件的文件系统路径。使用此类最基本的方法

use \AWonderPHP\FileWrapper\FileWrapper as FileWrapper;
$obj = new FileWrapper('/srv/whatever/foo.mp4`);

构造函数接受的参数

$path -- 必需
要提供文件的文件系统路径。始终是 string。
$request -- 可选
客户端将看到的请求文件的名称。这仅在它不同于文件系统上的文件名称并且文件作为附件供客户端保存到其本地文件系统时才有意义。将其设置为 null 以仅使用 $path 中的文件名，否则将其设置为 string。默认值为 null。
$mime -- 可选
应该提供文件的MIME类型。如果设置为 null，则类将尝试嗅探正确的MIME类型，但最好明确指定MIME类型。使用 string 指定MIME类型。要告诉类检测MIME类型，请将其设置为 null。
$maxage -- 可选
客户端应该缓存文件多长时间。此参数可以是表示秒数的整数，表示你希望缓存何时过期的UNIX时间戳的整数，可以是解析器通过strtotime()命令解析的字符串，指定你希望缓存何时过期，或指定浏览器应该缓存多长时间的\DateInterval对象。默认值为604800秒，即一周。
$attachment -- 可选
是否发送一个头部信息告诉客户端保存文件。布尔值默认为false。

一旦实例化了该类，就有两个公开的函数可用

`$obj->setAllowOrigin($origin)`

在某些情况下，你可能需要设置access-control-allow-origin头部。此函数允许你设置它。请注意，如果类正在提供字体，除非你指定其他情况，否则它将自动将该头部设置为*。

`$obj->sendfile()`

这会导致文件被发送到请求客户端。

示例用法

图像文件

此示例用于服务图像文件

use \AWonderPHP\FileWrapper\FileWrapper as FileWrapper;
$obj = new FileWrapper('/srv/images/image.jpg');
$obj->sendfile();
exit();

假设文件实际上是一个JPEG图像，该类将确定文件MIME类型为image/jpeg，并以这种方式将文件服务给请求客户端。

音频下载

此示例使用所有五个参数来服务一个客户端保存到磁盘的音频文件

use \AWonderPHP\FileWrapper\FileWrapper as FileWrapper;
$obj = new FileWrapper('/srv/media/549805.mka', 'waterfall.mka', 'audio/x-matroska', 0, true);
$obj->sendfile();
exit();

服务器文件系统中的文件名为549804.mka，这不是一个非常有描述性的名称，所以我们使用第二个参数给出一个更描述性的文件名，以便最终用户受益。

MIME类型被显式设置为audio/x-matroska，这有助于客户端了解正在下载的文件类型。

由于是下载，我们将文件缓存时间设置为0秒，尽管实际上可以将其设置为null，因为缓存时间对文件下载不适用。

最后，我们使用true作为最后一个参数，以便服务器发送正确的头部信息来触发客户端将文件保存到磁盘而不是在浏览器窗口中打开它。

可捕获的异常

该类伴随有三个可捕获的异常类。

\AWonderPHP\FileWrapper\InvalidArgumentException

此异常类扩展了\InvalidArgumentException，当参数类型正确但无意义时抛出。

目前它仅在使用负数$maxage参数或使用核心PHP strtotime函数无法解析的字符串设置$maxage时抛出。

\AWonderPHP\FileWrapper\TypeErrorException

此异常类扩展了\TypeError，当作为参数设置的变量类型错误时抛出。

\AWonderPHP\FileWrapper\NullPropertyException

此异常类扩展了\ErrorException，当类属性不应为NULL时为NULL时抛出。

此异常永远不会发生，如果发生，则是由于类中的错误。

扩展类

此类还包含一些在处理基于文本的文件时有用的方法，例如将非UTF8字符集转换为UTF8，JavaScript/CSS文件的压缩，以及纯文本文件的自动换行。虽然这些方法位于此类中，但它们是禁用的，需要扩展此类以启用它们。

class TextWrapper extends \AliceWonderMiscreations\Utilities\FileWrapper
{
    public function __construct(string $path, $request = null, $mime = null, bool $minify = false)
    {
        $this->toUTF8 = true;
        $maxage = 604800;
        if ($minify) {
            $this->minify = true;
        }
        parent::__construct($path, $request, $mime, $maxage, false);
    }
}

扩展后的类将启用转换到UTF8，并可选择自动压缩由它服务的文件。

单元测试

我尚未为此类创建任何单元测试。

我的个人经验是，单元测试揭示了开发者在编写单元测试之前不知道存在的错误。这意味着这个类可能存在一些错误。

话虽如此，我一直在Naughty.Audio（Naughty.Audio）上使用这个类进行JS/CSS压缩、作为文件下载包装器以及处理HTML5媒体内容的部分请求。

对我来说它是有效的。

是的，我确实需要创建实际的单元测试。目前我正在研究如何为一个下载包装器编写单元测试，这并不简单，因为它涉及到解释客户端发送的头部信息。

awonderphp / filewrapper

维护者

详细信息