README

文件上传变得简单！著名的 Laravel 网络框架的 PHP blob 存储。

特性

• 基于文件系统的 blob 存储
• 按名称的 blob 组分组
• 支持存储 blob 元数据（存储为 JSON 文件）
• 兼容 Laravel 4.1，4.2 & 5.0

为什么使用它？

• 您将经常需要存储二进制大型对象（blobs），如用户上传的图像
• Larablob 将数据与您的数据库分开存储
• 因此，您的数据库转储保持较小
• 备份非常简单：只需复制 blob 存储目录
• 易于设置和使用简单
• 已考虑并关注常见的安全陷阱
• 干净的 API 高层和简单的文件系统层访问

如何使用

<?php
use Larablob\Facades\BlobStore;

$blobGroup = BlobStore::getBlobGroup('profile-pics', true);     // true indicates to create the group if it's not yet present

$blob = $blobGroup->createBlob();
$blob->importFromFile('php://input');

echo "Saved request body to filesystem without worrying about malicious user-given file names!\n";
echo "And we now have a high-level API for using it, too.";

$blob->save("Hello world!");
echo "Stored new data in blob: ".$blob->data()."\n";

echo "All profile-pic blobs:\n";
foreach ($blobGroup->allBlobs() as $blob) {
    echo "-> ".$blob->getId()." (size: ".$blob->size().")\n";
}

echo "Cleaning up...\n";
$blobGroup->delete();

安装

在项目目录中运行以下命令

composer require andywer/larablob=dev-master      # dev-laravel4 for Laravel 4.1 or 4.2

现在将以下行添加到您的 config/app.php 文件的 providers 数组中

    'providers' => [
        /* ... */
        'Larablob\LarablobServiceProvider'
    ]

可选地

    `aliases` => [
        /* ... */
        'BlobStore' => 'Larablob\Facades\BlobStore'
    ]

Laravel 4

如果您仍然使用 Laravel 4.1 或 4.2，安装包如下

composer require andywer/larablob=dev-laravel4

示例

使用简单直接。以下示例代码展示了如何轻松地将随机的 HTTP POST 数据和相关元数据存储到 blob 存储中。

<?php
namespace app\Http\Controllers;

use Larablob\Facades\BlobStore;
use Request;

class PostController extends Controller {

    /** @var \Larablob\Storage\BlobGroup */
    protected $blobGroup;


    public function __construct()
    {
        // the `true` indicates that a new group shall be created if it does not exist
        $this->blobGroup = BlobStore::getBlobGroup('post-data', true);
    }

    /**
     * GET parameters: ['id', 'mime-type']
     * POST data: Random data
     */
    public function postDataUpload()
    {
        $blob = $this->blobGroup->createBlob(Request::input('id'));
        // if we would not pass a blob ID here, the blob store would generate a random UUID v4 for us

        $blob->importFromFile('php://input');
        $blob->setMeta([ 'type' => Request::input('mime-type') ]);

        return response()->json([ 'storedBytes' => $blob->size() ]);
    }

    /**
     * GET parameters: ['id']
     */
    public function retrieveData()
    {
        $blob = $this->blobGroup->getBlob(Request::input('id'));

        return response()->download($blob->getFilePath());
    }

    /**
     * GET parameters: ['id']
     */
    public function retrieveMetadata()
    {
        $blob = $this->blobGroup->getBlob(Request::input('id'));
        $meta = $blob->getMeta();

        return response()->json([ 'type' => $meta->type, 'size' => $blob->size() ]);
    }

    /**
     * Parameters: None
     */
    public function listAll()
    {
        return response()->json([
            'IDs' => $this->blobGroup->allBlobIds()
        ]);
    }

    /**
     * GET parameters: ['id']
     */
    public function removeData()
    {
        $this->blobGroup->getBlob(Request::input('id'))->delete();
        // getBlob() throws a \Larablob\Exceptions\NotFoundException if a bad ID is passed

        return response()->json([ 'success' => true ]);
    }

}

API

Larablob\Facades\BlobStore

BlobStore::getPath()

返回文件系统上 blob 存储基本目录的路径。默认为 {project-dir}/storage/larablob

BlobStore::createBlobGroup(string $name)

使用提供的 $name 创建新的 blob 组并返回 BlobGroup 实例。可能会抛出 Larablob\Exceptions\NamingException 或 Larablob\Exceptions\AlreadyPresentException。

BlobStore::getBlobGroup(string $name, bool $autoCreate = false)

返回一个 BlobGroup 实例，您可以使用它来创建、读取、更新或删除 blob。如果找不到 blob 组，则会抛出 Larablob\Exceptions\NotFoundException，除非将 $autoCreate 设置为 true（在这种情况下，将创建具有给定名称的新 blob 组并返回）。

BlobStore::allBlobGroups()

返回包含所有现有 BlobGroup 的数组。

BlobStore::allBlobGroupNames()

返回包含所有现有 blob 组名称的数组。

BlobStore::blobGroupExists(string $name)

如果存在具有此名称的 blob 组，则返回 true，如果不存在，则返回 false。

Larablob\Storage\BlobGroup

$blobGroup->getName()

返回 blob 组的名称。

$blobGroup->getStore()

返回 blob 组存储的 Larablob\Storage\BlobStore 实例。

$blobGroup->createBlob(string $id = null)

在 blob 组中创建一个新的 blob 并返回一个 Blob 实例。您可以可选地传递一个 $id 到该方法（任何非空字符串都可以；文件名将是 urlencode($id)）或者否则 Larablob 将为 blob 创建一个随机的 UUID v4。

提示：blob 的 ID 必须在其 blob 组的上下文中是唯一的。

$blobGroup->getBlob(string $id, bool $autoCreate = false)

返回一个 Blob 实例。如果找不到 blob，则会抛出 Larablob\Exceptions\NotFoundException，除非将 $autoCreate 设置为 true（在这种情况下，将创建具有给定 id 的新 blob 并返回）。

$blobGroup->allBlobs()

返回包含此 blob 组所有 Blob 的数组。

$blobGroup->allBlobIds()

返回包含所有 blob 标识符（在此 blob 组中）的数组。

$blobGroup->blobExists(string $id)

如果具有给定ID的blob存在，则返回true，如果不存在，则返回false。

$blobGroup->delete()

删除blob组及其所有blob。注意：在调用delete()之后尝试访问blob组或其内容可能会导致抛出异常。

Larablob\Storage\Blob

$blob->getId()

返回blob的标识符，作为string。

$blob->getFilePath()

返回blob文件的路径，作为string。

$blob->getBlobGroup()

返回包含此blob的blob组的BlobGroup实例。

$blob->data()

返回blob的数据，作为string。

$blob->size()

返回一个integer，指示blob数据的大小（以字节为单位）。

$blob->save(string $data)

更新blob的数据。覆盖现有数据。

$blob->importFromFile(string $filePath)

将给定文件的内容保存到blob的快捷方式。如果文件无法读取，则抛出Larablob\Exceptions\FileSystemException。

$blob->getMeta()

返回之前通过setMeta()设置的blob的元数据，作为通用对象（stdClass）。

$blob->setMeta(mixed $metadata)

保存blob的自定义元数据。元数据将编码为JSON字符串并保存到另一个文件。

$blob->delete()

删除blob及其元数据。注意：在调用delete()之后尝试访问blob或其内容可能会导致抛出异常。

配置

目前要配置的只有存储路径。默认为应用程序存储目录中的larablob目录。

许可证

本软件根据MIT许可证的条款进行许可。有关详细信息，请参阅LICENSE。