user_guide/libraries/file_uploading.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   3 <head>
   4
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <title>File Uploading Class : CodeIgniter User Guide</title>
   7
   8 <style type='text/css' media='all'>@import url('../userguide.css');</style>
   9 <link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
  10
  11 <script type="text/javascript" src="../nav/nav.js"></script>
  12 <script type="text/javascript" src="../nav/prototype.lite.js"></script>
  13 <script type="text/javascript" src="../nav/moo.fx.js"></script>
  14 <script type="text/javascript" src="../nav/user_guide_menu.js"></script>
  15
  16 <meta http-equiv='expires' content='-1' />
  17 <meta http-equiv= 'pragma' content='no-cache' />
  18 <meta name='robots' content='all' />
  19 <meta name='author' content='ExpressionEngine Dev Team' />
  20 <meta name='description' content='CodeIgniter User Guide' />
  21
  22 </head>
  23 <body>
  24
  25 <!-- START NAVIGATION -->
  26 <div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
  27 <div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
  28 <div id="masthead">
  29 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  30 <tr>
  31 <td><h1>CodeIgniter User Guide Version 2.0.2</h1></td>
  32 <td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
  33 </tr>
  34 </table>
  35 </div>
  36 <!-- END NAVIGATION -->
  37
  38
  39 <!-- START BREADCRUMB -->
  40 <table cellpadding="0" cellspacing="0" border="0" style="width:100%">
  41 <tr>
  42 <td id="breadcrumb">
  43 <a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
  44 <a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
  45 File Uploading Class
  46 </td>
  47 <td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
  48 </tr>
  49 </table>
  50 <!-- END BREADCRUMB -->
  51
  52 <br clear="all" />
  53
  54
  55 <!-- START CONTENT -->
  56 <div id="content">
  57
  58
  59 <h1>File Uploading Class</h1>
  60
  61 <p>CodeIgniter's File Uploading Class permits files to be uploaded.  You can set various
  62 preferences, restricting the type and size of the files.</p>
  63
  64
  65 <h2>The Process</h2>
  66
  67 <p>Uploading a file involves the following general process:</p>
  68
  69
  70 <ul>
  71 <li>An upload form is displayed, allowing a user to select a file and upload it.</li>
  72 <li>When the form is submitted, the file is uploaded to the destination you specify.</li>
  73 <li>Along the way, the file is validated to make sure it is allowed to be uploaded based on the preferences you set.</li>
  74 <li>Once uploaded, the user will be shown a success message.</li>
  75 </ul>
  76
  77 <p>To demonstrate this process here is brief tutorial. Afterward you'll find reference information.</p>
  78
  79 <h2>Creating the Upload Form</h2>
  80
  81
  82
  83 <p>Using a text editor, create a form called <dfn>upload_form.php</dfn>.  In it, place this code and save it to your <samp>applications/views/</samp>
  84 folder:</p>
  85
  86
  87 <textarea class="textarea" style="width:100%" cols="50" rows="23">
  88 &lt;html>
  89 &lt;head>
  90 &lt;title>Upload Form&lt;/title>
  91 &lt;/head>
  92 &lt;body>
  93
  94 &lt;?php echo $error;?>
  95
  96 &lt;?php echo form_open_multipart('upload/do_upload');?>
  97
  98 &lt;input type="file" name="userfile" size="20" />
  99
 100 &lt;br />&lt;br />
 101
 102 &lt;input type="submit" value="upload" />
 103
 104 &lt;/form>
 105
 106 &lt;/body>
 107 &lt;/html></textarea>
 108
 109 <p>You'll notice we are using a form helper to create the opening form tag.  File uploads require a multipart form, so the helper
 110 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
 111 the user does something wrong.</p>
 112
 113
 114 <h2>The Success Page</h2>
 115
 116 <p>Using a text editor, create a form called <dfn>upload_success.php</dfn>.
 117 In it, place this code and save it to your <samp>applications/views/</samp> folder:</p>
 118
 119 <textarea class="textarea" style="width:100%" cols="50" rows="20">&lt;html>
 120 &lt;head>
 121 &lt;title>Upload Form&lt;/title>
 122 &lt;/head>
 123 &lt;body>
 124
 125 &lt;h3>Your file was successfully uploaded!&lt;/h3>
 126
 127 &lt;ul>
 128 &lt;?php foreach ($upload_data as $item => $value):?>
 129 &lt;li>&lt;?php echo $item;?>: &lt;?php echo $value;?>&lt;/li>
 130 &lt;?php endforeach; ?>
 131 &lt;/ul>
 132
 133 &lt;p>&lt;?php echo anchor('upload', 'Upload Another File!'); ?>&lt;/p>
 134
 135 &lt;/body>
 136 &lt;/html></textarea>
 137
 138
 139 <h2>The Controller</h2>
 140
 141 <p>Using a text editor, create a controller called <dfn>upload.php</dfn>.  In it, place this code and save it to your <samp>applications/controllers/</samp>
 142 folder:</p>
 143
 144
 145 <textarea class="textarea" style="width:100%" cols="50" rows="43">&lt;?php
 146
 147 class Upload extends CI_Controller {
 148
 149         function __construct()
 150         {
 151                 parent::__construct();
 152                 $this->load->helper(array('form', 'url'));
 153         }
 154
 155         function index()
 156         {
 157                 $this->load->view('upload_form', array('error' => ' ' ));
 158         }
 159
 160         function do_upload()
 161         {
 162                 $config['upload_path'] = './uploads/';
 163                 $config['allowed_types'] = 'gif|jpg|png';
 164                 $config['max_size']     = '100';
 165                 $config['max_width']  = '1024';
 166                 $config['max_height']  = '768';
 167
 168                 $this->load->library('upload', $config);
 169
 170                 if ( ! $this->upload->do_upload())
 171                 {
 172                         $error = array('error' => $this->upload->display_errors());
 173
 174                         $this->load->view('upload_form', $error);
 175                 }
 176                 else
 177                 {
 178                         $data = array('upload_data' => $this->upload->data());
 179
 180                         $this->load->view('upload_success', $data);
 181                 }
 182         }
 183 }
 184 ?&gt;</textarea>
 185
 186
 187 <h2>The Upload Folder</h2>
 188
 189 <p>You'll need a destination folder for your uploaded images.  Create a folder at the root of your CodeIgniter installation called
 190 <dfn>uploads</dfn> and set its file permissions to 777.</p>
 191
 192
 193 <h2>Try it!</h2>
 194
 195 <p>To try your form, visit your site using a URL similar to this one:</p>
 196
 197 <code>example.com/index.php/<var>upload</var>/</code>
 198
 199 <p>You should see an upload form. Try uploading an image file (either a jpg, gif, or png). If the path in your
 200 controller is correct it should work.</p>
 201
 202
 203 <p>&nbsp;</p>
 204
 205 <h1>Reference Guide</h1>
 206
 207
 208 <h2>Initializing the Upload Class</h2>
 209
 210 <p>Like most other classes in CodeIgniter, the Upload class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
 211
 212 <code>$this->load->library('upload');</code>
 213 <p>Once the Upload class is loaded, the object will be available using: <dfn>$this->upload</dfn></p>
 214
 215
 216 <h2>Setting Preferences</h2>
 217
 218 <p>Similar to other libraries, you'll control what is allowed to be upload based on your preferences.  In the controller you
 219 built above you set the following preferences:</p>
 220
 221 <code>$config['upload_path'] = './uploads/';<br />
 222 $config['allowed_types'] = 'gif|jpg|png';<br />
 223 $config['max_size']     = '100';<br />
 224 $config['max_width']  = '1024';<br />
 225 $config['max_height']  = '768';<br />
 226 <br />
 227 $this->load->library('upload', $config);<br /><br />
 228
 229 // Alternately you can set preferences by calling the initialize function.  Useful if you auto-load the class:<br />
 230 $this->upload->initialize($config);</code>
 231
 232 <p>The above preferences should be fairly self-explanatory.  Below is a table describing all available preferences.</p>
 233
 234
 235 <h2>Preferences</h2>
 236
 237 <p>The following preferences are available.  The default value indicates what will be used if you do not specify that preference.</p>
 238
 239 <table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
 240 <tr>
 241 <th>Preference</th>
 242 <th>Default&nbsp;Value</th>
 243 <th>Options</th>
 244 <th>Description</th>
 245 </tr>
 246
 247 <tr>
 248 <td class="td"><strong>upload_path</strong></td>
 249 <td class="td">None</td>
 250 <td class="td">None</td>
 251 <td class="td">The path to the folder where the upload should be placed.  The folder must be writable and the path can be absolute or relative.</td>
 252 </tr>
 253
 254 <tr>
 255 <td class="td"><strong>allowed_types</strong></td>
 256 <td class="td">None</td>
 257 <td class="td">None</td>
 258 <td class="td">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.  Separate multiple types with a pipe.</td>
 259 </tr>
 260
 261
 262 <tr>
 263 <td class="td"><strong>file_name</strong></td>
 264 <td class="td">None</td>
 265 <td class="td">Desired file name</td>
 266 <td class="td">
 267         <p>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.</p>
 268 </td>
 269 </tr>
 270
 271 <tr>
 272 <td class="td"><strong>overwrite</strong></td>
 273 <td class="td">FALSE</td>
 274 <td class="td">TRUE/FALSE (boolean)</td>
 275 <td class="td">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.</td>
 276 </tr>
 277
 278
 279 <tr>
 280 <td class="td"><strong>max_size</strong></td>
 281 <td class="td">0</td>
 282 <td class="td">None</td>
 283 <td class="td">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.</td>
 284 </tr>
 285
 286 <tr>
 287 <td class="td"><strong>max_width</strong></td>
 288 <td class="td">0</td>
 289 <td class="td">None</td>
 290 <td class="td">The maximum width (in pixels) that the file can be.  Set to zero for no limit.</td>
 291 </tr>
 292
 293 <tr>
 294 <td class="td"><strong>max_height</strong></td>
 295 <td class="td">0</td>
 296 <td class="td">None</td>
 297 <td class="td">The maximum height (in pixels) that the file can be.  Set to zero for no limit.</td>
 298 </tr>
 299
 300 <tr>
 301 <td class="td"><strong>max_filename</strong></td>
 302 <td class="td">0</td>
 303 <td class="td">None</td>
 304 <td class="td">The maximum length that a file name can be.  Set to zero for no limit.</td>
 305 </tr>
 306
 307 <tr>
 308 <td class="td"><strong>encrypt_name</strong></td>
 309 <td class="td">FALSE</td>
 310 <td class="td">TRUE/FALSE (boolean)</td>
 311 <td class="td">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.</td>
 312 </tr>
 313
 314 <tr>
 315 <td class="td"><strong>remove_spaces</strong></td>
 316 <td class="td">TRUE</td>
 317 <td class="td">TRUE/FALSE (boolean)</td>
 318 <td class="td">If set to TRUE, any spaces in the file name will be converted to underscores. This is recommended.</td>
 319 </tr>
 320 </table>
 321
 322
 323 <h2>Setting preferences in a config file</h2>
 324
 325 <p>If you prefer not to set preferences using the above method, you can instead put them into a config file.
 326 Simply create a new file called the <var>upload.php</var>,  add the <var>$config</var>
 327 array in that file. Then save the file in: <var>config/upload.php</var> and it will be used automatically. You
 328 will NOT need to use the <dfn>$this->upload->initialize</dfn> function if you save your preferences in a config file.</p>
 329
 330
 331 <h2>Function Reference</h2>
 332
 333 <p>The following functions are available</p>
 334
 335
 336 <h2>$this->upload->do_upload()</h2>
 337
 338 <p>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
 339 called <dfn>userfile</dfn>, and the form must be a "multipart type:</p>
 340
 341 <code>&lt;form method="post" action="some_action" enctype="multipart/form-data" /></code>
 342
 343 <p>If you would like to set your own field name simply pass its value to the <dfn>do_upload</dfn> function:</p>
 344
 345 <code>
 346 $field_name = "some_field_name";<br />
 347 $this->upload->do_upload($field_name)</code>
 348
 349
 350 <h2>$this->upload->display_errors()</h2>
 351
 352 <p>Retrieves any error messages if the <dfn>do_upload()</dfn> function returned false.  The function does not echo automatically, it
 353 returns the data so you can assign it however you need.</p>
 354
 355 <h3>Formatting Errors</h3>
 356 <p>By default the above function wraps any errors within &lt;p> tags.  You can set your own delimiters like this:</p>
 357
 358 <code>$this->upload->display_errors('<var>&lt;p></var>', '<var>&lt;/p></var>');</code>
 359
 360 <h2>$this->upload->data()</h2>
 361
 362 <p>This is a helper function that returns an array containing all of the data related to the file you uploaded.
 363 Here is the array prototype:</p>
 364
 365 <code>Array<br />
 366 (<br />
 367 &nbsp;&nbsp;&nbsp;&nbsp;[file_name]&nbsp;&nbsp;&nbsp;&nbsp;=> mypic.jpg<br />
 368 &nbsp;&nbsp;&nbsp;&nbsp;[file_type]&nbsp;&nbsp;&nbsp;&nbsp;=> image/jpeg<br />
 369 &nbsp;&nbsp;&nbsp;&nbsp;[file_path]&nbsp;&nbsp;&nbsp;&nbsp;=> /path/to/your/upload/<br />
 370 &nbsp;&nbsp;&nbsp;&nbsp;[full_path]&nbsp;&nbsp;&nbsp;&nbsp;=> /path/to/your/upload/jpg.jpg<br />
 371 &nbsp;&nbsp;&nbsp;&nbsp;[raw_name]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> mypic<br />
 372 &nbsp;&nbsp;&nbsp;&nbsp;[orig_name]&nbsp;&nbsp;&nbsp;&nbsp;=> mypic.jpg<br />
 373 &nbsp;&nbsp;&nbsp;&nbsp;[client_name]&nbsp;&nbsp;=> mypic.jpg<br />
 374 &nbsp;&nbsp;&nbsp;&nbsp;[file_ext]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> .jpg<br />
 375 &nbsp;&nbsp;&nbsp;&nbsp;[file_size]&nbsp;&nbsp;&nbsp;&nbsp;=> 22.2<br />
 376 &nbsp;&nbsp;&nbsp;&nbsp;[is_image]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;=> 1<br />
 377 &nbsp;&nbsp;&nbsp;&nbsp;[image_width]&nbsp;&nbsp;=> 800<br />
 378 &nbsp;&nbsp;&nbsp;&nbsp;[image_height] => 600<br />
 379 &nbsp;&nbsp;&nbsp;&nbsp;[image_type]&nbsp;&nbsp;&nbsp;=> jpeg<br />
 380 &nbsp;&nbsp;&nbsp;&nbsp;[image_size_str] => width="800" height="200"<br />
 381 )</code>
 382
 383 <h3>Explanation</h3>
 384
 385 <p>Here is an explanation of the above array items.</p>
 386
 387 <table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
 388 <tr><th>Item</th><th>Description</th></tr>
 389
 390 <tr><td class="td"><strong>file_name</strong></td>
 391 <td class="td">The name of the file that was uploaded including the file extension.</td></tr>
 392
 393 <tr><td class="td"><strong>file_type</strong></td>
 394 <td class="td">The file's Mime type</td></tr>
 395
 396 <tr><td class="td"><strong>file_path</strong></td>
 397 <td class="td">The absolute server path to the file</td></tr>
 398
 399 <tr><td class="td"><strong>full_path</strong></td>
 400 <td class="td">The absolute server path including the file name</td></tr>
 401
 402 <tr><td class="td"><strong>raw_name</strong></td>
 403 <td class="td">The file name without the extension</td></tr>
 404
 405 <tr><td class="td"><strong>orig_name</strong></td>
 406 <td class="td">The original file name.  This is only useful if you use the encrypted name option.</td></tr>
 407
 408 <tr><td class="td"><strong>client_name</strong></td>
 409 <td class="td">The file name as supplied by the client user agent, prior to any file name preparation or incrementing.</td></tr>
 410
 411 <tr><td class="td"><strong>file_ext</strong></td>
 412 <td class="td">The file extension with period</td></tr>
 413
 414 <tr><td class="td"><strong>file_size</strong></td>
 415 <td class="td">The file size in kilobytes</td></tr>
 416
 417 <tr><td class="td"><strong>is_image</strong></td>
 418 <td class="td">Whether the file is an image or not.  1 = image. 0 = not.</td></tr>
 419
 420 <tr><td class="td"><strong>image_width</strong></td>
 421 <td class="td">Image width.</td></tr>
 422
 423 <tr><td class="td"><strong>image_height</strong></td>
 424 <td class="td">Image height</td></tr>
 425
 426 <tr><td class="td"><strong>image_type</strong></td>
 427 <td class="td">Image type.  Typically the file extension without the period.</td></tr>
 428
 429 <tr><td class="td"><strong>image_size_str</strong></td>
 430 <td class="td">A string containing the width and height.  Useful to put into an image tag.</td></tr>
 431
 432
 433 </table>
 434
 435 </div>
 436 <!-- END CONTENT -->
 437
 438
 439 <div id="footer">
 440 <p>
 441 Previous Topic:&nbsp;&nbsp;<a href="encryption.html">Encryption Helper</a>
 442 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 443 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 444 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 445 Next Topic:&nbsp;&nbsp;<a href="form_validation.html">Form Validation Class</a>
 446 </p>
 447 <p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
 448 </div>
 449
 450 </body>
 451 </html>