Download the PHP package ashleydawson/doctrine-gaufrette-storable-bundle without Composer

Doctrine Gaufrette Storable Bundle

Requirements

Doctrine Support

• Support for Doctrine ORM - Complete
• Support for Doctrine ODM - Incomplete

Introduction

I built this bundle to extend the excellent filesystem abstraction layer, Knp Lab's Gaufrette. In fact, this library extends the KnpGaufretteBundle.

This bundle implements an "uploaded file" handler on Doctrine entities, allowing Gaufrette to store the file as a part of the Doctrine entity lifecycle.

The first class citizen on the bundle is a trait that is applied to any Doctrine entity to give the Gaufrette handler the ability to persist file details along with the entity.

Installation

You can install the Doctrine Gaufrette Storable Bundle via Composer. To do that, simply require the package in your composer.json file like so:

Run composer update to install the package. Then you'll need to register the bundle in your app/AppKernel.php:

Configuration

Next, you'll need to configure at least one filesystem to store your files in. I'll lay out an example below, however, a better example of this can be found in the Gaufrette Bundle documentation.

Usage

In order to use this bundle, you must apply the given trait to the entities you'd like to have carry an uploaded file.

The trait will add four fields to the entity:

• file_name : string
  • The original name of the file as uploaded by the client
  • E.g. foobar.gif
• file_storage_path : string
  • The storage path of the file. Defaults to the file name (above)
  • E.g. /path/to/foobar.gif
• file_mime_type : string
  • The resolved mime type of the file uploaded by the client
  • E.g. image/gif
• file_size : integer
  • The file size in bytes
  • E.g. 2324

You'll need to update your schema before using this entity.

The getFilesystemMapId() abstract method defines the Gaufrette filesystem id where you'd like the file associated with this entity to be stored (defined in the knp_gaufrette config).

Form Type

An example of using the entity with a form type

Note: the field named "uploaded_file" maps to a parameter within the AshleyDawson\DoctrineGaufretteStorableBundle\Model\UploadedFileTrait. If you'd like to change this, simply add an accessor to your entity to act as a proxy:

Then you can add the new name to the form type, like so:

Events

The storage handler, which is a part of the Doctrine entity lifecycle, fires several events on the margins of the file storage activity. These are:

• ad_doctrine_gaufrette_storable.pre_write
  • Dispatched before file is written to filesystem
• ad_doctrine_gaufrette_storable.post_write
  • Dispatched after file is written to filesystem
• ad_doctrine_gaufrette_storable.pre_delete
  • Dispatched before file is deleted from filesystem
• ad_doctrine_gaufrette_storable.post_delete
  • Dispatched after file is deleted from filesystem

These events can be found within the namespace AshleyDawson\DoctrineGaufretteStorableBundle\Event\StorageEvents.

A good use case for these events is if you want to change any details of the form before it is written, for example (inside a Symfony controller):

Of course, this is a crude example - but it does show how a file (or meta information about a file) may be changed. In the example above, I'm building a hash directory structure for the storage path. Something like this:

Note: please don't use the example above as a production solution as there is a chance of filename collision.

It may also be a good idea to mount a subscriber instead of doing a closure-based implementation as I've done above. You should always aim to deliver a system that promotes the single responsibility principal!