The Process¶

Uploading a file involves the following general process:

• An upload form is displayed, allowing a user to select a file and upload it.
• When the form is submitted, the file is uploaded to the destination you specify.
• Along the way, the file is validated to make sure it is allowed to be uploaded based on the preferences you set.
• Once uploaded, the user will be shown a success message.

To demonstrate this process here is brief tutorial. Afterward you’ll find reference information.

    <?php echo $error;?>
    <?php echo form_open_multipart('upload/do_upload');?>
<input type="file" name="userfile" size="20" />
<br /><br />
<input type="submit" value="upload" />
    </form>

<h3>Your file was successfully uploaded!</h3>

<ul>
<?php foreach ($upload_data as $item => $value):?>
<li><?php echo $item;?>: <?php echo $value;?></li>
<?php endforeach; ?>
</ul>

<p><?php echo anchor('upload', 'Upload Another File!'); ?></p>

public function index()
{
        ee()->load->view('upload_form', array('error' => ' ' ));
}

        public function do_upload()
        {
                $config['upload_path']   = './uploads/';
                $config['allowed_types'] = 'gif|jpg|png';
                $config['max_size']      = 100;
                $config['max_width']     = 1024;
                $config['max_height']    = 768;

                ee()->load->library('upload', $config);

                if ( ! ee()->upload->do_upload())
                {
                        $error = array('error' => ee()->upload->display_errors());

                        ee()->load->view('upload_form', $error);
                }
                else
                {
                        $data = array('upload_data' => ee()->upload->data());

                        ee()->load->view('upload_success', $data);
                }
        }
}

Reference Guide¶

ee()->load->library('upload');

$config['upload_path'] = './uploads/';
$config['allowed_types'] = 'gif|jpg|png';
$config['max_size']     = '100';
$config['max_width'] = '1024';
$config['max_height'] = '768';

ee()->load->library('upload', $config);

// Alternately you can set preferences by calling the ``initialize()`` method. Useful if you auto-load the class:
ee()->upload->initialize($config);

Class Reference¶

class EE_Upload¶

EE_Upload::initialize([array $config = array()[, $reset = TRUE]])¶

Parameters:	$config (array) – Preferences $reset (bool) – Whether to reset preferences (that are not provided in $config) to their defaults
Returns:	EE_Upload instance (method chaining)
Return type:	EE_Upload

EE_Upload::do_upload([$field = 'userfile'])¶

Parameters:	$field (string) – Name of the form field
Returns:	TRUE on success, FALSE on failure
Return type:	bool

Performs the upload based on the preferences you’ve set.

Note

By default the upload routine expects the file to come from a form field called userfile, and the form must be of type multipart.

<form method="post" action="some_action" enctype="multipart/form-data" />

If you would like to set your own field name simply pass its value to the do_upload() method:

$field_name = "some_field_name";
ee()->upload->do_upload($field_name);

EE_Upload::display_errors([$open = '<p>'[, $close = '</p>']])¶

Parameters:	$open (string) – Opening markup $close (string) – Closing markup
Returns:	Formatted error message(s)
Return type:	string

Retrieves any error messages if the do_upload() method returned false. The method does not echo automatically, it returns the data so you can assign it however you need.

Formatting Errors

By default the above method wraps any errors within <p> tags. You can set your own delimiters like this:

ee()->upload->display_errors('<p>', '</p>');

EE_Upload::data([$index = NULL])¶

Parameters:	$data (string) – Element to return instead of the full array
Returns:	Information about the uploaded file
Return type:	mixed

This is a helper method that returns an array containing all of the data related to the file you uploaded. Here is the array prototype:

Array
(
        [file_name]     => mypic.jpg
        [file_type]     => image/jpeg
        [file_path]     => /path/to/your/upload/
        [full_path]     => /path/to/your/upload/jpg.jpg
        [raw_name]      => mypic
        [orig_name]     => mypic.jpg
        [client_name]   => mypic.jpg
        [file_ext]      => .jpg
        [file_size]     => 22.2
        [is_image]      => 1
        [image_width]   => 800
        [image_height]  => 600
        [image_type]    => jpeg
        [image_size_str] => width="800" height="200"
)

To return one element from the array:

ee()->upload->data('file_name');        // Returns: mypic.jpg

Here’s a table explaining the above-displayed array items:

Item	Description
file_name	Name of the file that was uploaded, including the filename extension
file_type	File MIME type identifier
file_path	Absolute server path to the file
full_path	Absolute server path, including the file name
raw_name	File name, without the extension
orig_name	)riginal file name. This is only useful if you use the encrypted name option.
client_name	File name as supplied by the client user agent, prior to any file name preparation or incrementing
file_ext	Filename extension, period included
file_size	File size in kilobytes
is_image	Whether the file is an image or not. 1 = image. 0 = not.
image_width	Image width
image_height	Image height
image_type	Image type (usually the file name extension without the period)
image_size_str	A string containing the width and height (useful to put into an image tag)