The Upload Plugin is an attempt to sanely upload files using techniques garnered packages such as MeioUpload , UploadPack and PHP documentation.

I will not accept any feature pull requests. They are sometimes of dubious quality and ensuring everything useful gets into the core is difficult at best. Please create a ticket for the functionality you desire and I will either extend this plugin or build it into the core.

If it is a bug-fix, feel free to issue a pull request, but be aware that reviewing your submission will take time and it may not be accepted as-is.

That said, I appreciate any and all feedback, especially on untested code such as this :)

• CakePHP 1.2/1.3
• Imagick/GD PHP Extension (for Thumbnail Creation)
• PHP5 (Not really, but I’m more likely to be able to fix a PHP5 issue than a PHP4 issue)
• Patience

1. Download this: http://github.com/josegonzalez/upload/zipball/master
2. Unzip that download.
3. Copy the resulting folder to app/plugins
4. Rename the folder you just copied to upload

CREATE table users (
	id int(10) unsigned NOT NULL auto_increment,
	username varchar(20) NOT NULL,
	photo varchar(255)
);

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'photo'
		)
	);
}
?>

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.username'); ?>
	<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
<?php echo $this->Form->end(); ?>

Using the above setup, uploaded files cannot be deleted. To do so, a field must be added to store the directory of the file as follows:

CREATE table users (
	`id` int(10) unsigned NOT NULL auto_increment,
	`username` varchar(20) NOT NULL,
	`photo` varchar(255) DEFAULT NULL,
	`photo_dir` varchar(255) DEFAULT NULL,
	PRIMARY KEY (`id`)
);

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'profile_picture' => array(
				'fields' => array(
					'dir' => 'photo_dir'
				)
			)
		)
	);
}
?>

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.username'); ?>
	<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
	<?php echo $this->Form->input('User.photo_dir', array('type' => 'hidden')); ?>
<?php echo $this->Form->end(); ?>

Thumbnails are not automatically created. To do so, thumbnail sizes must be defined:

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'fields' => array(
					'dir' => 'photo_dir'
				),
				'thumbsizes' => array(
					'xvga' => '1024x768',
					'vga' => '640x480',
					'thumb' => '80x80'
				)
			)
		)
	);
}
?>

Multiple files can also be attached to a single record:

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'resume',
			'photo' => array(
				'fields' => array(
					'dir' => 'profile_dir'
				),
				'thumbsizes' => array(
					'xvga' => '1024x768',
					'vga' => '640x480',
					'thumb' => '80x80'
				)
			)
		)
	);
}
?>

Please read about the Behavior options for more details as to how to configure this plugin.

• pathMethod: The method to use for file paths
  • Default: (string) primaryKey
  • Options:
    • flat: Does not create a path for each record. Files are moved to the value of the ‘path’ option
    • primaryKey: Path based upon the record’s primaryKey is generated. Persists across a record
    • random: Random path is generated for each file upload. Does not persist across a record.
• path: A path relative to the APP_PATH
  • Default: (string) 'webroot{DS}files{DS}{model}{DS}{field}{DS}'
  • Tokens:
    • {DS}: Replaced by a DIRECTORY_SEPARATOR
    • {model}: Replaced by the Model Alias
    • {field}: Replaced by the field name
• fields: An array of fields to use when uploading files
  • Default: (array) array('dir' => 'dir', 'type' => 'type', 'size' => 'size')
  • Options:
    • dir: Field to use for storing the directory
    • type: Field to use for storing the filetype
    • size: Field to use for storing the filesize
• mimetypes: Array of mimetypes to use for validation
  • Default: (array) empty
• extensions: Array of extensions to use for validation
  • Default: (array) empty
• maxSize: Max filesize in bytes for validation
  • Default: (int) 2097152
• minSize: Minimum filesize in bytes for validation
  • Default: (int) 8
• maxHeight: Maximum image height for validation
  • Default: (int) 0
• minHeight: Minimum image height for validation
  • Default: (int) 0
• maxWidth: Maximum image width for validation
  • Default: (int) 0
• minWidth: Minimum image width for validation
  • Default: (int) 0
• prefixStyle: Whether to prefix or suffix the style onto thumbnails
  • Default: (boolean) true
• thumbnails: Whether to create thumbnails or not
  • Default: (boolean) true
• thumbsizes: Array of thumbnail sizes, with the style-name mapping to a geometry
  • Default: (array) empty
• thumbnailQuality: Quality of thumbnails that will be generated, on a scale of 0-100
  • Default: (int) 75
• thumbnailMethod: The method to use for resizing thumbnails
  • Default: (string) imagick
  • Options:
    • imagick: Uses the PHP imagick extension to generate thumbnails
    • php: Uses the built-in PHP methods to generate thumbnails

Styles are the definition of thumbnails that will be generated for original image. You can define as many as you want.

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'thumbsizes' => array(
					'big' => '200x200',
					'small' => '120x120'
					'thumb' => '80x80'
				)
			)
		)
	);
?>

Styles only apply to images of the following types:

• image/bmp
• image/gif
• image/jpeg
• image/pjpeg
• image/png
• image/vnd.microsoft.icon
• image/x-icon

You can specify any of the following resize modes for your styles:

• 100×80 – resize for best fit into these dimensions, with overlapping edges trimmed if original aspect ratio differs
• [100×80] – resize to fit these dimensions, with white banding if original aspect ratio differs
• 100w – maintain original aspect ratio, resize to 100 pixels wide
• 80h – maintain original aspect ratio, resize to 80 pixels high
• 80l – maintain original aspect ratio, resize so that longest side is 80 pixels

By default, no validation rules are attached to the model. One must explicitly attach each rule if needed. Rules not referring to PHP upload errors are configurable but fallback to the behavior configuration.

Check that the file does not exceed the max file size specified by PHP

var $validate = array(
	'photo' => array(
		'rule' => 'isUnderPhpSizeLimit',
		'message' => 'File exceeds upload filesize limit'
	)
);

Check that the file does not exceed the max file size specified in the HTML Form

var $validate = array(
	'photo' => array(
		'rule' => 'isUnderFormSizeLimit',
		'message' => 'File exceeds form upload filesize limit'
	)
);

Check that the file was completely uploaded

var $validate = array(
	'photo' => array(
		'rule' => 'isCompletedUpload',
		'message' => 'File was not successfully uploaded'
	)
);

Check that a file was uploaded

var $validate = array(
	'photo' => array(
		'rule' => 'isFileUpload',
		'message' => 'File was missing from submission'
	)
);

Check that the PHP temporary directory is missing

var $validate = array(
	'photo' => array(
		'rule' => 'tempDirExists',
		'message' => 'The system temporary directory is missing'
	)
);

Check that the file was successfully written to the server

var $validate = array(
	'photo' => array(
		'rule' => 'isSuccessfulWrite',
		'message' => 'File was unsuccessfully written to the server'
	)
);

Check that a PHP extension did not cause an error

var $validate = array(
	'photo' => array(
		'rule' => 'noPhpExtensionErrors',
		'message' => 'File was not uploaded because of a faulty PHP extension'
	)
);

Check that the file is of a valid mimetype

var $validate = array(
	'photo' => array(
		'rule' => 'isValidMimeType',
		'message' => 'File is of an invalid mimetype'
	)
);

Check that the upload directory is writable

var $validate = array(
	'photo' => array(
		'rule' => 'isWritable',
		'message' => 'File upload directory was not writable'
	)
);

Check that the upload directory exists

var $validate = array(
	'photo' => array(
		'rule' => 'isValidDir',
		'message' => 'File upload directory does not exist'
	)
);

Check that the file is below the maximum file upload size

var $validate = array(
	'photo' => array(
		'rule' => 'isBelowMaxSize',
		'message' => 'File is larger than the maximum filesize'
	)
);

Check that the file is above the minimum file upload size

var $validate = array(
	'photo' => array(
		'rule' => 'isAboveMinSize',
		'message' => 'File is below the mimimum filesize'
	)
);

Check that the file has a valid extension

var $validate = array(
	'photo' => array(
		'rule' => 'isValidExtension',
		'message' => 'File has an invalid extension'
	)
);

Check that the file is above the minimum height requirement

var $validate = array(
	'photo' => array(
		'rule' => 'isAboveMinHeight',
		'message' => 'File is below the minimum height'
	)
);

Check that the file is below the maximum height requirement

var $validate = array(
	'photo' => array(
		'rule' => 'isBelowMaxHeight',
		'message' => 'File is above the maximum height'
	)
);

Check that the file is above the minimum width requirement

var $validate = array(
	'photo' => array(
		'rule' => 'isAboveMinWidth',
		'message' => 'File is below the minimum width'
	)
);

Check that the file is below the maximum width requirement

var $validate = array(
	'photo' => array(
		'rule' => 'isBelowMaxWidth',
		'message' => 'File is above the maximum width'
	)
);

UploadHelper::url($data, $field, $full = false)

Returns url to the uploaded file

• $data – record from database, can be a $this->Model->read() result or a association result like hasMany
• $field – name of a field like this Modelname.fieldname (would be User.photo here)
• $full – if true, the full base URL will be prepended to the result

Assuming tha you have read a user from database and it’s available in $user variable in view with this:

$user = array(
	'User' => array(
		'id' => 1,
		'dir' => '1',
		'photo' => 'Photo.png'
	)
);

<?php echo $upload->url($user, 'User.photo'); ?>

Will output /files/user/photo/1/Photo.png

But when the user is fetched as one of many users associated by hasMany association to another model it could be something like:

$data = array(
	'User' => array(
		0 => array(
			'id' => 1,
			'dir' => '1',
			'photo' => 'Photo.png'
		),
		1 => array(
			'id' => 2,
			'dir' => '1',
			'photo' => 'Photo2.png'
		)
	)
);

Then you should do:

<?php echo $upload->url($data['User'][0], 'User.photo') ?>

The helper is smart enough to figure out the structure of data you pass to it.

If you have defined thumbsizes on you model like:

<?php
class User extends AppModel {
	var $name = 'User';
	var $actsAs = array(
		'Upload.Upload' => array(
			'photo' => array(
				'thumbsizes' => array(
					'thumb' => '50x50',
					'galeria' => '180x180'
				)
			)
		)
	);
}
?>

You can use helper to get url for any of thumb you defined:

<?php echo $upload->url($data['User'][0], 'User.photo.thumb') ?>

UploadHelper::image($data, $field, $options = array())

Returns image tag pointing to uploaded file.

• $data – record from database, can be a $this->Model->read() result or a association result like hasMany
• $field – name of a field like this Modelname.fieldname (would be User.photo here)
• $options – array of HTML attributes.

You can use like any of options of UploadHelper::url() explained above like:

<?php echo $upload->image($user, 'User.photo'); ?>