File Upload Plugin v4.0 -- Behaviors and Global Settings
Please Support:
CakePHP File Upload Plugin
Info:
- Version: 6.1.1
- Requirements: CakePHP 1.x, PHP
- Docs: CakePHP File Upload Plugin API
- Article: CakePHP File Upload Plugin Discussion and Examples
Watch:
Get it:
- Download Now
- git clone git://github.com/webtechnick/CakePHP-FileUpload-Plugin file_upload
New in version 4.0 of the File Upload Plugin is a new behavior and global settings classes. As most of you who are familiar with File Upload Plugin know, it was rather odd that when you setup the FileUpload component the way you wanted in your controller you then had to set it up again in your view for the helper to send the component the right information. Well, all that is gone with a new global settings class. For those of you not familiar with the File Upload Plugin, if you are developing a site that allows a display picture or avatar, perhaps one similar to http://www.partypoker.com/ you will know dealing with uploads can be tricky. Hopefully this plugin will clear up any issues you may have.
Settings you save in plugins/file_upload/config/file_upload_settings.php will be the new "default" settings across all your file uploading instances. This is true for the component, the helper, and the new behavior. By opening up this settings file you'll see all the documentation on what each setting does and how to manipulate it.
All the settings are there: fileModel, fileVar, uploadDir, allowedTypes, fields, automatic, and massSave (new since 3.6)
NEW WAY:
As you can see, each setting has been given its own method (actually its a __call overload so you can create your own settings if you'd like). By not passing in any parameters to the setting's method it will return the current value of that setting. If you then pass in a value to the setting's method you'll then be setting that setting (that's fun to say). I think an example will help explain:
NEW WAY:
As you can see, by passing in a value to that setting's method you'll now be setting that specific option.
Legacy Plugin: I've stamped the latest version without these API changes and without the behavior or global settings to 3.6.3. I will be keeping this legacy plugin for those who wish to stay with the old way of doing things. Get the legacy plugin v3.6.3 here: http://projects.webtechnick.com/file_upload_plugin_v3_6_3.tgz
The behavior is extremely flexible and easily fits into your current project allowing for automagic file uploading without you having to think about it. Setup is simple:
Attach the FileUpload.FileUpload to your model of choice, we'll use our trusty Upload model as an example...
Simple as that, now whenever you (or another associated model) save an upload with a file submitted, a record will be saved and all your file related columns (name,size,type) will be filled in for you automatically. The plugin takes special care not to overwrite files.
As discussed before, all the settings will be inherited by the new settings class located in /plugins/file_upload/config/file_upload_settings.php, but that doesn't mean you can't pass in your own settings on the fly. Using our same Upload model, lets change the save directory to 'uploads', our column names from name,size,type to file_size,file_size,file_type, lets only allow .pdfs to be uploaded, lets make it so an upload is required (required is new in 4.2.x), and only allow less than 10KB files (new in 4.3).
All set, all the default settings are the same except we're now uploading to the 'uploads' directory (app/webroot/uploads), we've changed our file specific columns from name, type, and size, to file_name, file_type, and file_size, we require a file to be uploaded, our max file size to allow is 10,000 bytes, and finally we're only allowing .pdf files to be uploaded and saved as new records.
Doing the upload is just as simple in the view, here's an example:
Doing your file uploading this way with a behavior lets you build your associations with full upload support without hesitation. Continuing with our example lets say we have an Application model that hasMany Uploads.
Assuming Application->hasMany->Uploads, in views/applications/add.ctp :
Notice we're just using normal cakePHP association syntax in our view, just be sure to use saveAll() instead of save() in your application controller add function. =)
That's it for version 4.0. There's more to look over in the API and in the actual code itself if you'd like to learn more.
API: http://projects.webtechnick.com/docs/file_upload_plugin
Thanks, I hope you all find it useful! As always, if you like the plugin, find a bug, or have a feature request -- post a comment. =)
Nick
Settings you save in plugins/file_upload/config/file_upload_settings.php will be the new "default" settings across all your file uploading instances. This is true for the component, the helper, and the new behavior. By opening up this settings file you'll see all the documentation on what each setting does and how to manipulate it.
All the settings are there: fileModel, fileVar, uploadDir, allowedTypes, fields, automatic, and massSave (new since 3.6)
API changes...
Due to the new way we handle our settings globally, setting and retrieving our settings has slightly changed. The full migration guide is included in the most recent version of this plugin (file_upload/migration_guide_3_x-4_0.txt), but I'll go over the change briefly as its very straight forward.GETTING YOUR SETTINGS:
OLD WAY:- $this->FileUpload->fileModel;
- $this->FileUpload->fileVar;
- $this->FileUpload->fields;
- $this->FileUpload->fileModel();
- $this->FileUpload->fileVar();
- $this->FileUpload->fields();
As you can see, each setting has been given its own method (actually its a __call overload so you can create your own settings if you'd like). By not passing in any parameters to the setting's method it will return the current value of that setting. If you then pass in a value to the setting's method you'll then be setting that setting (that's fun to say). I think an example will help explain:
SETTING YOUR SETTINGS:
OLD WAY:- $this->FileUpload->fileModel = null;
- $this->FileUpload->fileVar = 'file';
- $this->FileUpload->fileModel(null);
- $this->FileUpload->fileVar('file');
As you can see, by passing in a value to that setting's method you'll now be setting that specific option.
Legacy Plugin: I've stamped the latest version without these API changes and without the behavior or global settings to 3.6.3. I will be keeping this legacy plugin for those who wish to stay with the old way of doing things. Get the legacy plugin v3.6.3 here: http://projects.webtechnick.com/file_upload_plugin_v3_6_3.tgz
Behaviors for the WIN!
New in 4.0 is a great behavior to attach to your model. By using this behavior you will no longer need the component. I've left the component in, for legacy reasons, as well as its the only way to preform file uploads without a model (one of my main goals when developing this project).The behavior is extremely flexible and easily fits into your current project allowing for automagic file uploading without you having to think about it. Setup is simple:
Attach the FileUpload.FileUpload to your model of choice, we'll use our trusty Upload model as an example...
- class Upload extends AppModel {
- var $name = 'Upload';
- }
Simple as that, now whenever you (or another associated model) save an upload with a file submitted, a record will be saved and all your file related columns (name,size,type) will be filled in for you automatically. The plugin takes special care not to overwrite files.
As discussed before, all the settings will be inherited by the new settings class located in /plugins/file_upload/config/file_upload_settings.php, but that doesn't mean you can't pass in your own settings on the fly. Using our same Upload model, lets change the save directory to 'uploads', our column names from name,size,type to file_size,file_size,file_type, lets only allow .pdfs to be uploaded, lets make it so an upload is required (required is new in 4.2.x), and only allow less than 10KB files (new in 4.3).
- class Upload extends AppModel {
- var $name = 'Upload';
- 'uploadDir' => 'uploads',
- 'name' => 'file_name',
- 'type' => 'file_type',
- 'size' => 'file_size'
- ),
- 'requilred' => true,
- 'maxFileSize' => '10000',
- )
- );
- }
All set, all the default settings are the same except we're now uploading to the 'uploads' directory (app/webroot/uploads), we've changed our file specific columns from name, type, and size, to file_name, file_type, and file_size, we require a file to be uploaded, our max file size to allow is 10,000 bytes, and finally we're only allowing .pdf files to be uploaded and saved as new records.
Doing the upload is just as simple in the view, here's an example:
Doing your file uploading this way with a behavior lets you build your associations with full upload support without hesitation. Continuing with our example lets say we have an Application model that hasMany Uploads.
Assuming Application->hasMany->Uploads, in views/applications/add.ctp :
- echo $form->input('Application.name');
Notice we're just using normal cakePHP association syntax in our view, just be sure to use saveAll() instead of save() in your application controller add function. =)
Automagic File Upload Deletions...
The new behavior will automatically delete the source file when the record of that upload has been deleted. No more worrying if you have old crusty files hanging around your file system long after any record of it ever exists. =)That's it, enjoy the new features!
That's it for version 4.0. There's more to look over in the API and in the actual code itself if you'd like to learn more.
API: http://projects.webtechnick.com/docs/file_upload_plugin
Thanks, I hope you all find it useful! As always, if you like the plugin, find a bug, or have a feature request -- post a comment. =)
Nick
