Download the PHP package ashleydawson/doctrine-flysystem-bundle without Composer

Doctrine Flysystem Bundle

Add a flysystem storage behaviour to Doctrine entities in Symfony 2

Requirements

Doctrine Support

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

Introduction

I built this bundle to extend Flysystem filesystem abstraction. In fact, this library extends the FlysystemBundle for Symfony 2.

This bundle implements an "uploaded file" handler on Doctrine entities, allowing Flysystem 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 Flysystem storage handler the ability to persist file details along with the entity.

Installation

You can install the Doctrine Flysystem 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. The first of these examples uses the MultiBundle library to register the bundle and it's dependencies. For more information see the MultiBundle docs.

Or you could do this the classic way:

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 FlysystemBundle documentation.

Note: The line mount: my_filesystem_mount_name is important as this bundle references filesystems using their mount prefix as defined here

Usage

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

The getFilesystemMountPrefix() method defines the Flysystem mount prefix where you'd like the file associated with this entity to be stored as defined in app/config/config.yml.

Note: If an array of mount prefixes is returned from getFilesystemMountPrefix() then a copy of the file will be stored in each filesystem

The trait will add four properties to the entity:

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

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

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\DoctrineFlysystemBundle\ORM\StorableTrait. 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:

• ashleydawson.doctrine_flysystem_bundle.pre_store
  • Dispatched before file is written to filesystem
• ashleydawson.doctrine_flysystem_bundle.post_store
  • Dispatched after file is written to filesystem
• ashleydawson.doctrine_flysystem_bundle.pre_delete
  • Dispatched before file is deleted from filesystem
• ashleydawson.doctrine_flysystem_bundle.post_delete
  • Dispatched after file is deleted from filesystem

These events can be found within the namespace AshleyDawson\DoctrineFlysystemBundle\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!

Optional Configuration

Optional configuration parameters are defined in the following way:

Setting delete_old_file_on_update to false will mean that when an entity is updated with a new file, the old file associated with the entity will be deleted.

Override Field Mapping

The StorableTrait, when used by entities, maps several fields for storing file metadata. If you need to change these mappings you can do so by implementing AshleyDawson\DoctrineFlysystemBundle\ORM\Mapping\StorableFieldMapperInterface and overriding the one that ships with this bundle. This will allow you to define your own mapping strategy for each field. For example:

Then simply configure the service container to use your mapper: