The goal of this bundle is to provide tools to handle file uploads.
Currently it includes one form type, image_upload. This presents a preview of the current image and a button which opens a modal dialog (twitter bootstrap required) in which a new image can be uploaded and then cropped.
Sample configuration (config.yml)
bvw_upload:
upload:
base_path: ../web/upload/temp # where to store images
base_url: /upload/temp # public url for image store
formats:
post:
default:
width: 600
height: 400
mode: limit
small:
width: 100
height: 100
mode: fit
thumbnail:
width: 200
height: 200
mode: center
A format specifies how an uploaded image is processed. A format must have at least one sub-format called default. This specifies what happens to the uploaded file. If you specifiy additional sub-formats, the service will automatically create copies of the uploaded file using their specifications. They can be referred to using the subformats name (in the example they are called thumbnail and small.
The mode setting specifies how to process the image. There are four modes:
limit: Only resizes the image if it exceeds the specified width or height. Keeps aspect ratio.
scale: Fit image within dimensions but keep aspect ratio. Scales the image up if it's smaller than the target dimensions. Note that the resulting height or width can be smaller than the target dimensions if the aspect ratio of the given image doesn't match the target aspect ratio.
fit: Same as scale, except that the difference in height or width between the resized image and the target
dimensions will be filled with a color that can be specified with an extra background_color setting (default white)
center: Resize the image so that it's either exactly as wide or exactly as high as the target format and then cut off the parts exceeding the dimensions (equally at the top and bottom or left and right).
For more formats see inside the ImageGenerator class.
$formBuilder
->add('image', 'image_upload', array('format' => 'avatar')))
;
Required options:
format: an identifier refering to a format-spec in your config, which tells the service how to process the uploaded image.
Optional:
crop_area_widthandcrop_area_heightspecify the dimensions of the JCrop cropping area inside the modal that is shown after uploading.use_aspect_ratio: set to true if JCrop should use a fixed aspect ratio (the aspect ratio of your target format) for croppingpreview: specify a sub-format to use for displaying a thumbnail in the form widget. If left out, default is used
The value that results from this form type is a unique name for the stored image. You can store it as a string. You can get the public URL from the storage service like this:
$url = $this->container->get('bvw_upload.storage')->getPublicUrl($name);
TODO: Create a twig extension to make this easy to use within templates
The bundle hands the generated images to a storage service, which abstracts the images into 'storage objects'. These objects are referenced by name. The storage implementation automatically generates a unique name for each stored object.
Two storage service implementations are included in the bundle, one for a local filesystem (enabled by default, easiest touse) and an Amazon S3 implementation for storing your images in the cloud.
The default configuration stores your images in your project's web/upload directory. To change this,
put the following in your configuration:
bvw_upload:
localstorage:
base_path: ../web/media # relative to your app.php or absolute!
base_url: /media # public url of the above path (can be a full url as well)
To use S3 storage instead, include this:
bvw_upload:
storage: s3
s3storage:
key: # your s3 api key
secret: # your s3 private key
bucket: # your s3 bucket
region: # your s3 region
- improve documentation
- include a Twig helper to get the public URL of a storage object based on the object name
- handle deletes
- clean up unused images from storage? (how?)