FuelPHP, a PHP 5.3 Framework Documentation

is_valid()

The is_valid method can be used to check if there are any uploaded files present that have passed the upload validation.

// do we have any uploaded files to save?
if (Upload::is_valid())
{
	Upload::save();
}

get_files($index = null)

The get_files method returns a multi-dimensional array with all files uploaded that have an error value of false.

// get the list of successfully uploaded files
foreach(Upload::get_files() as $file)
{
	// do something with the file info
}

// get the first uploaded file by index
if ( ! Upload::get_files(0))
{
	// first uploaded file was not succesfully uploaded
}

get_errors($index = null)

The get_errors method returns a multi-dimensional array with all files uploaded that have an error status of true.

// get the list of uploaded files with errors
foreach(Upload::get_errors() as $file)
{
	// do something with the file info
}

// get the first uploaded file by field name
if (Upload::get_errors('new_image'))
{
	// there was an error uploading the file for the form field 'new_image'
	// defined as <input type="file" name="new_image" />
}

Note that all upload fields in your form are submitted, even if they are optional. For fields that are left empty, the uploaded files array will have an empty file entry, with an error code of Upload::UPLOAD_ERR_NO_FILE. When processing errors, check the error code first, before trying to use any of the other fields in the returned array.

register($event, $callback)

The register method allows you to register callbacks for specific upload events, and allow you to add your own code to the process() and save() methods.

// register a before callback using a closure
Upload::register('before', function (&$file) {
	if ($file['error'] == Upload::UPLOAD_ERR_OK)
	{
		switch($file['extension'])
		{
			case "jpg":
			case "png":
			case "gif":
				// store these in the images subdirectory
				$file['file'] .= 'images/';
			break;

			case "css":
				// store these in the css subdirectory
				$file['file'] .= 'css/';
			break;

			case "js":
				// store these in the javascript subdirectory
				$file['file'] .= 'js/';
			break;

			default:
				// don't modify the path for all others
		}
	}
});

If you want to use a 'validate' callback, be sure to register it before you call Upload::process(). If you have used the 'auto_process' configuration setting, Upload::process() will be called as soon as you use the Upload class, which means you can't use this setting if you want to define callbacks at runtime.

The callback will receive a FuelPHP\Upload\File object as parameter. The entry is passed by reference, which allows the callback function to modify the entries of the array. You can access it as an array for backward compatibility reasons, but if migrate your application a version < 1.6 to 1.6+, check the value passed to your callbacks, as not all attributes are named the same as in pre-1.6.
If the callback function returns an integer, it is assumed to be an update of the uploaded file's error code. All other return values are ignored.

Note: if you alter the contents of the $file array in your callback, you have to make sure that the information is still valid, as the Upload class won't perform its checks again. The only exception to this rule is the 'file' path, which will be checked and created if required after the callback has been executed.

process($config = array())

The process method processes the information about all uploaded files, normalizes the different permutations of form field names that can be used, fetches additional information about the file and its mimetype, and validates the file.

// process the uploaded files
// set the max size to 10Kb, and allow overwrites of duplicate files
Upload::process(array(
	'max_size'    => 10240,
	'auto_rename' => false,
	'overwrite'   => true
));

If you intend to use this method, disable auto_process in the config, to avoid processing the uploaded files twice!

save( ... )

The save method saves all validated files uploaded to the path specified.

// save all validated files
Upload::save();

// save only the first uploaded file
Upload::save(0);

// save the first, second and fourth uploaded file
Upload::save(0, 1, 3);

// save all validated files, and to an alternate location
$arr = Upload::get_files();
Upload::save(DOCROOT.'assets', array_keys($arr));

// process any errors on these files
foreach (Upload::get_errors() as $key => $file)
{
	// process the errors here
}