user_guide/libraries/zip.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>Zip Encoding 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 Zip Encoding 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>Zip Encoding Class</h1>
  60 <p>CodeIgniter's Zip Encoding Class classes permit you to create Zip archives. Archives can be downloaded to your
  61 desktop or saved to a directory.</p>
  62
  63
  64 <h2>Initializing the Class</h2>
  65 <p>Like most other classes in CodeIgniter, the Zip class is initialized in your controller using the <dfn>$this->load->library</dfn> function:</p>
  66
  67 <code>$this->load->library('zip');</code>
  68 <p>Once loaded, the Zip library object will be available using: <dfn>$this->zip</dfn></p>
  69
  70
  71 <h2>Usage Example</h2>
  72
  73 <p>This example demonstrates how to compress a file, save it to a folder on your server, and download it to your desktop.</p>
  74
  75 <code>
  76 $name = 'mydata1.txt';<br />
  77 $data = 'A Data String!';<br />
  78 <br />
  79 $this->zip->add_data($name, $data);<br />
  80 <br />
  81 // Write the zip file to a folder on your server. Name it "my_backup.zip"<br />
  82 $this->zip->archive('/path/to/directory/my_backup.zip');
  83 <br /><br />
  84  // Download the file to your desktop.  Name it "my_backup.zip"<br />
  85 $this->zip->download('my_backup.zip');
  86 </code>
  87
  88 <h1>Function Reference</h1>
  89
  90 <h2>$this->zip->add_data()</h2>
  91
  92 <p>Permits you to add data to the Zip archive. The first parameter must contain the name you would like
  93 given to the file, the second parameter must contain the file data as a string:</p>
  94
  95 <code>
  96 $name = 'my_bio.txt';<br />
  97 $data = 'I was born in an elevator...';<br />
  98 <br />
  99 $this->zip->add_data($name, $data);
 100 </code>
 101
 102 <p>You are allowed multiple calls to this function in order to
 103 add several files to your archive.  Example:</p>
 104
 105 <code>
 106 $name = 'mydata1.txt';<br />
 107 $data = 'A Data String!';<br />
 108 $this->zip->add_data($name, $data);<br />
 109 <br />
 110 $name = 'mydata2.txt';<br />
 111 $data = 'Another Data String!';<br />
 112 $this->zip->add_data($name, $data);<br />
 113 </code>
 114
 115 <p>Or you can pass multiple files using an array:</p>
 116
 117 <code>
 118 $data = array(<br />
 119 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'mydata1.txt' => 'A Data String!',<br />
 120 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'mydata2.txt' => 'Another Data String!'<br />
 121 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;);<br />
 122 <br />
 123 $this->zip->add_data($data);<br />
 124 <br />
 125 $this->zip->download('my_backup.zip');
 126 </code>
 127
 128 <p>If you would like your compressed data organized into sub-folders, include the path as part of the filename:</p>
 129
 130 <code>
 131 $name = '<kbd>personal/</kbd>my_bio.txt';<br />
 132 $data = 'I was born in an elevator...';<br />
 133 <br />
 134 $this->zip->add_data($name, $data);
 135 </code>
 136
 137 <p>The above example will place <dfn>my_bio.txt</dfn> inside a folder called <kbd>personal</kbd>.</p>
 138
 139
 140 <h2>$this->zip->add_dir()</h2>
 141
 142 <p>Permits you to add a directory.  Usually this function is unnecessary since you can place your data into folders when
 143 using <dfn>$this->zip->add_data()</dfn>, but if you would like to create an empty folder you can do so.  Example:</p>
 144
 145 <code>$this->zip->add_dir('myfolder'); // Creates a folder called "myfolder"</code>
 146
 147
 148
 149 <h2>$this->zip->read_file()</h2>
 150
 151 <p>Permits you to compress a file that already exists somewhere on your server.  Supply a file path and the zip class will
 152 read it and add it to the archive:</p>
 153
 154 <code>
 155 $path = '/path/to/photo.jpg';<br /><br />
 156 $this->zip->read_file($path);
 157 <br /><br />
 158  // Download the file to your desktop.  Name it "my_backup.zip"<br />
 159 $this->zip->download('my_backup.zip');
 160 </code>
 161
 162 <p>If you would like the Zip archive to maintain the directory structure of the file in it, pass <kbd>TRUE</kbd> (boolean) in the
 163 second parameter.  Example:</p>
 164
 165
 166 <code>
 167 $path = '/path/to/photo.jpg';<br /><br />
 168 $this->zip->read_file($path, <kbd>TRUE</kbd>);
 169 <br /><br />
 170  // Download the file to your desktop.  Name it "my_backup.zip"<br />
 171 $this->zip->download('my_backup.zip');
 172 </code>
 173
 174 <p>In the above example, <dfn>photo.jpg</dfn> will be placed inside two folders:  <kbd>path/to/</kbd></p>
 175
 176
 177
 178 <h2>$this->zip->read_dir()</h2>
 179
 180 <p>Permits you to compress a folder (and its contents) that already exists somewhere on your server.  Supply a file path to the
 181 directory and the zip class will recursively read it and recreate it as a Zip archive.  All files contained within the
 182 supplied path will be encoded, as will any sub-folders contained within it.  Example:</p>
 183
 184 <code>
 185 $path = '/path/to/your/directory/';<br /><br />
 186 $this->zip->read_dir($path);
 187 <br /><br />
 188  // Download the file to your desktop.  Name it "my_backup.zip"<br />
 189 $this->zip->download('my_backup.zip');
 190 </code>
 191
 192 <p>By default the Zip archive will place all directories listed in the first parameter inside the zip. If you want the tree preceding the target folder to be ignored
 193 you can pass <kbd>FALSE</kbd> (boolean) in the second parameter.  Example:</p>
 194
 195 <code>
 196 $path = '/path/to/your/directory/';<br /><br />
 197 $this->zip->read_dir($path, FALSE);
 198 </code>
 199
 200 <p>This will create a ZIP with the folder "directory" inside, then all sub-folders stored correctly inside that, but will not include the folders <samp>/path/to/your</samp>.</p>
 201
 202
 203
 204
 205 <h2>$this->zip->archive()</h2>
 206
 207 <p>Writes the Zip-encoded file to a directory on your server.  Submit a valid server path ending in the file name.  Make sure the
 208 directory is writable (666 or 777 is usually OK). Example:</p>
 209
 210 <code>$this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip</code>
 211
 212
 213 <h2>$this->zip->download()</h2>
 214
 215 <p>Causes the Zip file to be downloaded from your server. The function must be passed the name you would like the zip file called.
 216 Example:</p>
 217
 218 <code>$this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip"</code>
 219
 220 <p class="important"><strong>Note:</strong>&nbsp; Do not display any data in the controller in which you call this function since it sends various server headers
 221 that cause the download to happen and the file to be treated as binary.</p>
 222
 223
 224 <h2>$this->zip->get_zip()</h2>
 225
 226 <p>Returns the Zip-compressed file data.  Generally you will not need this function unless you want to do something unique with the data.
 227 Example:</p>
 228
 229 <code>
 230 $name = 'my_bio.txt';<br />
 231 $data = 'I was born in an elevator...';<br />
 232 <br />
 233 $this->zip->add_data($name, $data);<br /><br />
 234
 235 $zip_file = $this->zip->get_zip();
 236 </code>
 237
 238
 239 <h2>$this->zip->clear_data()</h2>
 240
 241 <p>The Zip class caches your zip data so that it doesn't need to recompile the Zip archive for each function you use above.
 242 If, however, you need to create multiple Zips, each with different data, you can clear the cache between calls. Example:</p>
 243
 244 <code>
 245 $name = 'my_bio.txt';<br />
 246 $data = 'I was born in an elevator...';<br />
 247 <br />
 248 $this->zip->add_data($name, $data);<br />
 249 $zip_file = $this->zip->get_zip();<br />
 250 <br />
 251 <kbd>$this->zip->clear_data();</kbd>
 252 <br /><br />
 253
 254 $name = 'photo.jpg';<br />
 255 $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents<br />
 256 <br /><br />
 257 $this->zip->download('myphotos.zip');
 258 </code>
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272 </div>
 273 <!-- END CONTENT -->
 274
 275
 276 <div id="footer">
 277 <p>
 278 Previous Topic:&nbsp;&nbsp;<a href="xmlrpc.html"> XML-RPC Class</a>
 279 &nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 280 <a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 281 <a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
 282 Next Topic:&nbsp;&nbsp;<a href="../helpers/array_helper.html">Array Helper</a>
 283 </p>
 284 <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>
 285 </div>
 286
 287 </body>
 288 </html>