^Status|stub|
^Todo|Write me|

====== Upload Helper ======

The upload helper is designed to work with the global $_FILES array and validation library.  [[http://us.php.net/manual/en/features.file-upload.php|More information about PHP file uploads]].

===== Configuration =====

Configuration is done in the ''application/config/upload.php'' file, if it's not there take the one from ''system/config'' and copy it to the application folder (see [[http://docs.kohanaphp.com/general/filesystem#cascading|cascading filesystem]]):

<code php>
$config['directory'] = DOCROOT.'upload';
	
$config['create_directories'] = FALSE;

$config['remove_spaces'] = TRUE;
</code>

=== Upload directory ===

''$config['directory']'' sets the path to the saved files. This path is relative to your index file. Absolute paths are also supported.

=== Directory creation ===

''$config['create_directories']'' enable or disable directory creation.

=== Remove spaces ===

''$config['remove_spaces']'' removes spaces from uploaded filenames.
===== Complete example =====

The example below demonstrates how to validate a file upload (where the field name is `picture`), save it temporarily and apply some image manipulation. 
<code php>
$files = Validation::factory($_FILES)
	->add_rules('picture', 'upload::valid', 'upload::required', 'upload::type[gif,jpg,png]', 'upload::size[1M]');

if ($files->validate())
{
	// Temporary file name
	$filename = upload::save('picture');

	// Resize, sharpen, and save the image
	Image::factory($filename)
		->resize(100, 100, Image::WIDTH)
		->save(DOCROOT.'media/pictures/'.basename($filename));

	// Remove the temporary file
	unlink($filename);
}
</code>

The example below demonstrates how to upload several images
<code php>
   foreach( arr::rotate($_FILES['image']) as $file )
   {
	$filename = upload::save($file);

	Image::factory($filename)
		->resize(30, 30, Image::AUTO)
		->save(DOCROOT.'upload/'.basename($filename));
        unlink($filename);
    }
</code>

===== Methods =====

==== save() ====

''save($file, $filename = NULL, $directory = NULL, $chmod = 0644)'' saves an uploaded file to a new location. It takes:

  * **[mixed]** ''$file'' name of $_FILE input or array of upload data
  * **[string]** ''$filename'' new filename, if omitted use the default filename, with a timestamp pre-pended
  * **[string]** ''$directory '' new directory, if omitted uses the pre-configured upload directory
  * **[integer]** ''$chmod '' chmod mask, default 0644
  * returns **[string]** full path to the new file

==== valid() ====

''valid($file)'' tests if input data is valid file type, even if no upload is present.

  * **[array]** ''$file'' $_FILES items
  * returns **[bool]** TRUE if data is valid, FALSE otherwise

==== required() ====

''required(array $file)'' tests if input data has valid upload data.

  * **[array]** ''$file'' $_FILES items
  * returns **[bool]** TRUE if input data has valid upload data, FALSE otherwise


==== type() ====

''type(array $file, array $allowed_types)'' tests if an uploaded file is allowed by extension.

  * **[array]** ''$file'' $_FILES items
  * **[array]** ''$allowed_types'' allowed file extensions
  * returns **[bool]** TRUE if the uploaded file has an allowed extension, FALSE otherwise

==== size() ====

''size(array $file, array $size)'' tests if an uploaded file is allowed by file size. File sizes are defined as: SB, where S is the size (1, 15, 300, etc) and B is the byte modifier: (B)ytes, (K)ilobytes, (M)egabytes, (G)igabytes. __Eg__: to limit the size to 1MB or less, you would use "1M".

  * **[array]** ''$file'' $_FILES items
  * **[array]** ''$size'' maximum file size
  * returns **[bool]** TRUE if the uploaded file size is lesser that maximum allowed, FALSE otherwise