| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 1 | #################### |
| 2 | File Uploading Class |
| 3 | #################### |
| 4 | |
| 5 | CodeIgniter's File Uploading Class permits files to be uploaded. You can |
| 6 | set various preferences, restricting the type and size of the files. |
| 7 | |
| 8 | *********** |
| 9 | The Process |
| 10 | *********** |
| 11 | |
| 12 | Uploading 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 | |
| 22 | To demonstrate this process here is brief tutorial. Afterward you'll |
| 23 | find reference information. |
| 24 | |
| 25 | Creating the Upload Form |
| 26 | ======================== |
| 27 | |
| 28 | Using a text editor, create a form called upload_form.php. In it, place |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 29 | this code and save it to your applications/views/ folder:: |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 30 | |
| Derek Jones | 0786251 | 2011-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 Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 52 | You'll notice we are using a form helper to create the opening form tag. |
| 53 | File uploads require a multipart form, so the helper creates the proper |
| 54 | syntax for you. You'll also notice we have an $error variable. This is |
| 55 | so we can show error messages in the event the user does something |
| 56 | wrong. |
| 57 | |
| 58 | The Success Page |
| 59 | ================ |
| 60 | |
| 61 | Using a text editor, create a form called upload_success.php. In it, |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 62 | place this code and save it to your applications/views/ folder:: |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 63 | |
| Derek Jones | 0786251 | 2011-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 Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 83 | The Controller |
| 84 | ============== |
| 85 | |
| 86 | Using a text editor, create a controller called upload.php. In it, place |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 87 | this code and save it to your applications/controllers/ folder:: |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 88 | |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 89 | <?php |
| 90 | |
| 91 | class Upload extends CI_Controller { |
| 92 | |
| Andrey Andreev | d8e1ac7 | 2012-03-26 22:22:37 +0300 | [diff] [blame] | 93 | public function __construct() |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 94 | { |
| 95 | parent::__construct(); |
| 96 | $this->load->helper(array('form', 'url')); |
| 97 | } |
| 98 | |
| Andrey Andreev | d8e1ac7 | 2012-03-26 22:22:37 +0300 | [diff] [blame] | 99 | public function index() |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 100 | { |
| 101 | $this->load->view('upload_form', array('error' => ' ' )); |
| 102 | } |
| 103 | |
| Andrey Andreev | d8e1ac7 | 2012-03-26 22:22:37 +0300 | [diff] [blame] | 104 | public function do_upload() |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 105 | { |
| Andrey Andreev | d8e1ac7 | 2012-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 Jones | 0786251 | 2011-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 Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 129 | |
| 130 | The Upload Folder |
| 131 | ================= |
| 132 | |
| 133 | You'll need a destination folder for your uploaded images. Create a |
| 134 | folder at the root of your CodeIgniter installation called uploads and |
| 135 | set its file permissions to 777. |
| 136 | |
| 137 | Try it! |
| 138 | ======= |
| 139 | |
| 140 | To try your form, visit your site using a URL similar to this one:: |
| 141 | |
| 142 | example.com/index.php/upload/ |
| 143 | |
| 144 | You should see an upload form. Try uploading an image file (either a |
| 145 | jpg, gif, or png). If the path in your controller is correct it should |
| 146 | work. |
| 147 | |
| 148 | *************** |
| 149 | Reference Guide |
| 150 | *************** |
| 151 | |
| 152 | Initializing the Upload Class |
| 153 | ============================= |
| 154 | |
| 155 | Like most other classes in CodeIgniter, the Upload class is initialized |
| 156 | in your controller using the $this->load->library function:: |
| 157 | |
| 158 | $this->load->library('upload'); |
| 159 | |
| 160 | Once the Upload class is loaded, the object will be available using: |
| 161 | $this->upload |
| 162 | |
| 163 | Setting Preferences |
| 164 | =================== |
| 165 | |
| 166 | Similar to other libraries, you'll control what is allowed to be upload |
| 167 | based on your preferences. In the controller you built above you set the |
| 168 | following preferences:: |
| 169 | |
| Derek Jones | 0786251 | 2011-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 | |
| 178 | // Alternately you can set preferences by calling the initialize function. Useful if you auto-load the class: |
| 179 | $this->upload->initialize($config); |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 180 | |
| 181 | The above preferences should be fairly self-explanatory. Below is a |
| 182 | table describing all available preferences. |
| 183 | |
| 184 | Preferences |
| 185 | =========== |
| 186 | |
| 187 | The following preferences are available. The default value indicates |
| 188 | what will be used if you do not specify that preference. |
| 189 | |
| Joseph Wensley | d87e5e6 | 2011-10-06 00:06:10 -0400 | [diff] [blame] | 190 | ============================ ================= ======================= ====================================================================== |
| 191 | Preference Default Value Options Description |
| 192 | ============================ ================= ======================= ====================================================================== |
| 193 | **upload_path** None None The path to the folder where the upload should be placed. The folder |
| 194 | must be writable and the path can be absolute or relative. |
| 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 Andreev | 6123b61 | 2012-10-05 15:54:43 +0300 | [diff] [blame] | 200 | If no extension is provided in the original file_name will be used. |
| Joseph Wensley | d87e5e6 | 2011-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. |
| 207 | **max_width** 0 None The maximum width (in pixels) that the file can be. Set to zero for no |
| 208 | limit. |
| 209 | **max_height** 0 None The maximum height (in pixels) that the file can be. Set to zero for no |
| 210 | limit. |
| 211 | **max_filename** 0 None The maximum length that a file name can be. Set to zero for no limit. |
| 212 | **max_filename_increment** 100 None When overwrite is set to FALSE, use this to set the maximum filename |
| 213 | increment for CodeIgniter to append to the filename. |
| 214 | **encrypt_name** FALSE TRUE/FALSE (boolean) If set to TRUE the file name will be converted to a random encrypted |
| 215 | string. This can be useful if you would like the file saved with a name |
| 216 | that can not be discerned by the person uploading it. |
| 217 | **remove_spaces** TRUE TRUE/FALSE (boolean) If set to TRUE, any spaces in the file name will be converted to |
| 218 | underscores. This is recommended. |
| Andrey Andreev | d60e700 | 2012-06-17 00:03:03 +0300 | [diff] [blame] | 219 | **detect_mime** TRUE TRUE/FALSE (boolean) If set to TRUE, a server side detection of the file type will be |
| 220 | performed to avoid code injection attacks. DO NOT disable this option |
| 221 | unless you have no other option as that would cause a security risk. |
| Joseph Wensley | d87e5e6 | 2011-10-06 00:06:10 -0400 | [diff] [blame] | 222 | ============================ ================= ======================= ====================================================================== |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 223 | |
| 224 | Setting preferences in a config file |
| 225 | ==================================== |
| 226 | |
| 227 | If you prefer not to set preferences using the above method, you can |
| 228 | instead put them into a config file. Simply create a new file called the |
| 229 | upload.php, add the $config array in that file. Then save the file in: |
| 230 | config/upload.php and it will be used automatically. You will NOT need |
| 231 | to use the $this->upload->initialize function if you save your |
| 232 | preferences in a config file. |
| 233 | |
| 234 | ****************** |
| 235 | Function Reference |
| 236 | ****************** |
| 237 | |
| 238 | The following functions are available |
| 239 | |
| 240 | $this->upload->do_upload() |
| 241 | =========================== |
| 242 | |
| 243 | Performs the upload based on the preferences you've set. Note: By |
| 244 | default the upload routine expects the file to come from a form field |
| 245 | called userfile, and the form must be a "multipart type:: |
| 246 | |
| 247 | <form method="post" action="some_action" enctype="multipart/form-data" /> |
| 248 | |
| 249 | If you would like to set your own field name simply pass its value to |
| 250 | the do_upload function:: |
| 251 | |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 252 | $field_name = "some_field_name"; |
| 253 | $this->upload->do_upload($field_name); |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 254 | |
| 255 | $this->upload->display_errors() |
| 256 | ================================ |
| 257 | |
| 258 | Retrieves any error messages if the do_upload() function returned |
| 259 | false. The function does not echo automatically, it returns the data so |
| 260 | you can assign it however you need. |
| 261 | |
| 262 | Formatting Errors |
| 263 | ***************** |
| 264 | |
| 265 | By default the above function wraps any errors within <p> tags. You can |
| 266 | set your own delimiters like this:: |
| 267 | |
| 268 | $this->upload->display_errors('<p>', '</p>'); |
| 269 | |
| 270 | $this->upload->data() |
| 271 | ===================== |
| 272 | |
| 273 | This is a helper function that returns an array containing all of the |
| 274 | data related to the file you uploaded. Here is the array prototype:: |
| 275 | |
| Derek Jones | 0786251 | 2011-10-05 16:10:33 -0500 | [diff] [blame] | 276 | Array |
| 277 | ( |
| 278 | [file_name] => mypic.jpg |
| 279 | [file_type] => image/jpeg |
| 280 | [file_path] => /path/to/your/upload/ |
| 281 | [full_path] => /path/to/your/upload/jpg.jpg |
| 282 | [raw_name] => mypic |
| 283 | [orig_name] => mypic.jpg |
| 284 | [client_name] => mypic.jpg |
| 285 | [file_ext] => .jpg |
| 286 | [file_size] => 22.2 |
| 287 | [is_image] => 1 |
| 288 | [image_width] => 800 |
| 289 | [image_height] => 600 |
| 290 | [image_type] => jpeg |
| 291 | [image_size_str] => width="800" height="200" |
| 292 | ) |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 293 | |
| Michiel Vugteveen | 37ec30c | 2012-06-11 09:26:33 +0200 | [diff] [blame] | 294 | To return one element from the array:: |
| 295 | |
| 296 | $this->upload->data('file_name'); // Returns: mypic.jpg |
| 297 | |
| Derek Jones | 8ede1a2 | 2011-10-05 13:34:52 -0500 | [diff] [blame] | 298 | Explanation |
| 299 | *********** |
| 300 | |
| 301 | Here is an explanation of the above array items. |
| 302 | |
| 303 | Item |
| 304 | Description |
| 305 | **file_name** |
| 306 | The name of the file that was uploaded including the file extension. |
| 307 | **file_type** |
| 308 | The file's Mime type |
| 309 | **file_path** |
| 310 | The absolute server path to the file |
| 311 | **full_path** |
| 312 | The absolute server path including the file name |
| 313 | **raw_name** |
| 314 | The file name without the extension |
| 315 | **orig_name** |
| 316 | The original file name. This is only useful if you use the encrypted |
| 317 | name option. |
| 318 | **client_name** |
| 319 | The file name as supplied by the client user agent, prior to any file |
| 320 | name preparation or incrementing. |
| 321 | **file_ext** |
| 322 | The file extension with period |
| 323 | **file_size** |
| 324 | The file size in kilobytes |
| 325 | **is_image** |
| 326 | Whether the file is an image or not. 1 = image. 0 = not. |
| 327 | **image_width** |
| 328 | Image width. |
| 329 | **image_height** |
| 330 | Image height |
| 331 | **image_type** |
| 332 | Image type. Typically the file extension without the period. |
| 333 | **image_size_str** |
| 334 | A string containing the width and height. Useful to put into an image |
| 335 | tag. |