Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / fd5d918362d21fe7fe47a4e1b2607eec67a58a5c / . / user_guide_src / source / libraries / file_uploading.rst
blob: c7965ae11861391cd838d8556c3a8935568fd643 [file] [log] [blame]
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]1####################
2File Uploading Class
3####################
4
5CodeIgniter's File Uploading Class permits files to be uploaded. You can
6set various preferences, restricting the type and size of the files.
7
8***********
9The Process
10***********
11
12Uploading a file involves the following general process:
13
14- An upload form is displayed, allowing a user to select a file and
15 upload it.
16- When the form is submitted, the file is uploaded to the destination
17 you specify.
18- Along the way, the file is validated to make sure it is allowed to be
19 uploaded based on the preferences you set.
20- Once uploaded, the user will be shown a success message.
21
22To demonstrate this process here is brief tutorial. Afterward you'll
23find reference information.
24
25Creating the Upload Form
26========================
27
28Using a text editor, create a form called upload_form.php. In it, place
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]29this code and save it to your **application/views/** directory::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]30
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]31 <html>
32 <head>
33 <title>Upload Form</title>
34 </head>
35 <body>
36
37 <?php echo $error;?>
38
39 <?php echo form_open_multipart('upload/do_upload');?>
40
41 <input type="file" name="userfile" size="20" />
42
43 <br /><br />
44
45 <input type="submit" value="upload" />
46
47 </form>
48
49 </body>
50 </html>
51
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]52You'll notice we are using a form helper to create the opening form tag.
53File uploads require a multipart form, so the helper creates the proper
54syntax for you. You'll also notice we have an $error variable. This is
55so we can show error messages in the event the user does something
56wrong.
57
58The Success Page
59================
60
61Using a text editor, create a form called upload_success.php. In it,
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]62place this code and save it to your **application/views/** directory::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]63
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]64 <html>
65 <head>
66 <title>Upload Form</title>
67 </head>
68 <body>
69
70 <h3>Your file was successfully uploaded!</h3>
71
72 <ul>
73 <?php foreach ($upload_data as $item => $value):?>
74 <li><?php echo $item;?>: <?php echo $value;?></li>
75 <?php endforeach; ?>
76 </ul>
77
78 <p><?php echo anchor('upload', 'Upload Another File!'); ?></p>
79
80 </body>
81 </html>
82
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]83The Controller
84==============
85
86Using a text editor, create a controller called upload.php. In it, place
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]87this code and save it to your **application/controllers/** directory::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]88
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]89 <?php
90
91 class Upload extends CI_Controller {
92
Andrey Andreevd8e1ac72012-03-26 22:22:37 +0300[diff] [blame]93 public function __construct()
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]94 {
95 parent::__construct();
96 $this->load->helper(array('form', 'url'));
97 }
98
Andrey Andreevd8e1ac72012-03-26 22:22:37 +0300[diff] [blame]99 public function index()
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]100 {
101 $this->load->view('upload_form', array('error' => ' ' ));
102 }
103
Andrey Andreevd8e1ac72012-03-26 22:22:37 +0300[diff] [blame]104 public function do_upload()
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]105 {
Andrey Andreevd8e1ac72012-03-26 22:22:37 +0300[diff] [blame]106 $config['upload_path'] = './uploads/';
107 $config['allowed_types'] = 'gif|jpg|png';
108 $config['max_size'] = 100;
109 $config['max_width'] = 1024;
110 $config['max_height'] = 768;
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]111
112 $this->load->library('upload', $config);
113
114 if ( ! $this->upload->do_upload())
115 {
116 $error = array('error' => $this->upload->display_errors());
117
118 $this->load->view('upload_form', $error);
119 }
120 else
121 {
122 $data = array('upload_data' => $this->upload->data());
123
124 $this->load->view('upload_success', $data);
125 }
126 }
127 }
128 ?>
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]129
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]130The Upload Directory
131====================
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]132
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]133You'll need a destination directory for your uploaded images. Create a
134directory at the root of your CodeIgniter installation called uploads
135and set its file permissions to 777.
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]136
137Try it!
138=======
139
140To try your form, visit your site using a URL similar to this one::
141
142 example.com/index.php/upload/
143
144You should see an upload form. Try uploading an image file (either a
145jpg, gif, or png). If the path in your controller is correct it should
146work.
147
148***************
149Reference Guide
150***************
151
152Initializing the Upload Class
153=============================
154
155Like most other classes in CodeIgniter, the Upload class is initialized
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]156in your controller using the ``$this->load->library()`` method::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]157
158 $this->load->library('upload');
159
160Once the Upload class is loaded, the object will be available using:
161$this->upload
162
163Setting Preferences
164===================
165
166Similar to other libraries, you'll control what is allowed to be upload
167based on your preferences. In the controller you built above you set the
168following preferences::
169
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]170 $config['upload_path'] = './uploads/';
171 $config['allowed_types'] = 'gif|jpg|png';
172 $config['max_size'] = '100';
173 $config['max_width'] = '1024';
174 $config['max_height'] = '768';
175
176 $this->load->library('upload', $config);
177
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]178 // Alternately you can set preferences by calling the ``initialize()`` method. Useful if you auto-load the class:
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]179 $this->upload->initialize($config);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]180
181The above preferences should be fairly self-explanatory. Below is a
182table describing all available preferences.
183
184Preferences
185===========
186
187The following preferences are available. The default value indicates
188what will be used if you do not specify that preference.
189
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]190============================ ================= ======================= ======================================================================
191Preference Default Value Options Description
192============================ ================= ======================= ======================================================================
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]193**upload_path** None None The path to the directory where the upload should be placed. The
194 directory must be writable and the path can be absolute or relative.
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]195**allowed_types** None None The mime types corresponding to the types of files you allow to be
196 uploaded. Usually the file extension can be used as the mime type.
197 Separate multiple types with a pipe.
198**file_name** None Desired file name If set CodeIgniter will rename the uploaded file to this name. The
199 extension provided in the file name must also be an allowed file type.
Andrey Andreev6123b612012-10-05 15:54:43 +0300[diff] [blame]200 If no extension is provided in the original file_name will be used.
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]201**overwrite** FALSE TRUE/FALSE (boolean) If set to true, if a file with the same name as the one you are
202 uploading exists, it will be overwritten. If set to false, a number will
203 be appended to the filename if another with the same name exists.
204**max_size** 0 None The maximum size (in kilobytes) that the file can be. Set to zero for no
205 limit. Note: Most PHP installations have their own limit, as specified
206 in the php.ini file. Usually 2 MB (or 2048 KB) by default.
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]207**max_width** 0 None The maximum width (in pixels) that the image can be. Set to zero for no
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]208 limit.
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]209**max_height** 0 None The maximum height (in pixels) that the image can be. Set to zero for no
210 limit.
211**min_width** 0 None The minimum width (in pixels) that the image can be. Set to zero for no
212 limit.
213**min_height** 0 None The minimum height (in pixels) that the image can be. Set to zero for no
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]214 limit.
215**max_filename** 0 None The maximum length that a file name can be. Set to zero for no limit.
216**max_filename_increment** 100 None When overwrite is set to FALSE, use this to set the maximum filename
217 increment for CodeIgniter to append to the filename.
218**encrypt_name** FALSE TRUE/FALSE (boolean) If set to TRUE the file name will be converted to a random encrypted
219 string. This can be useful if you would like the file saved with a name
220 that can not be discerned by the person uploading it.
221**remove_spaces** TRUE TRUE/FALSE (boolean) If set to TRUE, any spaces in the file name will be converted to
222 underscores. This is recommended.
Andrey Andreevd60e7002012-06-17 00:03:03 +0300[diff] [blame]223**detect_mime** TRUE TRUE/FALSE (boolean) If set to TRUE, a server side detection of the file type will be
224 performed to avoid code injection attacks. DO NOT disable this option
225 unless you have no other option as that would cause a security risk.
Joseph Wensleyd87e5e62011-10-06 00:06:10 -0400[diff] [blame]226============================ ================= ======================= ======================================================================
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]227
228Setting preferences in a config file
229====================================
230
231If you prefer not to set preferences using the above method, you can
232instead put them into a config file. Simply create a new file called the
233upload.php, add the $config array in that file. Then save the file in:
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]234**config/upload.php** and it will be used automatically. You will NOT
235need to use the ``$this->upload->initialize()`` method if you save your
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]236preferences in a config file.
237
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]238***************
239Class Reference
240***************
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]241
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]242The following methods are available:
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]243
244$this->upload->do_upload()
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]245==========================
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]246
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]247Performs the upload based on the preferences you've set.
248
249.. note:: By default the upload routine expects the file to come from
250 a form field called userfile, and the form must be of type
251 "multipart".
252
253::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]254
255 <form method="post" action="some_action" enctype="multipart/form-data" />
256
257If you would like to set your own field name simply pass its value to
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]258the ``do_upload()`` method::
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]259
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]260 $field_name = "some_field_name";
261 $this->upload->do_upload($field_name);
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]262
263$this->upload->display_errors()
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]264===============================
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]265
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]266Retrieves any error messages if the ``do_upload()`` method returned
267false. The method does not echo automatically, it returns the data so
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]268you can assign it however you need.
269
270Formatting Errors
271*****************
272
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]273By default the above method wraps any errors within <p> tags. You can
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]274set your own delimiters like this::
275
276 $this->upload->display_errors('<p>', '</p>');
277
278$this->upload->data()
279=====================
280
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]281This is a helper method that returns an array containing all of the
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]282data related to the file you uploaded. Here is the array prototype::
283
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]284 Array
285 (
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]286 [file_name] => mypic.jpg
287 [file_type] => image/jpeg
288 [file_path] => /path/to/your/upload/
289 [full_path] => /path/to/your/upload/jpg.jpg
290 [raw_name] => mypic
291 [orig_name] => mypic.jpg
292 [client_name] => mypic.jpg
293 [file_ext] => .jpg
294 [file_size] => 22.2
295 [is_image] => 1
296 [image_width] => 800
297 [image_height] => 600
298 [image_type] => jpeg
299 [image_size_str] => width="800" height="200"
Derek Jones07862512011-10-05 16:10:33 -0500[diff] [blame]300 )
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]301
Michiel Vugteveen37ec30c2012-06-11 09:26:33 +0200[diff] [blame]302To return one element from the array::
303
304 $this->upload->data('file_name'); // Returns: mypic.jpg
305
Derek Jones8ede1a22011-10-05 13:34:52 -0500[diff] [blame]306Explanation
307***********
308
309Here is an explanation of the above array items.
310
311Item
312Description
313**file_name**
314The name of the file that was uploaded including the file extension.
315**file_type**
316The file's Mime type
317**file_path**
318The absolute server path to the file
319**full_path**
320The absolute server path including the file name
321**raw_name**
322The file name without the extension
323**orig_name**
324The original file name. This is only useful if you use the encrypted
325name option.
326**client_name**
327The file name as supplied by the client user agent, prior to any file
328name preparation or incrementing.
329**file_ext**
330The file extension with period
331**file_size**
332The file size in kilobytes
333**is_image**
334Whether the file is an image or not. 1 = image. 0 = not.
335**image_width**
336Image width.
337**image_height**
338Image height
339**image_type**
340Image type. Typically the file extension without the period.
341**image_size_str**
342A string containing the width and height. Useful to put into an image
Andrey Andreev05aa2d62012-12-03 16:06:55 +0200[diff] [blame]343tag.