356 lines
14 KiB
ReStructuredText
356 lines
14 KiB
ReStructuredText
####################
|
|
File Uploading Class
|
|
####################
|
|
|
|
CodeIgniter's File Uploading Class permits files to be uploaded. You can
|
|
set various preferences, restricting the type and size of the files.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. raw:: html
|
|
|
|
<div class="custom-index container"></div>
|
|
|
|
***********
|
|
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.
|
|
|
|
Creating the Upload Form
|
|
========================
|
|
|
|
Using a text editor, create a form called upload_form.php. In it, place
|
|
this code and save it to your **application/views/** directory::
|
|
|
|
<html>
|
|
<head>
|
|
<title>Upload Form</title>
|
|
</head>
|
|
<body>
|
|
|
|
<?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>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
You'll notice we are using a form helper to create the opening form tag.
|
|
File uploads require a multipart form, so the helper creates the proper
|
|
syntax for you. You'll also notice we have an $error variable. This is
|
|
so we can show error messages in the event the user does something
|
|
wrong.
|
|
|
|
The Success Page
|
|
================
|
|
|
|
Using a text editor, create a form called upload_success.php. In it,
|
|
place this code and save it to your **application/views/** directory::
|
|
|
|
<html>
|
|
<head>
|
|
<title>Upload Form</title>
|
|
</head>
|
|
<body>
|
|
|
|
<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>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
The Controller
|
|
==============
|
|
|
|
Using a text editor, create a controller called Upload.php. In it, place
|
|
this code and save it to your **application/controllers/** directory::
|
|
|
|
<?php
|
|
|
|
class Upload extends CI_Controller {
|
|
|
|
public function __construct()
|
|
{
|
|
parent::__construct();
|
|
$this->load->helper(array('form', 'url'));
|
|
}
|
|
|
|
public function index()
|
|
{
|
|
$this->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;
|
|
|
|
$this->load->library('upload', $config);
|
|
|
|
if ( ! $this->upload->do_upload('userfile'))
|
|
{
|
|
$error = array('error' => $this->upload->display_errors());
|
|
|
|
$this->load->view('upload_form', $error);
|
|
}
|
|
else
|
|
{
|
|
$data = array('upload_data' => $this->upload->data());
|
|
|
|
$this->load->view('upload_success', $data);
|
|
}
|
|
}
|
|
}
|
|
?>
|
|
|
|
The Upload Directory
|
|
====================
|
|
|
|
You'll need a destination directory for your uploaded images. Create a
|
|
directory at the root of your CodeIgniter installation called uploads
|
|
and set its file permissions to 777.
|
|
|
|
Try it!
|
|
=======
|
|
|
|
To try your form, visit your site using a URL similar to this one::
|
|
|
|
example.com/index.php/upload/
|
|
|
|
You should see an upload form. Try uploading an image file (either a
|
|
jpg, gif, or png). If the path in your controller is correct it should
|
|
work.
|
|
|
|
***************
|
|
Reference Guide
|
|
***************
|
|
|
|
Initializing the Upload Class
|
|
=============================
|
|
|
|
Like most other classes in CodeIgniter, the Upload class is initialized
|
|
in your controller using the ``$this->load->library()`` method::
|
|
|
|
$this->load->library('upload');
|
|
|
|
Once the Upload class is loaded, the object will be available using:
|
|
$this->upload
|
|
|
|
Setting Preferences
|
|
===================
|
|
|
|
Similar to other libraries, you'll control what is allowed to be upload
|
|
based on your preferences. In the controller you built above you set the
|
|
following preferences::
|
|
|
|
$config['upload_path'] = './uploads/';
|
|
$config['allowed_types'] = 'gif|jpg|png';
|
|
$config['max_size'] = '100';
|
|
$config['max_width'] = '1024';
|
|
$config['max_height'] = '768';
|
|
|
|
$this->load->library('upload', $config);
|
|
|
|
// Alternately you can set preferences by calling the ``initialize()`` method. Useful if you auto-load the class:
|
|
$this->upload->initialize($config);
|
|
|
|
The above preferences should be fairly self-explanatory. Below is a
|
|
table describing all available preferences.
|
|
|
|
Preferences
|
|
===========
|
|
|
|
The following preferences are available. The default value indicates
|
|
what will be used if you do not specify that preference.
|
|
|
|
============================ ================= ======================= ======================================================================
|
|
Preference Default Value Options Description
|
|
============================ ================= ======================= ======================================================================
|
|
**upload_path** None None The path to the directory where the upload should be placed. The
|
|
directory must be writable and the path can be absolute or relative.
|
|
**allowed_types** None None The mime types corresponding to the types of files you allow to be
|
|
uploaded. Usually the file extension can be used as the mime type.
|
|
Can be either an array or a pipe-separated string.
|
|
**file_name** None Desired file name If set CodeIgniter will rename the uploaded file to this name. The
|
|
extension provided in the file name must also be an allowed file type.
|
|
If no extension is provided in the original file_name will be used.
|
|
**file_ext_tolower** FALSE TRUE/FALSE (boolean) If set to TRUE, the file extension will be forced to lower case
|
|
**overwrite** FALSE TRUE/FALSE (boolean) If set to true, if a file with the same name as the one you are
|
|
uploading exists, it will be overwritten. If set to false, a number will
|
|
be appended to the filename if another with the same name exists.
|
|
**max_size** 0 None The maximum size (in kilobytes) that the file can be. Set to zero for no
|
|
limit. Note: Most PHP installations have their own limit, as specified
|
|
in the php.ini file. Usually 2 MB (or 2048 KB) by default.
|
|
**max_width** 0 None The maximum width (in pixels) that the image can be. Set to zero for no
|
|
limit.
|
|
**max_height** 0 None The maximum height (in pixels) that the image can be. Set to zero for no
|
|
limit.
|
|
**min_width** 0 None The minimum width (in pixels) that the image can be. Set to zero for no
|
|
limit.
|
|
**min_height** 0 None The minimum height (in pixels) that the image can be. Set to zero for no
|
|
limit.
|
|
**max_filename** 0 None The maximum length that a file name can be. Set to zero for no limit.
|
|
**max_filename_increment** 100 None When overwrite is set to FALSE, use this to set the maximum filename
|
|
increment for CodeIgniter to append to the filename.
|
|
**encrypt_name** FALSE TRUE/FALSE (boolean) If set to TRUE the file name will be converted to a random encrypted
|
|
string. This can be useful if you would like the file saved with a name
|
|
that can not be discerned by the person uploading it.
|
|
**remove_spaces** TRUE TRUE/FALSE (boolean) If set to TRUE, any spaces in the file name will be converted to
|
|
underscores. This is recommended.
|
|
**detect_mime** TRUE TRUE/FALSE (boolean) If set to TRUE, a server side detection of the file type will be
|
|
performed to avoid code injection attacks. DO NOT disable this option
|
|
unless you have no other option as that would cause a security risk.
|
|
**mod_mime_fix** TRUE TRUE/FALSE (boolean) If set to TRUE, multiple filename extensions will be suffixed with an
|
|
underscore in order to avoid triggering `Apache mod_mime
|
|
<http://httpd.apache.org/docs/2.0/mod/mod_mime.html#multipleext>`_.
|
|
DO NOT turn off this option if your upload directory is public, as this
|
|
is a security risk.
|
|
============================ ================= ======================= ======================================================================
|
|
|
|
Setting preferences in a config file
|
|
====================================
|
|
|
|
If you prefer not to set preferences using the above method, you can
|
|
instead put them into a config file. Simply create a new file called the
|
|
upload.php, add the $config array in that file. Then save the file in:
|
|
**config/upload.php** and it will be used automatically. You will NOT
|
|
need to use the ``$this->upload->initialize()`` method if you save your
|
|
preferences in a config file.
|
|
|
|
***************
|
|
Class Reference
|
|
***************
|
|
|
|
.. php:class:: CI_Upload
|
|
|
|
.. php:method:: initialize([array $config = array()[, $reset = TRUE]])
|
|
|
|
:param array $config: Preferences
|
|
:param bool $reset: Whether to reset preferences (that are not provided in $config) to their defaults
|
|
:returns: CI_Upload instance (method chaining)
|
|
:rtype: CI_Upload
|
|
|
|
.. php:method:: do_upload([$field = 'userfile'])
|
|
|
|
:param string $field: Name of the form field
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: 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";
|
|
$this->upload->do_upload($field_name);
|
|
|
|
.. php:method:: display_errors([$open = '<p>'[, $close = '</p>']])
|
|
|
|
:param string $open: Opening markup
|
|
:param string $close: Closing markup
|
|
:returns: Formatted error message(s)
|
|
:rtype: 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::
|
|
|
|
$this->upload->display_errors('<p>', '</p>');
|
|
|
|
|
|
.. php:method:: data([$index = NULL])
|
|
|
|
:param string $data: Element to return instead of the full array
|
|
:returns: Information about the uploaded file
|
|
:rtype: 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::
|
|
|
|
$this->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 Original 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)
|
|
================ ====================================================================================================
|