From 2c08e4e4df83e67262d0cde8aed729e4343564fb Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Mon, 23 Sep 2013 15:20:21 +0300 Subject: [ci skip] Update Zip library docs --- user_guide_src/source/libraries/zip.rst | 229 ++++++++++++++++---------------- 1 file changed, 116 insertions(+), 113 deletions(-) (limited to 'user_guide_src') diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst index c27718273..e0955e3d6 100644 --- a/user_guide_src/source/libraries/zip.rst +++ b/user_guide_src/source/libraries/zip.rst @@ -6,6 +6,17 @@ CodeIgniter's Zip Encoding Class classes permit you to create Zip archives. Archives can be downloaded to your desktop or saved to a directory. +.. contents:: + :local: + +.. raw:: html + +
+ +**************************** +Using the Zip Encoding Class +**************************** + Initializing the Class ====================== @@ -35,174 +46,166 @@ your server, and download it to your desktop. // Download the file to your desktop. Name it "my_backup.zip" $this->zip->download('my_backup.zip'); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->zip->add_data() -======================= +.. class:: CI_Zip -Permits you to add data to the Zip archive. The first parameter must -contain the name you would like given to the file, the second parameter -must contain the file data as a string:: + .. method:: add_data($filepath[, $data = NULL]) - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + :param mixed $filepath: a single file path or an array of file => data pairs + :param array $data: single file contents + :returns: void - $this->zip->add_data($name, $data); + Adds data to the Zip archive. Can work both in single and multiple files mode. -You are allowed multiple calls to this function in order to add several -files to your archive. Example:: + When adding a single file, the first parameter must contain the name you would like given to the file and the second must contain the file contents:: - $name = 'mydata1.txt'; - $data = 'A Data String!'; - $this->zip->add_data($name, $data); + $name = 'mydata1.txt'; + $data = 'A Data String!'; + $this->zip->add_data($name, $data); - $name = 'mydata2.txt'; - $data = 'Another Data String!'; - $this->zip->add_data($name, $data); + $name = 'mydata2.txt'; + $data = 'Another Data String!'; + $this->zip->add_data($name, $data); + + When adding multiple files, the first parameter must contain *file => contents* pairs and the second parameter is ignored:: -Or you can pass multiple files using an array:: + $data = array( + 'mydata1.txt' => 'A Data String!', + 'mydata2.txt' => 'Another Data String!' + ); - $data = array( - 'mydata1.txt' => 'A Data String!', - 'mydata2.txt' => 'Another Data String!' - ); + $this->zip->add_data($data); - $this->zip->add_data($data); + If you would like your compressed data organized into sub-directories, simply include the path as part of the filename(s):: - $this->zip->download('my_backup.zip'); + $name = 'personal/my_bio.txt'; + $data = 'I was born in an elevator...'; -If you would like your compressed data organized into sub-folders, -include the path as part of the filename:: + $this->zip->add_data($name, $data); - $name = 'personal/my_bio.txt'; - $data = 'I was born in an elevator...'; + The above example will place my_bio.txt inside a folder called personal. - $this->zip->add_data($name, $data); + .. method:: add_dir($directory) -The above example will place my_bio.txt inside a folder called -personal. + :param mixed $directory: string directory name or an array of multiple directories + :returns: void -$this->zip->add_dir() -====================== + Permits you to add a directory. Usually this method is unnecessary since you can place your data into directories when using + ``$this->zip->add_data()``, but if you would like to create an empty directory you can do so:: -Permits you to add a directory. Usually this function is unnecessary -since you can place your data into folders when using -$this->zip->add_data(), but if you would like to create an empty folder -you can do so. Example:: + $this->zip->add_dir('myfolder'); // Creates a directory called "myfolder" - $this->zip->add_dir('myfolder'); // Creates a folder called "myfolder" + .. method:: read_file($path[, $preserve_filepath = FALSE]) -$this->zip->read_file() -======================== + :param string $path: path to file + :param bool $preserve_filepath: whether to maintain the original filepath + :returns: bool -Permits you to compress a file that already exists somewhere on your -server. Supply a file path and the zip class will read it and add it to -the archive:: + Permits you to compress a file that already exists somewhere on your server. + Supply a file path and the zip class will read it and add it to the archive:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path); + $this->zip->read_file($path); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -If you would like the Zip archive to maintain the directory structure of -the file in it, pass TRUE (boolean) in the second parameter. Example:: + If you would like the Zip archive to maintain the directory structure of + the file in it, pass TRUE (boolean) in the second parameter. Example:: - $path = '/path/to/photo.jpg'; + $path = '/path/to/photo.jpg'; - $this->zip->read_file($path, TRUE); + $this->zip->read_file($path, TRUE); - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); -In the above example, photo.jpg will be placed inside two folders: -path/to/ + In the above example, photo.jpg will be placed into the *path/to/* directory. -$this->zip->read_dir() -======================= + .. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]]) -Permits you to compress a folder (and its contents) that already exists -somewhere on your server. Supply a file path to the directory and the -zip class will recursively read it and recreate it as a Zip archive. All -files contained within the supplied path will be encoded, as will any -sub-folders contained within it. Example:: + :param string $path: path to directory + :param bool $preserve_filepath: whether to maintain the original path + :param string $root_path: part of the path to exclude from the archive directory + :returns: bool - $path = '/path/to/your/directory/'; + Permits you to compress a directory (and its contents) that already exists somewhere on your server. + Supply a path to the directory and the zip class will recursively read and recreate it as a Zip archive. + All files contained within the supplied path will be encoded, as will any sub-directories contained within it. Example:: - $this->zip->read_dir($path); + $path = '/path/to/your/directory/'; - // Download the file to your desktop. Name it "my_backup.zip" - $this->zip->download('my_backup.zip'); + $this->zip->read_dir($path); -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 you can pass FALSE (boolean) in the second -parameter. Example:: + // Download the file to your desktop. Name it "my_backup.zip" + $this->zip->download('my_backup.zip'); - $path = '/path/to/your/directory/'; + 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 directory to be ignored you can pass FALSE (boolean) in the second parameter. Example:: - $this->zip->read_dir($path, FALSE); + $path = '/path/to/your/directory/'; -This will create a ZIP with the folder "directory" inside, then all -sub-folders stored correctly inside that, but will not include the -folders /path/to/your. + $this->zip->read_dir($path, FALSE); -$this->zip->archive() -===================== + This will create a ZIP with a directory named "directory" inside, then all sub-directories stored correctly inside that, but will not include the + */path/to/your* part of the path. -Writes the Zip-encoded file to a directory on your server. Submit a -valid server path ending in the file name. Make sure the directory is -writable (666 or 777 is usually OK). Example:: + .. method:: archive($filepath) - $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip + :param string $filepath: path to target zip archive + :returns: bool -$this->zip->download() -====================== + Writes the Zip-encoded file to a directory on your server. Submit a valid server path ending in the file name. + Make sure the directory is writable (660 or 666 is usually OK). Example:: -Causes the Zip file to be downloaded from your server. The function must -be passed the name you would like the zip file called. Example:: + $this->zip->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip - $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" + .. method:: download($filename = 'backup.zip') -.. note:: Do not display any data in the controller in which you call - this function since it sends various server headers that cause the - download to happen and the file to be treated as binary. + :param string $filename: the archive file name + :returns: void -$this->zip->get_zip() -====================== + Causes the Zip file to be downloaded from your server. You must pass the name you would like the zip file called. Example:: -Returns the Zip-compressed file data. Generally you will not need this -function unless you want to do something unique with the data. Example:: + $this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip" - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + .. note:: Do not display any data in the controller in which you call + this method since it sends various server headers that cause the + download to happen and the file to be treated as binary. - $this->zip->add_data($name, $data); + .. method:: get_zip() - $zip_file = $this->zip->get_zip(); + :returns: string -$this->zip->clear_data() -========================= + Returns the Zip-compressed file data. Generally you will not need this method unless you want to do something unique with the data. Example:: -The Zip class caches your zip data so that it doesn't need to recompile -the Zip archive for each function you use above. If, however, you need -to create multiple Zips, each with different data, you can clear the -cache between calls. Example:: + $name = 'my_bio.txt'; + $data = 'I was born in an elevator...'; - $name = 'my_bio.txt'; - $data = 'I was born in an elevator...'; + $this->zip->add_data($name, $data); - $this->zip->add_data($name, $data); - $zip_file = $this->zip->get_zip(); + $zip_file = $this->zip->get_zip(); + + .. method:: clear_data() + + :returns: void + + The Zip class caches your zip data so that it doesn't need to recompile the Zip archive for each method you use above. + If, however, you need to create multiple Zip archives, each with different data, you can clear the cache between calls. Example:: - $this->zip->clear_data(); + $name = 'my_bio.txt'; + $data = 'I was born in an elevator...'; - $name = 'photo.jpg'; - $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->add_data($name, $data); + $zip_file = $this->zip->get_zip(); + $this->zip->clear_data(); - $this->zip->download('myphotos.zip'); + $name = 'photo.jpg'; + $this->zip->read_file("/path/to/photo.jpg"); // Read the file's contents + $this->zip->download('myphotos.zip'); \ No newline at end of file -- cgit v1.2.3-24-g4f1b