pictcode

*CakePlugin::load('DebugKit'); // Loads a single plugin named DebugKit

  CakePlugin::loadAll(); // Loads all plugins at once

<?php

App::uses('HttpSocket', 'Network/Http');

/**

 * This file is a part of UploadPack - a plugin that makes file uploads in CakePHP as easy as possible.

 *

 * UploadBehavior

 *

 * UploadBehavior does all the job of saving files to disk while saving records to database. For more info read UploadPack documentation.

 *

 * joe bartlett's lovingly handcrafted tweaks add several resize modes. see "more on styles" in the documentation.

 *

 * @author Michał Szajbe (michal.szajbe@gmail.com) and joe bartlett (contact@jdbartlett.com)

 * @link http://github.com/szajbus/uploadpack

 */

class UploadBehavior extends ModelBehavior {

    private static $__settings = array();

    private $toWrite = array();

    private $toDelete = array();

    private $maxWidthSize = false;

    public function setup(Model $model, $settings = array()) {

        $defaults = array(

            'path' => ':webroot/upload/:model/:id/:basename_:style.:extension',

            'styles' => array(),

            'resizeToMaxWidth' => false,

            'quality' => 75,

            'alpha' => false

        );

        foreach ($settings as $field => $array) {

            self::$__settings[$model->name][$field] = array_merge($defaults, $array);

        }

    }

    public function beforeSave(Model $model, $options = array()) {

        $this->_reset();

        foreach (self::$__settings[$model->name] as $field => $settings) {

            if (!empty($model->data[$model->name][$field]) && is_array($model->data[$model->name][$field]) && file_exists($model->data[$model->name][$field]['tmp_name'])) {

                if (!empty($model->id)) {

                    $this->_prepareToDeleteFiles($model, $field, true);

                }

                $this->_prepareToWriteFiles($model, $field);

                unset($model->data[$model->name][$field]);

                $model->data[$model->name][$field.'_file_name'] = $this->toWrite[$field]['name'];

                $model->data[$model->name][$field.'_file_size'] = $this->toWrite[$field]['size'];

                $model->data[$model->name][$field.'_content_type'] = $this->toWrite[$field]['type'];

            } elseif (array_key_exists($field, $model->data[$model->name]) && $model->data[$model->name][$field] === null) {

                if (!empty($model->id)) {

                    $this->_prepareToDeleteFiles($model, $field, true);

                }

                unset($model->data[$model->name][$field]);

                $model->data[$model->name][$field.'_file_name'] = null;

                $model->data[$model->name][$field.'_file_size'] = null;

                $model->data[$model->name][$field.'_content_type'] = null;

            }

        }

        return true;

    }

    public function afterSave(Model $model, $create, $options = array()) {

        if (!$create) {

            $this->_deleteFiles($model);

        }

        $this->_writeFiles($model);

    }

    public function beforeDelete(Model $model, $cascade = true) {

        $this->_reset();

        $this->_prepareToDeleteFiles($model);

        return true;

    }

    public function afterDelete(Model $model) {

        $this->_deleteFiles($model);

    }

    public function beforeValidate(Model $model, $options = array()) {

        foreach (self::$__settings[$model->name] as $field => $settings) {

            if (isset($model->data[$model->name][$field])) {

                $data = $model->data[$model->name][$field];

                if ((empty($data) || is_array($data) && empty($data['tmp_name'])) && !empty($settings['urlField']) && !empty($model->data[$model->name][$settings['urlField']])) {

                    $data = $model->data[$model->name][$settings['urlField']];

                }

                if (!is_array($data)) {

                    $model->data[$model->name][$field] = $this->_fetchFromUrl($data);

                }

            }

        }

        return true;

    }

    private function _reset() {

        $this->toWrite = null;

        $this->toDelete = null;

    }

    private function _fetchFromUrl($url) {

        $path_chunks = explode('/', $url);

        $filename_chunks = explode('.', $url);

        $data = array('remote' => true);

        $data['name'] = end($path_chunks);

        $data['tmp_name'] = tempnam(sys_get_temp_dir(), $data['name']) . '.' . end($filename_chunks);

        $httpSocket = new HttpSocket();

        $raw = $httpSocket->get($url);

        $response = $httpSocket->response;

        $content_types = explode(';', $response['header']['Content-Type']);

        $data['size'] = strlen($raw);

        $data['type'] = reset($content_types);

        file_put_contents($data['tmp_name'], $raw);

        return $data;

    }

    private function _prepareToWriteFiles(&$model, $field) {

        $this->toWrite[$field] = $model->data[$model->name][$field];

        // make filename URL friendly by using Cake's Inflector

        $this->toWrite[$field]['name'] =

            Inflector::slug(substr($this->toWrite[$field]['name'], 0, strrpos($this->toWrite[$field]['name'], '.'))). // filename

            substr($this->toWrite[$field]['name'], strrpos($this->toWrite[$field]['name'], '.')); // extension

    }

    protected function afterMove($file) {

        // do nothing here

    }

    private function _writeFiles(&$model) {

        if (!empty($this->toWrite)) {

            foreach ($this->toWrite as $field => $toWrite) {

                $settings = $this->_interpolate($model, $field, $toWrite['name'], 'original');

                $destDir = dirname($settings['path']);

                if (!file_exists($destDir)) {

                    @mkdir($destDir, 0777, true);

                    @chmod($destDir, 0777);

                }

                if (is_dir($destDir) && is_writable($destDir)) {

                    $move = !empty($toWrite['remote']) ? 'rename' : 'move_uploaded_file';

                    if (@$move($toWrite['tmp_name'], $settings['path'])) {

                        $this->afterMove($settings['path']);  // <==== Calling afterMove() callback method

                        if($this->maxWidthSize) {

                            $this->_resize($settings['path'], $settings['path'], $this->maxWidthSize.'w', $settings['quality'], $settings['alpha']);

                        }

                        foreach ($settings['styles'] as $style => $geometry) {

                            $newSettings = $this->_interpolate($model, $field, $toWrite['name'], $style);

                            $this->_resize($settings['path'], $newSettings['path'], $geometry, $settings['quality'], $settings['alpha']);

                        }

                    }

                }

            }

        }

    }

    private function _prepareToDeleteFiles(&$model, $field = null, $forceRead = false) {

        $needToRead = true;

        if ($field === null) {

            $fields = array_keys(self::$__settings[$model->name]);

            foreach ($fields as &$field) {

                $field .= '_file_name';

            }

        } else {

            $field .= '_file_name';

            $fields = array($field);

        }

        if (!$forceRead && !empty($model->data[$model->alias])) {

            $needToRead = false;

            foreach ($fields as $field) {

                if (!array_key_exists($field, $model->data[$model->alias])) {

                    $needToRead = true;

                    break;

                }

            }

        }

        if ($needToRead) {

            $data = $model->find('first', array('conditions' => array($model->alias.'.'.$model->primaryKey => $model->id), 'fields' => $fields, 'callbacks' => false));

        } else {

            $data = $model->data;

        }

        if (is_array($this->toDelete)) {

            $this->toDelete = array_merge($this->toDelete, $data[$model->alias]);

        } else {

            $this->toDelete = $data[$model->alias];

        }

        $this->toDelete['id'] = $model->id;

    }

    private function _deleteFiles(&$model) {

        foreach (self::$__settings[$model->name] as $field => $settings) {

            if (!empty($this->toDelete[$field.'_file_name'])) {

                $styles = array_keys($settings['styles']);

                $styles[] = 'original';

                foreach ($styles as $style) {

                    $settings = $this->_interpolate($model, $field, $this->toDelete[$field.'_file_name'], $style);

                    if (file_exists($settings['path'])) {

                        @unlink($settings['path']);

                    }

                }

            }

        }

    }

    private function _interpolate(&$model, $field, $filename, $style) {

        return self::interpolate($model->name, $model->id, $field, $filename, $style);

    }

    static public function interpolate($modelName, $modelId, $field, $filename, $style = 'original', $defaults = array()) {

        $pathinfo = UploadBehavior::_pathinfo($filename);

        $interpolations = array_merge(array(

            'app' => preg_replace('/\/$/', '', APP),

            'webroot' => preg_replace('/\/$/', '', WWW_ROOT),

            'model' => Inflector::tableize($modelName),

            'basename' => !empty($filename) ? $pathinfo['filename'] : null,

            'extension' => !empty($filename) ? $pathinfo['extension'] : null,

            'id' => $modelId,

            'style' => $style,

            'attachment' => Inflector::pluralize($field),

            'hash' => md5((!empty($filename) ? $pathinfo['filename'] : "") . Configure::read('Security.salt'))

        ), $defaults);

        $settings = self::$__settings[$modelName][$field];

        $keys = array('path', 'url', 'default_url');

        foreach ($interpolations as $k => $v) {

            foreach ($keys as $key) {

                if (isset($settings[$key])) {

                    $settings[$key] = preg_replace('/\/{2,}/', '/', str_replace(":$k", $v, $settings[$key]));

                }

            }

        }

        return $settings;

    }

    static private function _pathinfo($filename) {

        $pathinfo = pathinfo($filename);

        // PHP < 5.2.0 doesn't include 'filename' key in pathinfo. Let's try to fix this.

        if (empty($pathinfo['filename'])) {

            $suffix = !empty($pathinfo['extension']) ? '.'.$pathinfo['extension'] : '';

            $pathinfo['filename'] = basename($pathinfo['basename'], $suffix);

        }

        return $pathinfo;

    }

    private function _resize($srcFile, $destFile, $geometry, $quality = 75, $alpha = false) {

        copy($srcFile, $destFile);

        @chmod($destFile, 0777);

        $pathinfo = UploadBehavior::_pathinfo($srcFile);

        $src = null;

        $createHandler = null;

        $outputHandler = null;

        switch (strtolower($pathinfo['extension'])) {

        case 'gif':

            $createHandler = 'imagecreatefromgif';

            $outputHandler = 'imagegif';

            break;

        case 'jpg':

        case 'jpeg':

            $createHandler = 'imagecreatefromjpeg';

            $outputHandler = 'imagejpeg';

            break;

        case 'png':

            $createHandler = 'imagecreatefrompng';

            $outputHandler = 'imagepng';

            $quality = null;

            break;

        default:

            return false;

        }

        if ($src = $createHandler($destFile)) {

            $srcW = imagesx($src);

            $srcH = imagesy($src);

            // determine destination dimensions and resize mode from provided geometry

            if (preg_match('/^\\[[\\d]+x[\\d]+\\]$/', $geometry)) {

                // resize with banding

                list($destW, $destH) = explode('x', substr($geometry, 1, strlen($geometry)-2));

                $resizeMode = 'band';

            } elseif (preg_match('/^[\\d]+x[\\d]+$/', $geometry)) {

                // cropped resize (best fit)

                list($destW, $destH) = explode('x', $geometry);

                $resizeMode = 'best';

            } elseif (preg_match('/^[\\d]+w$/', $geometry)) {

                // calculate heigh according to aspect ratio

                $destW = (int)$geometry-1;

                $resizeMode = false;

            } elseif (preg_match('/^[\\d]+h$/', $geometry)) {

                // calculate width according to aspect ratio

                $destH = (int)$geometry-1;

                $resizeMode = false;

            } elseif (preg_match('/^[\\d]+l$/', $geometry)) {

                // calculate shortest side according to aspect ratio

                if ($srcW > $srcH) $destW = (int)$geometry-1;

                else $destH = (int)$geometry-1;

                $resizeMode = false;

            }

            if (!isset($destW)) $destW = ($destH/$srcH) * $srcW;

            if (!isset($destH)) $destH = ($destW/$srcW) * $srcH;

            // determine resize dimensions from appropriate resize mode and ratio

            if ($resizeMode == 'best') {

                // "best fit" mode

                if ($srcW > $srcH) {

                    if ($srcH/$destH > $srcW/$destW) $ratio = $destW/$srcW;

                    else $ratio = $destH/$srcH;

                } else {

                    if ($srcH/$destH < $srcW/$destW) $ratio = $destH/$srcH;

                    else $ratio = $destW/$srcW;

                }

                $resizeW = $srcW*$ratio;

                $resizeH = $srcH*$ratio;

            }

            elseif ($resizeMode == 'band') {

                // "banding" mode

                if ($srcW > $srcH) $ratio = $destW/$srcW;

                else $ratio = $destH/$srcH;

                $resizeW = $srcW*$ratio;

                $resizeH = $srcH*$ratio;

            }

            else {

                // no resize ratio

                $resizeW = $destW;

                $resizeH = $destH;

            }

            $img = imagecreatetruecolor($destW, $destH);

            if ($alpha === true) {

                switch (strtolower($pathinfo['extension'])) {

                case 'gif':

                    $alphaColor = imagecolortransparent($src);

                    imagefill($img, 0, 0, $alphaColor);

                    imagecolortransparent($img, $alphaColor);

                    break;

                case 'png':

                    imagealphablending($img, false);

                    imagesavealpha($img, true);

                    break;

                default:

                    imagefill($img, 0, 0, imagecolorallocate($img, 255, 255, 255));

                    break;

                }

            } else {

                imagefill($img, 0, 0, imagecolorallocate($img, 255, 255, 255));

            }

            imagecopyresampled($img, $src, ($destW-$resizeW)/2, ($destH-$resizeH)/2, 0, 0, $resizeW, $resizeH, $srcW, $srcH);

            $outputHandler($img, $destFile, $quality);

            return true;

        }

        return false;

    }

    public function attachmentMinSize(Model $model, $value, $min, $options = array()) {

        $value = array_shift($value);

        if (!empty($value['tmp_name'])) {

            return (int)$min <= (int)$value['size'];

        } else if (isset($options['allowEmpty']) && $options['allowEmpty'] === false) {

          return false;

        }

        return true;

    }

    public function attachmentMaxSize(Model $model, $value, $max, $options = array()) {

        $value = array_shift($value);

        if (!empty($value['tmp_name'])) {

            return (int)$value['size'] <= (int)$max;

        } else if (isset($options['allowEmpty']) && $options['allowEmpty'] === false) {

          return false;

        }

        return true;

    }

    public function attachmentContentType(Model $model, $value, $contentTypes, $options = array()) {

        $value = array_shift($value);

        if (!is_array($contentTypes)) {

            $contentTypes = array($contentTypes);

        }

        if (!empty($value['tmp_name'])) {

            foreach ($contentTypes as $contentType) {

                if (substr($contentType, 0, 1) == '/') {

                    if (preg_match($contentType, $value['type'])) {

                        return true;

                    }

                } elseif ($contentType == $value['type']) {

                    return true;

                }

            }

            return false;

        } else if (isset($options['allowEmpty']) && $options['allowEmpty'] === false) {

          return false;

        }

        return true;

    }

    public function attachmentPresence(Model $model, $value, $options = array()) {

        $keys = array_keys($value);

        $field = $keys[0];

        $value = array_shift($value);

        if (!empty($value['tmp_name'])) {

            return true;

        }

        if (!empty($model->id)) {

            if (!empty($model->data[$model->alias][$field.'_file_name'])) {

                return true;

            } elseif (!isset($model->data[$model->alias][$field.'_file_name'])) {

                $existingFile = $model->field($field.'_file_name', array($model->primaryKey => $model->id));

                if (!empty($existingFile)) {

                    return true;

                }

            }

        }

        return false;

    }

    public function minWidth(Model $model, $value, $minWidth, $options = array()) {

        return $this->_validateDimension($value, 'min', 'x', $minWidth, $options);

    }

    public function minHeight(Model $model, $value, $minHeight, $options = array()) {

        return $this->_validateDimension($value, 'min', 'y', $minHeight, $options);

    }

    public function maxWidth(Model $model, $value, $maxWidth, $options = array()) {

        $keys = array_keys($value);

        $field = $keys[0];

        $settings = self::$__settings[$model->name][$field];

        if($settings['resizeToMaxWidth'] && !$this->_validateDimension($value, 'max', 'x', $maxWidth, $options)) {

            $this->maxWidthSize = $maxWidth;

            return true;

        } else {

            return $this->_validateDimension($value, 'max', 'x', $maxWidth, $options);

        }

    }

    public function maxHeight(Model $model, $value, $maxHeight, $options = array()) {

        return $this->_validateDimension($value, 'max', 'y', $maxHeight, $options);

    }

    private function _validateDimension($upload, $mode, $axis, $value, $options) {

        $upload = array_shift($upload);

        $func = 'images'.$axis;

        if(!empty($upload['tmp_name'])) {

            $createHandler = null;

            if($upload['type'] == 'image/jpeg') {

                $createHandler = 'imagecreatefromjpeg';

            } else if($upload['type'] == 'image/gif') {

                $createHandler = 'imagecreatefromgif';

            } else if($upload['type'] == 'image/png') {

                $createHandler = 'imagecreatefrompng';

            } else {

                return false;

            }

            if($img = $createHandler($upload['tmp_name'])) {

                switch ($mode) {

                case 'min':

                    return $func($img) >= $value;

                    break;

                case 'max':

                    return $func($img) <= $value;

                    break;

                }

            }

        } else if (isset($options['allowEmpty']) && $options['allowEmpty'] === true) {

            return true;

        }

        return false;

    }

    public function phpUploadError(Model $model, $value, $uploadErrors = array('UPLOAD_ERR_INI_SIZE', 'UPLOAD_ERR_FORM_SIZE', 'UPLOAD_ERR_PARTIAL', 'UPLOAD_ERR_NO_FILE', 'UPLOAD_ERR_NO_TMP_DIR', 'UPLOAD_ERR_CANT_WRITE', 'UPLOAD_ERR_EXTENSION'), $options = array()) {

        $value = array_shift($value);

        if (!is_array($uploadErrors)) {

            $uploadErrors = array($uploadErrors);

        }

        if (!empty($value['error'])) {

            return !in_array($value['error'], $uploadErrors);

        } else if (isset($options['allowEmpty']) && $options['allowEmpty'] === false) {

            return false;

        }

        return true;

    }

}

h1. UploadPack

"!https://pledgie.com/campaigns/7880.png?skin_name=chrome!(Using it in production? Share some love...)":https://www.pledgie.com/campaigns/7880

UploadPack is a plugin that makes file uploads in CakePHP as easy as possible. It works with almost no configuration, but if you need more flexibility you can easily override default settings.

What's included:

h4. UploadBehavior

Attach it to your model, it will detect any uploaded file and save it to disk. It can even automatically generate thumbnails of uploaded images.

h4. UploadHelper

Use it in your views to display uploaded images or links to files in general.

h2. Installation

# Download this: _http://github.com/szajbus/uploadpack/zipball/master_

# Unzip that download.

# Copy the resulting folder to _app/plugins_

# Rename the folder you just copied to _upload_pack_

h2. Usage

Look at an example.

Scenario: Let users upload their avatars and then display them in two styles - original size and thumbnail.

Solution:

We'll need @User@ model with @avatar_file_name@ field.

<pre><code>CREATE table users (

	id int(10) unsigned NOT NULL auto_increment,

	login varchar(20) NOT NULL,

	avatar_file_name varchar(255)

);

</code></pre>

Attach @UploadBehavior@ to @User@ model and set it up to handle avatars.

<pre><code><?php

	class User extends AppModel {

		var $name = 'User';

		var $actsAs = array(

			'UploadPack.Upload' => array(

				'avatar' => array(

					'styles' => array(

						'thumb' => '80x80'

					)

				)

			)

		);

	}

?>

</code></pre>

That's all we need to do with our model. We defined one thumbnail style named 'thumb' which means that uploaded image's thumnbnail of 80x80 pixels size will be generated and saved to disk together with original image.

We didn't touch any other configuration settings so files will be saved as @webroot/upload/:model/:id/:basename_:style.:extension@ (with :keys appropriately substituted at run time). Make sure that @webroot/upload/users@ folder is writeable.

Let's upload a file now. We need to add a file field to a standard "create user" form. Your form must have the right enctype attribute to support file uploads, e.g. @$form->create('Users', array('type' => 'file'));@. Note that we omit the field's @_file_name@ suffix here.

<pre><code><?php echo $form->file('User.avatar') ?></code></pre>

The last thing to do is to handle form-submit in a controller.

<pre><code><?php

class UsersController extends AppController {

	var $name = 'Users';

	var $uses = array('User');

	var $helpers = array('Form', 'UploadPack.Upload');

	function create() {

		if (!empty($this->data)) {

			$this->User->create($this->data);

			if ($this->User->save()) {

				$this->redirect('/users/show/'.$this->User->id);

			}

		}

	}

	function show($id) {

		$this->set('user', $this->User->findById($id));

	}

}

?>

</code></pre>

Let's create @users/show.ctp@ view to see the results. Note that we've included UploadHelper in controller's $helpers.

<pre><code>That would be the original file:

<?php echo $this->Upload->uploadImage($user, 'User.avatar') ?>

And now it's thumbnail:

<?php echo $this->Upload->uploadImage($user, 'User.avatar', array('style' => 'thumb')) ?>

</code></pre>

That's how you create new records with uploaded files. Updating existing record would delete a file attached to it from disk.

Could it be any easier? Probably not. Is there more to offer? Yes.

h3. Advanced configuration

h4. You can validate uploaded files

@UploadBehavior@ provides some validation rules for you to use together with standard CakePHP validation mechanism.

Validate attachment's size:

<pre><code>var $validate = array(

	'avatar' => array(

		'maxSize' => array(

			'rule' => array('attachmentMaxSize', 1048576),

			'message' => 'Avatar can\'t be larger than 1MB'

		),

		'minSize' => array(

			'rule' => array('attachmentMinSize', 1024),

			'message' => 'Avatar can\'t be smaller than 1KB'

		)

	)

);

</code></pre>

Validate attachment's content type:

<pre><code>var $validate = array(

	'avatar' => array(

		'image1 => array(

			'rule' => array('attachmentContentType', 'image/jpeg'),

			'message' => 'Only jpegs please'

		),

		'image2' => array(

			'rule' => array('attachmentContentType', array('image/jpeg', 'image/gif')),

			'message' => 'Only jpegs or gifs please'

		),

		'image3' => array(

			'rule' => array('attachmentContentType', array('document/pdf', '/^image\/.+/')),

			'message' => 'Only pdfs or images please'

		)

	)

);

</code></pre>

Validate attachment's presence:

<pre><code>var $validate = array(

	'avatar' => array(

		'rule' => array('attachmentPresence'),

		'message' => 'Avatar is required'

	)

);

</code></pre>

Validate image size:

<pre><code>var $validate = array(

	'avatar' => array(

		'minWidth' => array(

			'rule' => array('minWidth', '100'),

			'message' => 'Photo must be at least 100 pixels wide'

		),

		'maxWidth' => array(

			'rule' => array('maxWidth', '600'),

			'message' => 'Photo can\'t be over 600 pixels wide'

		),

		'minHeight' => array(

			'rule' => array('minHeight', '100'),

			'message' => 'Photo must be at least 100 pixels wide'

		),

		'maxHeight' => array(

			'rule' => array('maxHeight', '600'),

			'message' => 'Photo can\'t be over 600 pixels wide'

		)

	)

);

</code></pre>

If you're editing a record that already has avatar attached and you don't supply a new one, record will be valid.

Validate php upload errors:

PHP: Error Messages Explained - Manual (http://www.php.net/manual/features.file-upload.errors.php)

<pre><code>var $validate = array(

	'avatar' => array(

		'checkIniSizeError' => array(

			'rule' => array('phpUploadError', UPLOAD_ERR_INI_SIZE),

			'message' => 'The uploaded file exceeds the upload_max_filesize directive in php.ini'

		),

		'checkSizesError' => array(

			'rule' => array('phpUploadError', array(UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE)),

			'message' => 'The uploaded file exceeds the upload_max_filesize directive in php.ini or MAX_FILE_SIZE directive that was specified in the HTML form'

		),

		'checkAllError' => array(

			'rule' => array('phpUploadError'),

			'message' => 'Can\'t upload'

		)

	)

);

</code></pre>

Validation options:

You can pass additional options to validation rules:

* *allowEmpty* - if set to _false_ will cause validation to fail if the file is not present. This option is not available for _attachmentPresence_ rule.

The example below return true if there is no upload files or jpeg.

<pre><code>var $validate = array(

	'avatar' => array(

		'rule' => array('attachmentContentType', 'image/jpeg'),

		'message' => 'Only jpegs please',

		'allowEmpty' => true

	)

);

</code></pre>

h4. You can change the path where the files are saved

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'path' => 'your/new/path'

		)

	)

);

</code></pre>

The path string can contain special :keys that will be substituted at run time with appropriate values. Here's the list of available @:keys@ with the values they're substituted with.

* *:app* - path to your app dir

* *:webroot* - path to your app's webroot dir

* *:model* - name of the model tableized with Inflector::tableize (would be 'users' for User model)

* *:id* - ID of the record

* *:basename* - basename of the uploaded file's original name (would be 'photo' for photo.jpg)

* *:extension* - extension of the uploaded file's original name (would be 'jpg' for photo.jpg)

* *:style* - name of the thumbnail's style

* *:attachment* - pluralized name of the attachment (for example 'avatars')

* *:hash* - md5 hash of the original filename + Security.salt

Default value for path is @:webroot/upload/:model/:id/:basename_:style.:extension@.

h4. You can change the url the helper points to when displaying or linking to uploaded files

This setting accepts all the :keys mentioned above and it's default value depends on path setting. For default path it would be defaults @/upload/:model/:id/:basename_:style.:extension@.

You probably won't need to change it too often, though.

h4. You can point to default url if the uploaded file is missing

If uploading an avatar is only a option to your users, you would probably want to have some default image being displayed if no image is uploaded by a user.

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'default_url' => 'path/to/default/image'

		)

	)

);

</code></pre>

This setting accepts all the @:keys@ mentioned above, but it's not set by default which results in usual url being returned even it the file does not exist.

h4. You can choose to automatically scale down images that are wider than the <code>maxWidth</code> specified in validation.

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'resizeToMaxWidth' => true

		)

	)

);

</code></pre>

h4. JPEG Quality

The jpeg quality can be set with the <code>quality</code> setting.

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'quality' => 95

		)

	)

);

</code></pre>

h4. Alpha Channel(PNG, GIF only)

The png and gif can use alpha channel <code>alpha</code> setting.

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'alpha' => true

		)

	)

);

</code></pre>

h4. You can choose another field for an external url

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'urlField' => 'gravatar'

		)

	)

);

</code></pre>

This way the user can paste an url or choose a file from their filesystem. The url will mimick usual uploading so it will still be validated and resized.

h4. Deleting a file attached to field

<pre><code>$model->data['avatar'] = null;

	$model->save();

</code></pre>

h3. More on styles

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

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(

			'styles' => array(

				'big' => '200x200',

				'small' => '120x120',

				'thumb' => '80x80'

			)

		)

	)

);

</code></pre>

Be sure to have @:style@ key included in your path setting to differentiate file names. The original file is also saved and has 'original' as @:style@ value, so you don't need it to define it yourself.

If you want non-image files to be uploaded, define no styles at all. It does not make much sense to generate thumbnails for zip or pdf files.

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

* *100x80* - resize for best fit into these dimensions, with overlapping edges trimmed if original aspect ratio differs

* *[100x80]* - resize to fit these dimensions, with white banding if original aspect ratio differs (Michał's original resize method)

* *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

h3. More on database table structure

The only database field you need to add to your model's table is @[field]_file_name@. Replace @[field]@ with chosen name (avatar for example).

There are two optional fields you can add: @[field]_content_type@ and @[field]_file_size@. If they're present they will be populated with uploaded file's content type and size in bytes respectively.

Model can have many uploaded files at once. For example define two fields in database table: @avatar_file_name@ and @logo_file_name@. Set up behavior:

<pre><code>var $actsAs = array(

	'UploadPack.Upload' => array(

		'avatar' => array(),

		'logo' => array()

		)

	)

);

</code></pre>

h3. Using the helper

There are two methods of UploadHelper you can use:

h4. UploadHelper::uploadUrl($data, $field, $options = array())

Returns url to the uploaded file

* *$data* - record from database (would be @$user@ here)

* *$field* - name of a field, like this @Modelname.fieldname@ (would be @User.avatar@ here)

* *$options* - url options

** *'style'* - name of a thumbnail's style

** *'urlize'* - if true returned url is wrapped with @$html->url()@

h4. UploadHelper::uploadImage($data, $field, $options = array(), $htmlOptions = array())

Returns image tag pointing to uploaded file.

* *$data* - record from database (would be @$user@ here)

* *$field* - name of a field, like this @Modelname.fieldname@ (would be @User.avatar@ here)

* *$options* - url options

** *'style'* - name of a thumbnail's style

** *'urlize'* - if true returned url is wrapped with @$html->url()@

* *$htmlOptions* - array of HTML attributes passed to @$html->image()@

Assuming that you have read a user from database and it's available in @$user@ variable in view.

<pre><code><?php echo $this->Upload->uploadImage($user, 'User.avatar', array('style' => 'thumb')); ?></code></pre>

When you fetch user from database you would usually get:

<pre><code>$user = array(

	'User' => array(

		'id' => 1,

		'avatar_file_name' => 'photo.jpg'

	)

);

</code></pre>

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

<pre><code>$data = array(

	'User' => array(

		0 => array(

			'id' => 1,

			'avatar_file_name' => 'photo.jpg'

		),

		1 => array(

			'id' => 2,

			'avatar_file_name' => 'photo2.jpg'

		)

	)

);

</code></pre>

Then you should do:

<pre><code><?php echo $this->Upload->uploadImage($data['User'][0], 'User.avatar', array('style' => 'thumb')) ?></code></pre>

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

h3. Requirements

UploadPack was developed with CakePHP 1.2 RC3, so it's not guaranteed to work with previous versions. You'll need GD library if you plan to generate image thumbnails. It works OK with 2.0.34 version at least, earlier versions may work too.

h2. Plans for future

There is still something missing in UploadPack, here's what will be added soon:

* file name normalization

The plans for more distant future:

* test coverage

* allow uploads to S3

* provide a method to regenerate all thumbnails, helpful if you later decide to have different sizes of thumbnails or more styles

I you want to help implementing these features, feel free to submit your patches.

h2. Copyright

Copyright (c) 2008 Michał Szajbe (http://codetunes.com), released under the MIT license.

joe bartlett's (http://jdbartlett.com) tweaks aren't under copyright. Run free, little tweaks!

UploadPack 0.7.2

<?php

App::uses('UploadBehavior', 'UploadPack.Model/Behavior');

/**

 * This file is a part of UploadPack - a plugin that makes file uploads in CakePHP as easy as possible.

 *

 * UploadHelper

 *

 * UploadHelper provides fine access to files uploaded with UploadBehavior. It generates url for those files and can display image tags of uploaded images. For more info read UploadPack documentation.

 *

 * @author Michał Szajbe (michal.szajbe@gmail.com)

 * @link http://github.com/szajbus/uploadpack

 */

class UploadHelper extends AppHelper {

    public $helpers = array('Html');

    public function uploadImage($data, $path, $options = array(), $htmlOptions = array())

    {

        $options += array('urlize' => false);

        return $this->output($this->Html->image($this->uploadUrl($data, $path, $options), $htmlOptions));

    }

    public function uploadLink($title, $data, $field, $urlOptions = array(), $htmlOptions = array())

    {

        $urlOptions += array('style' => 'original', 'urlize' => true);

        return $this->Html->link($title, $this->uploadUrl($data, $field, $urlOptions), $htmlOptions);

    }

    public function uploadUrl($data, $field, $options = array())

    {

        $options += array('style' => 'original', 'urlize' => true);

        list($model, $field) = explode('.', $field);

        if(is_array($data))

        {

            if(isset($data[$model]))

            {

                if(isset($data[$model]['id']))

                {

                    $id = $data[$model]['id'];

                    $filename = $data[$model][$field.'_file_name'];

                }

            }

            elseif(isset($data['id']))

            {

                $id = $data['id'];

                $filename = $data[$field.'_file_name'];

            }

        }

        if(isset($id) && !empty($filename))

        {

            $settings = UploadBehavior::interpolate($model, $id, $field, $filename, $options['style'], array('webroot' => ''));

            $url = isset($settings['url']) ? $settings['url'] : $settings['path'];

        }

        else

        {

            $settings = UploadBehavior::interpolate($model, null, $field, null, $options['style'], array('webroot' => ''));

            $url = isset($settings['default_url']) ? $settings['default_url'] : null;

        }

        return $options['urlize'] ? $this->Html->url($url) : $url;

    }

    /**

     * Returns appropriate extension for given mimetype.

     *

     * @param string $mime Mimetype

     * @return void

     * @author Bjorn Post

     */

    public function extension($mimeType = null)

    {

        $knownMimeTypes = array(

            'ai' => 'application/postscript', 'bcpio' => 'application/x-bcpio', 'bin' => 'application/octet-stream',

            'ccad' => 'application/clariscad', 'cdf' => 'application/x-netcdf', 'class' => 'application/octet-stream',

            'cpio' => 'application/x-cpio', 'cpt' => 'application/mac-compactpro', 'csh' => 'application/x-csh',

            'csv' => 'application/csv', 'dcr' => 'application/x-director', 'dir' => 'application/x-director',

            'dms' => 'application/octet-stream', 'doc' => 'application/msword', 'drw' => 'application/drafting',

            'dvi' => 'application/x-dvi', 'dwg' => 'application/acad', 'dxf' => 'application/dxf', 'dxr' => 'application/x-director',

            'eps' => 'application/postscript', 'exe' => 'application/octet-stream', 'ez' => 'application/andrew-inset',

            'flv' => 'video/x-flv', 'gtar' => 'application/x-gtar', 'gz' => 'application/x-gzip',

            'bz2' => 'application/x-bzip', '7z' => 'application/x-7z-compressed', 'hdf' => 'application/x-hdf',

            'hqx' => 'application/mac-binhex40', 'ips' => 'application/x-ipscript', 'ipx' => 'application/x-ipix',

            'js' => 'application/x-javascript', 'latex' => 'application/x-latex', 'lha' => 'application/octet-stream',

            'lsp' => 'application/x-lisp', 'lzh' => 'application/octet-stream', 'man' => 'application/x-troff-man',

            'me' => 'application/x-troff-me', 'mif' => 'application/vnd.mif', 'ms' => 'application/x-troff-ms',

            'nc' => 'application/x-netcdf', 'oda' => 'application/oda', 'pdf' => 'application/pdf',

            'pgn' => 'application/x-chess-pgn', 'pot' => 'application/mspowerpoint', 'pps' => 'application/mspowerpoint',

            'ppt' => 'application/mspowerpoint', 'ppz' => 'application/mspowerpoint', 'pre' => 'application/x-freelance',

            'prt' => 'application/pro_eng', 'ps' => 'application/postscript', 'roff' => 'application/x-troff',

            'scm' => 'application/x-lotusscreencam', 'set' => 'application/set', 'sh' => 'application/x-sh',

            'shar' => 'application/x-shar', 'sit' => 'application/x-stuffit', 'skd' => 'application/x-koan',

            'skm' => 'application/x-koan', 'skp' => 'application/x-koan', 'skt' => 'application/x-koan',

            'smi' => 'application/smil', 'smil' => 'application/smil', 'sol' => 'application/solids',

            'spl' => 'application/x-futuresplash', 'src' => 'application/x-wais-source', 'step' => 'application/STEP',

            'stl' => 'application/SLA', 'stp' => 'application/STEP', 'sv4cpio' => 'application/x-sv4cpio',

            'sv4crc' => 'application/x-sv4crc', 'svg' => 'image/svg+xml', 'svgz' => 'image/svg+xml',

            'swf' => 'application/x-shockwave-flash', 't' => 'application/x-troff',

            'tar' => 'application/x-tar', 'tcl' => 'application/x-tcl', 'tex' => 'application/x-tex',

            'texi' => 'application/x-texinfo', 'texinfo' => 'application/x-texinfo', 'tr' => 'application/x-troff',

            'tsp' => 'application/dsptype', 'unv' => 'application/i-deas', 'ustar' => 'application/x-ustar',

            'vcd' => 'application/x-cdlink', 'vda' => 'application/vda', 'xlc' => 'application/vnd.ms-excel',

            'xll' => 'application/vnd.ms-excel', 'xlm' => 'application/vnd.ms-excel', 'xls' => 'application/vnd.ms-excel',

            'xlw' => 'application/vnd.ms-excel', 'zip' => 'application/zip', 'aif' => 'audio/x-aiff', 'aifc' => 'audio/x-aiff',

            'aiff' => 'audio/x-aiff', 'au' => 'audio/basic', 'kar' => 'audio/midi', 'mid' => 'audio/midi',

            'midi' => 'audio/midi', 'mp2' => 'audio/mpeg', 'mp3' => 'audio/mpeg', 'mpga' => 'audio/mpeg',

            'ra' => 'audio/x-realaudio', 'ram' => 'audio/x-pn-realaudio', 'rm' => 'audio/x-pn-realaudio',

            'rpm' => 'audio/x-pn-realaudio-plugin', 'snd' => 'audio/basic', 'tsi' => 'audio/TSP-audio', 'wav' => 'audio/x-wav',

            'asc' => 'text/plain', 'c' => 'text/plain', 'cc' => 'text/plain', 'css' => 'text/css', 'etx' => 'text/x-setext',

            'f' => 'text/plain', 'f90' => 'text/plain', 'h' => 'text/plain', 'hh' => 'text/plain', 'htm' => 'text/html',

            'html' => 'text/html', 'm' => 'text/plain', 'rtf' => 'text/rtf', 'rtx' => 'text/richtext', 'sgm' => 'text/sgml',

            'sgml' => 'text/sgml', 'tsv' => 'text/tab-separated-values', 'tpl' => 'text/template', 'txt' => 'text/plain',

            'xml' => 'text/xml', 'avi' => 'video/x-msvideo', 'fli' => 'video/x-fli', 'mov' => 'video/quicktime',

            'movie' => 'video/x-sgi-movie', 'mpe' => 'video/mpeg', 'mpeg' => 'video/mpeg', 'mpg' => 'video/mpeg',

            'qt' => 'video/quicktime', 'viv' => 'video/vnd.vivo', 'vivo' => 'video/vnd.vivo', 'gif' => 'image/gif',

            'ief' => 'image/ief', 'jpe' => 'image/jpeg', 'jpeg' => 'image/jpeg', 'jpg' => 'image/jpeg',

            'pbm' => 'image/x-portable-bitmap', 'pgm' => 'image/x-portable-graymap', 'png' => 'image/png',

            'pnm' => 'image/x-portable-anymap', 'ppm' => 'image/x-portable-pixmap', 'ras' => 'image/cmu-raster',

            'rgb' => 'image/x-rgb', 'tif' => 'image/tiff', 'tiff' => 'image/tiff', 'xbm' => 'image/x-xbitmap',

            'xpm' => 'image/x-xpixmap', 'xwd' => 'image/x-xwindowdump', 'ice' => 'x-conference/x-cooltalk',

            'iges' => 'model/iges', 'igs' => 'model/iges', 'mesh' => 'model/mesh', 'msh' => 'model/mesh',

            'silo' => 'model/mesh', 'vrml' => 'model/vrml', 'wrl' => 'model/vrml',

            'mime' => 'www/mime', 'pdb' => 'chemical/x-pdb', 'xyz' => 'chemical/x-pdb'

        );

        return array_search($mimeType, $knownMimeTypes);

    }

}

{

    "name": "szajbus/uploadpack",

    "description": "Easy way to handle file uploads in CakePHP",

    "version": "0.7.2",

    "type": "library",

    "keywords": ["upload", "cakephp", "image processing"],

    "homepage": "https://github.com/szajbus/uploadpack",

    "license": "MIT",

    "authors": [

        {

            "name": "Michał Szajbe",

            "email": "michal.szajbe@gmail.com"

        }

    ],

    "support": {

        "issues": "https://github.com/szajbus/uploadpack/issues",

        "source": "https://github.com/szajbus/uploadpack"

    },

    "require": {

        "cakephp/cakephp": ">=1.2"

    },

    "require-dev": {

        "phpunit/phpunit": "*",

        "cakephp/cakephp-codesniffer": "dev-master"

    }

}

Copyright (c) 2010 Michał Szajbe

Permission is hereby granted, free of charge, to any person

obtaining a copy of this software and associated documentation

files (the "Software"), to deal in the Software without

restriction, including without limitation the rights to use,

copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the

Software is furnished to do so, subject to the following

conditions:

The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES

OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT

HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,

WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR

OTHER DEALINGS IN THE SOFTWARE.