README

FloppyClient 是 FloppyServer 库的客户端。在您使用此库之前，应安装您的 FloppyServer 实例。关于如何使用 FloppyServer，您可以在文档中找到。

FloppyClient 提供两个简单的集成点

为存储在 FloppyServer 上的文件生成 URL
FloppyServer 上的文件上传客户端

FloppyClient 是 FloppyServer 的纯客户端，如果您想在 Symfony2 应用中使用 Floppy，您应该对 FloppyBundle 感兴趣。

文档

特性

FloppyClient 和 FloppyServer 组合提供简单的文件存储服务器。感谢 Floppy，您不必担心编写上传和存储文件、生成（在运行时或预先存储）各种照片缩略图、优化文件等的代码。您开发的应用程序只需知道文件上传的位置、从哪里可以检索请求的文件变体，以及最终知道应提供的安全规则和凭证。

StorageServer 的职责是以高效的方式（默认情况下在文件系统上，但也可以是云等）存储文件，并透明地准备请求的文件变体——例如给定尺寸的缩略图。

使用示例

    use Floppy\Client\Factory;
    use Floppy\Common\FileSource;
    use Floppy\Common\FileId;

    //configure FloppyClient library
    $factory = new Factory(array(
        'host' => 'your-floppy-server-host',
        'secretKey' => 'your-floppy-secret-key-the-same-as-in-server',
    ));

    //create client and url generator
    $client = $factory->createFloppyClient();
    $urlGenerator = $factory->createUrlGenerator();

    //upload file
    $fileId = $client->upload(FileSource::fromFile($someSplFileInstance)); //$fileId is Floppy\Common\FileId instance

    //info about file type, file size, file mime type etc.
    $info = $fileId->info();
    $info->get('size');

    //value that you should store to be able to recreate FileId instance
    $someFileStringId = $fileId->id();
    $recreatedFileId = new FileId($someFileStringId);

    //generate url to image thumbnail
    $url = $urlGenerator->generate(
        //create identifier to concrete thumbnail
        $fileId->with([ 'thumbnail' => [ 'size' => [ 80, 80 ] ] ]) //assume uploaded file is an image
    );

    //generate url to original file
    $url = $urlGenerator->generate($fileId);

配置

FloppyClient 的基本配置选项

host - FloppyServer 主机，必需选项
secretKey - 必须与 FloppyServer 中相同的密钥。它应该足够强大，因为安全性取决于其强度。16-32 长度的散列值应该足够。
protocol - FloppyServer 协议（http 或 https）- 默认值：http
path - FloppyServer 实例的路径，默认值：空字符串

安全凭证生成器

您可以为 Floppy 定义上传或下载文件的安全规则。负责向上传或下载请求添加凭证的类是 Floppy\Client\Security\CredentialsGenerator。您可以将凭证传递给 UrlGenerator::generate 或 FloppyClient::upload 方法。

    $urlGenerator->generate($fileId, 'image', /** credential attrs */ array('expiration' => time() + 60, 'customFiled' => 'value'));
    $client->upload($fileSource, array('file_types' => 'image'));

默认的 CredentialsGenerator 实现是 PolicyGenerator，它与 Floppy\Server\RequestHandler\Security\PolicyRule 从 FloppyServer 库中合作。支持的凭证属性

expiration - 定义请求将在该日期之后过期的时间戳
file_types - 允许上传的文件类型数组（文件处理器的名称，而不是 MIME 类型！）该请求可以上传，它仅与上传请求（FloppyClient::upload 方法）一起使用
access - 公共或私有（默认为公共）- 上传/检索的文件应该是公共/私有存储

您可以通过将您自己的实现传递给 Factory 的 credentialsGenerator 属性来更改 CredentialsGenerator 的实现。如果您想更改凭证生成器，请记住更改 FloppyServer 实例中的 action.download.securityRule 和 action.upload.securityRule。

    use Floppy\Client\Factory;
    
    $factory = new Factory(array(
        'credentialsGenerator' => function($container){
            return new CustomGenerator($container['checksumChecker']);
        }
    ));
    
    //...

文件处理器（文件类型）

默认情况下有两个文件处理器：图像和文件（其他文件）。客户端的文件处理器对于URL生成器很重要 - 生成器应该知道为哪种文件类型生成URL。URL生成器通过扩展名识别文件类型。默认情况下，具有给定扩展名：png、jpg、jpeg或gif的文件是图像类型。具有其他扩展名的文件具有“文件”类型。您可以通过将urlGenerator.image.extensions属性传递给Factory来自定义图像扩展名。您应该记住，客户端的文件处理器应该与服务器端相同配置（您应该在FloppyServer实例中配置fileHandlers.image.extensions、fileHandlers.image.mimeTypes、fileHandlers.file.extensions、fileHandlers.file.mimeTypes属性）。例如FloppyClient配置

    use Floppy\Client\Factory;
    
    $factory = new Factory(array(
        'urlGenerator.image.extensions' => array('jpeg', 'png', 'jpg'),//gif files will not be threaten as images
    ));

详细使用说明

创建Floppy工厂对象示例

    use Floppy\Client\Factory;

    $factory = new Factory(array(
        'host' => 'your-floppy-server-host',
        'secretKey' => 'your-floppy-secret-key-the-same-as-in-server',
        /** other options */
    ));

URL 生成器

您可以使用工厂创建UrlGenerator

    $urlGenerator = $factory->createUrlGenerator();

UrlGenerator有一个方法：UrlGenerator::generate(FileId $fileId, $fileType = null, array $credentialAttributes = array())。第一个参数是要生成URL的FileId。第二个参数是文件类型（它不是MIME类型，而是应为此文件使用的FileHandler的名称）。默认情况下，文件类型将根据文件扩展名猜测，但您可以强制文件类型。第三个参数是凭证属性。有关凭证属性的信息，请参阅安全凭证生成器部分。

作为第一个参数，您可以传递原始文件的FileId或适当的文件变体（例如给定大小的小图）。以下是生成60x60大小缩略图的方式

    use Floppy\Common\FileId;

    $fileId = new FileId('id-of-the-file.png');
    $url = $urlGenerator->generate($fileId->with(array(
        'thumbnail' => array(
            'size' => array(60, 60),
        ),
    ), /** explicitly file type */ 'image');

对于图像，有大量的过滤器可供使用，与LiipImagineBundle库中相同

auto_rotate:
- （无选项）
background:
- 颜色（默认#fff）
- 大小 - 数组(宽度，高度)
裁剪:
- 起始点 - 数组( x, y )
- 大小 - 数组(宽度，高度)
粘贴:
- 起始点 - 数组( x, y )
- image - 图像名称，图像默认存储在FloppyServer实例的storage.dir目录以上
relative_resize 在此过滤器中一次只能传递一个选项！
- heighten: 高度（以像素为单位）
- widen: 宽度（以像素为单位）
- increase: 像素数
- scale: 浮点数
resize:
- 大小 - 数组(宽度，高度)
thumbnail:
- 模式 - 外出或内嵌
- 大小 - 数组(宽度，高度)
- filter - ImageInterface::FILTER_*常量
upscale:
- min - 数组(宽度，高度)
watermark:
- 大小 - 浮点数或百分比 - 水印的相对大小
- 位置 - 顶部/中心（或空字符串）/底部 + 左侧（空字符串）/右侧，例如topleft，center，right等。
- image - 与paste过滤器中的含义相同

支持的file文件类型属性

name - 下载文件的名称，它将被添加到响应Content-Disposition http标头中

    $url = $urlGenerator->generate($fileId->with([ "name" => "Some name" ]));

文件上传

您可以使用工厂创建FloppyClient

    $client = $factory->createFloppyClient();

FloppyClient有一个方法：FloppyClient::upload(FileSource $fileSource, array $credentialAttributes = array())。您可以使用工厂方法FileSource::fromFile(\SplFileInfo $file)或直接通过构造函数创建FileSource实例。

    use Floppy\Common\FileSource;
    use Floppy\Common\Stream\LazyLoadedInputStream;
    use Floppy\Common\FileType;
    
    //by factory method - it is recommended
    $fileSource = FileSource::fromFile(new \SplFileInfo('some/path'));//you can pass instance of `UploadedFile` from Symfony too
    
    //by constructor
    $fileSource = new FileSource(new LazyLoadedInputStream('some/path'), new FileType('image/jpg', 'jpg'));

上传方法的第二个参数是凭证属性 - 有关更多信息，请参阅安全凭证生成器部分。

上传方法返回类型为Floppy\Common\FileId。在失败时抛出Floppy\Client\Exception\IOException。上传方法返回的FileId包含有关上传文件的额外信息

type - 文件类型，默认文件类型：image或file
mime-type
extension
size - 以字节为单位
width和height - （当文件是图像时）

此额外信息可通过FileId::info()方法访问。FileId具有可通过FileId::id()方法访问的id属性 - 您应该将其存储在某个地方（数据库？）以便将来能够生成此文件的URL。

许可证

本项目遵循 MIT 许可协议。

floppy / 客户端

维护者

详细信息