Download the PHP package iiirxs/image-upload-bundle without Composer

Brief description

This bundle provides image upload and optimization functionality out of the box, for embedded image collections.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:

Usage

The bundle provides all needed functionalities for image uploading out of the box as well as extensibility through configuration, service override and class inheritance. At this point it only supports MongoDB database, through Doctrine ODM Bundle.

Basic usage

Step 1: Add image embedded collection

Embed a collection of images inside a document. The target document class must extend IIIRxs\ImageUploadBundle\Document\AbstractImage:

AbstractImage class provides two basic mapped fields: path and rank but one can add any other mapped fields in the extended class.

Step 2: Set an uploader

In order for the images to be uploaded in the filesystem, your application should contain at least one service implementing IIIRxs\ImageUploadBundle\Uploader\ImageUploaderInterface, added to the IIIRxs\ImageUploadBundle\Uploader\ChainUploader.

The simplest way to achieve this is by simply configuring the full path to the directory where images should be uploaded to. You can do this, just by configuring default_image_upload_dir value inside bundle's configuration file:

The bundle also provides the capability of creating an optimized version and a thumbnail for each uploaded image instead of simply moving the uploaded file to the target directory. To use this feature just provide an array with optimized and thumbnails keys instead of a single path:

Now a default uploader is registered inside the chain uploader and will be used to upload images for any image collection inside your application that is configured to be processed by the bundle.

Step 3: Post image files

As all-needed functionality is already implemented inside IIIRxs\ImageUploadBundle\Controller\ImageController, all you need to do is the make the appropriate requests to uploadImages controller action.

Image collection creation

All-together upload

To upload a new collection of images along with their ranks in a single request, you should make a post request to iiirxs_image_upload route in your javascript code with Content-Type header set to multipart/form-data. The payload of the request should be a FormData object.

Example: Add collection of images to pre-existing image container object

One-by-one upload

To upload a new image collection with n images, one-by-one, you should make n+1 post requests to iiirxs_image_upload route; one for each image, plus one for the image ranks.

Example: Add collection of images (multiple requests)

Addition to image collection

Adding a new image to an existing collection is very similar to the image collection creation with multiple requests. Please note that during such requests, you should always add a field with null value to the FormData object, for every existing image in your database if the corresponding rank field is not set in your FormData object, elsewise the image will be removed from the database:

Example: Add new image to existing collection

Example: Add new image to existing collection (without ranks)

Deletion from image collection

In order to delete an image from a collection you can just omit its key from the FormData object sent:

Example: Add new image to existing collection (without ranks)

Step 4 (optional): Post additional image details

In case you have additional fields added inside your Image class (e.g. description) you can post these details to postImageDetails controller action.

However, in order to do that, at first you should create your own form type class that extends IIIRxs\ImageUploadBundle\Form\Type\ImageType class:

Then you have to add the appropriate mapping to the bundle's configuration, so that the correct form type will be used for this specific embedded collection:

Now you can post image details by making a simple post request to the iiirxs_image_upload_details_post route. The payload of the request should be a json object with the structure of the example.

Example: Post additional details to existing image collection

You are done!! Your images will be stored inside the embedded collection in your MongoDB database and the corresponding files will be moved to the appropriate location in your filesystem.

Advanced usage

Form

The bundle provides two basic form types:

• IIIRxs\ImageUploadBundle\Form\Type\ImageCollectionType
• IIIRxs\ImageUploadBundle\Form\Type\ImageType

It also provides an ImageFormService service that creates ImageCollectionType forms based on Doctrine ODM mappings or explicit configuration.

ImageCollectionType provides a collection field (field name should be explicitly provided). Entry type of this collection field is by default ImageType class but you can override it through bundle or by passing form options appropriately.

ImageType only supports objects of that extend AbstractImage class.

If Doctrine ODM mappings inside your project is correctly defined or correct mapping exists inside bundle configuration all you need to do to create a ImageCollectionType form for a specific class is to provide an instance of this class and a valid field name (corresponding to an image collection) to ImageFormService:

To explicitly define mappings for specific classes and their respective form types, you can use bundle's configuration like this:

Uploader

The bundle provides a ChainUploader class, an AbstractUploader class and ImageUploaderInterface. ImageUploaderInterface exposes two methods: supports and upload.

The easiest way to create an ImageUploader class is to extend IIIRxs\ImageUploadBundle\Uploader\AbstractUploader class that provides all needed functionality out of the box.

When extending AbstractUploader class, your ImageUploader service should receive at least two arguments it its constructor.

Constructor arguments

• $imagesDir which corresponds to a full path to the directory where images should be stored. It can be a string or an array, in case both optimized and thumbnail images should be generated. In the latter case the array must contain optimized and thumbnails keys with full paths as string values.
• $maxThumbnailDimension is used when thumbnails need to be created and it defines the maximum dimension in pixels for a thumbnail. By default it is set to 600px.

You can easily set the maximum thumbnail dimension inside bundle configuration:

The bundle registers all services tagged with 'image.uploader' tag inside the ChainUploader class. In order to use the ChainUploader inside a service, all you need to do is to inject it, and call the selectUploader and upload methods:

Events

The bundle provides three events:

• ImageDetailsPostEvent
• ImagesDeleteEvent
• ImagesUploadEvent

and an event subscriber that listens to the ImagesDeleteEvent and ImagesUploadEvent events. The ImageListener uses ChainUploader service to upload files appropriately and also deletes image files when ImagesDeleteEvent is correctly dispatched.

You can set up your own functionality for this event subscriber by overriding iiirxs_image_upload.event_listener.image_listener service in your project's configuration.

Controllers

This bundle ultimately provides controller actions that handle everything regarding image uploading for you.

As mentioned before, if you want to use bundle's controller actions, the only needed thing is to register at least one service that implements ImageUploaderInterface, is tagged with 'image.uploader' tag and supports the uploading cases that you want.

The bundle provides two different actions: uploadImages for file uploading and postImageDetails for updating information related to images like image rank and image description.

Currently uploadImages action only supports file uploading through form submission with multipart/form-data content-type.