About this plugin

This plugin simply allows you to handle the POST upload process for a file input. It will upload files and place them in a path you specify, but any tracking of the files after it is uploaded is your responsibility. This plugin is just meant to provide a somewhat flexible way to validate and upload a file.

Installation

As a plugin

1. Download, unzip and move 'ifupload' folder into your Cotonti plugin directory
2. Install plugin through the administration panel and make sure configurations are to your preference

As a standalone

1. Download and move and or rename inc/ifupload.functions.php and place into any folder
2. Add the language strings from lang/ into your extension language files
3. Include from your extension

Example Usage

This is an example for adding an image to a page with a custom page database column.

Step 1

Add any amount of file input fields into page.add.tpl. Currently file array inputs are NOT supported (e.g. test_upload[]). You can have multiple file inputs with different names.

<input type="file" name="test_upload" />

Step 2

Add a file handler where ever you complete a POST operation.

In this example, it is in a hook into page.add.add.error. This hook is just before adding the page into the database, but after page data validation.

Example 1

This example has the ifupload_file_handle function send errors through cot_error. In most circumstances, this is a tolerable method. In some circumstances, calling cot_error, depending where you are hooking at, will halt a process from continuing. To handle errors on your own, see example 2.

if(!cot_error_found())
{
	require_once cot_incfile('ifupload', 'plug');

	$rtestupload = ifupload_file_handle('test_upload');
	if($rtestupload['success'])
	{
		// The file was successfully uploaded
		// Where this hook is at in this example, this will add the column to the page insert query
		$rpage['page_custom_image'] = $rtestupload['file']['upload_path'];
	}
	else
	{
		// Add this if you are requiring the upload
		if(empty($rtestupload['errors']))
		{
			cot_error('You must select an upload');
		}
	}
}

Example 2

This example shows how to handle your own errors. In some cases you won't want to send some error messages to the user or effect your POST processing by triggering cot_error_found with cot_error.

if(!cot_error_found())
{
	require_once cot_incfile('ifupload', 'plug');

	$rtestupload = ifupload_file_handle('test_upload',
		array(
			'use_cot_error' => false,
		)
	);

	if($rtestupload['success'])
	{
		$rpage['page_custom_page_image'] = $rtestupload['file']['upload_path'];
	}
	else
	{
		// handle what errors to send to the user based on the error codes returned
		if(!empty($rtestupload['error_codes']))
		{
			foreach($rtestupload['error_codes'] as $error_code)
			{
				// Only send error messages with the code 1 or 2 to the user. The others will be suppressed.
				switch($error_code)
				{
					case 1:
					case 2:
						// Of course you would avoid cot_error() if you didn't want to trigger cot_found_error()
						cot_error($rtestupload['errors'][$error_code]);
					break;
				}
			}
		}
	}
}

Available Functions

ifupload_file_handle( $name, [array $options] )

Handles the POST upload process for a file input.

• $name: (string) The input name for the file to handle

• $options: (array) optional, Overwrite the default options

  Options

  Property	Default	Description
  use_cot_error	true	Have any file upload errors sent to cot_error.
  use_safename	true	Use `cot_safename` from the upload API
  file_name		Rename the file to the value set here if not empty
  use_file_check	true	Use `cot_file_check` from the upload API
  upload_path	Value of `$cfg['plugin']['ifupload']['path']`	The path to move the uploaded file to.
  custom_validator	false	Put the name of the callback you wish to use instead of the default file validator.
  check_file_exists	true	Check to see if the file name already exists. If the file does exist and this is property is true, the file will return a 'File already exists' error.
  special		Place a indentifier string you wish to append to a file. Nothing will be added if empty.
  valid_extensions	Value of $cfg['plugin']['ifupload']['exts']	An array of valid extensions (without ".") to accept. If a file's extension isn't in this list, it will return a 'Invalid file extension error'
  max_size		Set in bytes. If set other than empty, send an error on upload if the file size is too big. Empty is no limit.

• return: (array) See "Return examples" for further details

ifupload_file_remove($path)

Delete file from the upload path

• $path: (string) The file path
• return: (boolean) Removal completed

Return examples

Example of what ifupload_file_handle would return when successful or not

Successful

$rtestupload = ifupload_file_handle('test_upload');

// The above would return this if successful
return array(
	'success' => true,
	'file' => 
		array(
			'name' => 'uploadedfile.jpg',
			'size' => 648775,
			'tmp_name' => '/tmp/php8B9E.tmp',
			'error' => 0,
			'path' => 'static/',
			'upload_path' => 'static/uploadedfile.jpg'
		)
);

Not Successful

$rtestupload = ifupload_file_handle('test_upload');

// The above would return something like this if not successful
return array(
	'success' => false,
	'errors' => array(
		1 => 'Invalid file input',
		2 => 'Invalid file extension'
	),
	'error_codes' => array(
		0 => 1,
		1 => 2
	)
	'error_messages' => array(
		0 => 'Invalid file input',
		1 => 'Invalid file extension'
	)
);

Errors

Error codes and messages

Code	Constant	Message	Explanation
1	IFU_ECODE_FILE_NAME	Invalid file input	The file failed validation because it was empty, sizes didn't match or wasn't actually an uploaded file.
2	IFU_ECODE_FILE_EXT	Invalid file extension	The file failed validation because the file extension was not in the valid_extensions list
3	IFU_ECODE_FILE_CHECK	Invalid file	File failed validation because the file failed cot_check_file() if it was set in options
4	IFU_ECODE_FILE_EXISTS	File name already exists	File failed validation because the file name already exists
5	IFU_ECODE_FILE_ERROR	File failed to upload	The file failed to upload and this was trigger by $_FILES[$name]['error'] !== 0
5	IFU_ECODE_FILE_SIZE	File size is too big	File failed validation because the size of the file was being that max_size option