andywer/larablob

Local blob store for the famous Laravel PHP web framework

Larablob - Laravel blob store

, _(*1)

File uploads made easy! PHP blob store for the famous Laravel web framework., _(*2)

Features

• File system based blob storage
• Blobs grouped by named blob groups
• Supports storing blob metadata (stored as JSON files)
• Compatible with Laravel 4.1, 4.2 & 5.0

Why use it?

• You will frequently need to store binary large objects (blobs) like user-uploaded images
• Larablob stores the data separate from your database
• So your database dumps stay small
• Backups are dead easy: Just copy the blob store directory
• Easy to set up and simple to use
• Frequent security pitfalls have been considered and cared for
• Clean high-level API and uncomplicated access on filesystem layer

How To

<?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();

Installation

Just run the following command in your project directory:, _(*3)

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

Now add the following line to the providers array of your config/app.php file:, _(*4)

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

And optionally:, _(*5)

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

Laravel 4

If you still use Laravel 4.1 or 4.2, install the package like:, _(*6)

composer require andywer/larablob=dev-laravel4

Example

Usage is simple and straight forward. The following sample code shows how to easily store random HTTP POST data and related metadata into a blob store., _(*7)

<?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()

Returns the path to the blob store base directory on the file system. Defaults to {project-dir}/storage/larablob, _(*8)

BlobStore::createBlobGroup(string $name)

Creates a new blob group using the supplied $name and returns the BlobGroup instance. May throw a Larablob\Exceptions\NamingException or a Larablob\Exceptions\AlreadyPresentException., _(*9)

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

Returns a BlobGroup instance which you can use to create, read, update or delete blobs. If the blob group cannot be found a Larablob\Exceptions\NotFoundException is thrown, unless $autoCreate is set to true (in this case a new blob group with the given name will be created and returned)., _(*10)

BlobStore::allBlobGroups()

Returns an array containing all existing BlobGroups., _(*11)

BlobStore::allBlobGroupNames()

Returns an array containing all existing blob group's names., _(*12)

BlobStore::blobGroupExists(string $name)

Returns true if a blob group with this name exists, false if not., _(*13)

Larablob\Storage\BlobGroup

$blobGroup->getName()

Returns the name of the blob group., _(*14)

$blobGroup->getStore()

Returns the Larablob\Storage\BlobStore instance of the blob group's store., _(*15)

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

Creates a new blob in the blob group and returns a Blob instance. You can optionally pass an $id to the method (any non-empty string will do; the filename will be urlencode($id)) or otherwise Larablob will create a random UUID v4 for the blob., _(*16)

Hint: A blob's ID must only be unique in the context of it's blob group., _(*17)

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

Returns a Blob instance. If the blob cannot be found a Larablob\Exceptions\NotFoundException is thrown, unless $autoCreate is set to true (in this case a new blob with the given id will be created and returned)., _(*18)

$blobGroup->allBlobs()

Returns an array containing all Blobs of this blob group., _(*19)

$blobGroup->allBlobIds()

Returns an array containing all blob's identifiers (in this blob group)., _(*20)

$blobGroup->blobExists(string $id)

Returns true if a blob with the given ID exists, false if not., _(*21)

$blobGroup->delete()

Deletes the blob group and all its blobs. Attention: Trying to access the blob group or it's contents after calling delete() may result in an exception being thrown., _(*22)

Larablob\Storage\Blob

$blob->getId()

Returns the blob's identifier as a string., _(*23)

$blob->getFilePath()

Returns the path to the blob file as a string., _(*24)

$blob->getBlobGroup()

Returns the BlobGroup instance of the blob group that contains this blob., _(*25)

$blob->data()

Returns the blob's data as a string., _(*26)

$blob->size()

Returns an integer indicating the blob data's size in bytes., _(*27)

$blob->save(string $data)

Update the blob's data. Overwrites existing data., _(*28)

$blob->importFromFile(string $filePath)

A shortcut to saving the contents of the given file to the blob. Throws a Larablob\Exceptions\FileSystemException if the file cannot be read., _(*29)

$blob->getMeta()

Returns the blob's metadata previously set by setMeta() as a generic object (stdClass)., _(*30)

$blob->setMeta(mixed $metadata)

Saves custom metadata for the blob. The metadata will be encoded to a JSON string and saved to another file., _(*31)

$blob->delete()

Deletes the blob and it's metadata. Attention: Trying to access the blob or it's content after calling delete() may result in an exception being thrown., _(*32)

Configuration

Currently the only thing to configure is the store path. It defaults to a directory larablob in the application's storage directory., _(*33)

License

This software is licensed under the terms of the MIT license. See LICENSE for details., _(*34)