Google Ad

FileUploadPlugin v5.0 released!

Date: Fri, Apr 16th 2010, 22:52 Author: nick Views: 33491 Comments share

CakePHP File Upload Plugin

Get it:
  • Download Now
  • git clone git:// file_upload
I'm excited to announce the newest v5.0 release of the popular File Upload Plugin. There have been a lot of new features since the last major release and I'll discuss each one in depth.

New Features

At a glance:

- Validation, and file upload errors now display back to the view
- new 'required' key setting
- new 'maxFileSize' key setting
- new 'unique' key setting
- new 'fileNameFunction' key setting.

Validation errors

Any errors that occur during a file upload will now be presented back to user just like any other standard model validation error. If more than one error occurs, each subsequent error will be added to the model's validation errors. This means no more guess work for the developer or user over what went wrong during the upload (ie file was too large, file type not allowed, etc...).

Required setting

This is a behavior specific new feature. By setting the key 'required' to true you will require an upload to be made if the Model key is present in the saveAll function. This setting is false by default.

  1. var $actsAs = array('FileUpload.FileUpload' => array(
  2.   'required' => true
  3. ));

Now anywhere in your app if you attempt to preform a $this->saveAll($data, array('validate' => 'first')); with the file model set as an associative key, an uploaded file will be required as well. If no file is detected during that saveAll the entire save is exited and a validation error occurs.

maxfilesize setting

maxFileSize is a new key setting that allows a developer to limit the size of an upload (note: this does *not* overwrite the limit set in php.ini). This is useful, to tone down the size of uploaded files allowed. The setting takes an int and corresponds to the byte size allowed. If set to false, no file size restrictions (other than those set in php.ini) are enforced on the uploaded file. maxFileSize is false by default.

  1. var $actsAs = array('FileUpload.FileUpload' => array(
  2.   'maxFileSize' => 102400, //in bytes (~100KB)
  3. ));

unique setting

Until now, the File Upload Plugin made sure never to overwrite any previously uploaded file. That is still the default behavior, but now you can turn that feature off if you wish.

  1. var $actsAs = array('FileUpload.FileUpload' => array(
  2.   'unique' => false
  3. ));

When unique is set to false, uploaded files will overwrite files on the server with the same name. This setting is true by default.

fileNameFunction setting

We saved the best for last. A much requested feature was the ability to manipulate the resulting filename in a number of ways. Until now, the only way a user could manipulate the file was in a beforeSave(), but that still required the developer to manually rename the file on the server. Some suggested using a sha1 hash, others a md5 hash, and the rest wanted the ability to define their own function to handle the resulting filename. I've decided to make you all happy!

Enter fileNameFunction setting. With this setting you can define your own filename filtering function, or use any built in PHP hashing function.

  1. var $actsAs = array('FileUpload.FileUpload' => array(
  2.   'fileNameFunction' => 'sha1'
  3. ));

Defining fileNameFunction as sha1, the resulting filename will first be passed into sha1() and then moved to the server and saved to the database. You can use *ANY* PHP function you wish, including functions you define either in bootstrap.php or within your Model.

Bootstrap.php Example:
  1. //config/bootstrap.php
  2. function prefix_string($str){
  3.   return 'prefix_' . $str;
  4. }
  6. //models/upload.php
  7. var $actsAs = array('FileUpload.FileUpload' => array(
  8.   'fileNameFunction' => 'prefix_string'
  9. ));

You can also define it within the same Model:
  1. //models/upload.php
  2. var $actsAs = array('FileUpload.FileUpload' => array(
  3.   'fileNameFunction' => 'sanitizeFileName'
  4. ));
  6. function sanitizeFileName($fileName){
  7.   //whatever filename logic you need
  8.   return $fileName;
  9. }

NOTE: The function you choose must return a string. If the resulting hash function does *not* return a string, the save will be halted and a validation error will occur.

Enjoy v5.0

I hope you enjoy the new features. As always, comments are appreciated. If you enjoy the plugin and wish to help keep it supported, please consider a donation (or click an ad a few times. :) ).