Merge branch 'develop' into 'feature/encryption'

1 files changed, 130 insertions, 113 deletions

diff --git a/user_guide_src/source/libraries/zip.rst b/user_guide_src/source/libraries/zip.rst
index c27718273..5ff7d07d6 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
+
+  <div class="custom-index container"></div>
+
+****************************
+Using the Zip Encoding Class
+****************************
+
 Initializing the Class
 ======================
 
@@ -35,174 +46,180 @@ 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: File contents (ignored if $filepath is an array)
+		:rtype:	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: Directory name string or an array of multiple directories
+		:rtype:	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[, $archive_filepath = FALSE])
 
-$this->zip->read_file()
-========================
+		:param	string	$path: Path to file
+		:param	mixed	$archive_filepath: New file name/path (string) or (boolean) whether to maintain the original filepath
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	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()
-=======================
+		You can also specify a new name (path included) for the added file on the fly::
 
-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::
+			$path = '/path/to/photo.jpg';
+			$new_path = '/new/path/some_photo.jpg';
 
-	$path = '/path/to/your/directory/';
+			$this->zip->read_file($path, $new_path);
 
-	$this->zip->read_dir($path); 
+			// Download ZIP archive containing /new/path/some_photo.jpg
+			$this->zip->download('my_archive.zip');
 
-	// Download the file to your desktop. Name it "my_backup.zip"
-	$this->zip->download('my_backup.zip');
+	.. method:: read_dir($path[, $preserve_filepath = TRUE[, $root_path = NULL]])
 
-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::
+		: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:	TRUE on success, FALSE on failure
+		:rtype:	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, 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); 
 
-$this->zip->archive()
-=====================
+			// Download the file to your desktop. Name it "my_backup.zip"
+			$this->zip->download('my_backup.zip');
 
-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::
+		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->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip
+			$path = '/path/to/your/directory/';
 
-$this->zip->download()
-======================
+			$this->zip->read_dir($path, FALSE);
 
-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 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.
 
-	$this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip"
+	.. method:: archive($filepath)
 
-.. 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	$filepath: Path to target zip archive
+		:returns:	TRUE on success, FALSE on failure
+		:rtype:	bool
 
-$this->zip->get_zip()
-======================
+		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::
 
-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->archive('/path/to/folder/myarchive.zip'); // Creates a file named myarchive.zip
 
-	$name = 'my_bio.txt';
-	$data = 'I was born in an elevator...';
+	.. method:: download($filename = 'backup.zip')
 
-	$this->zip->add_data($name, $data);
+		:param	string	$filename: Archive file name
+		:rtype:	void
 
-	$zip_file = $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::
 
-$this->zip->clear_data()
-=========================
+			$this->zip->download('latest_stuff.zip'); // File will be named "latest_stuff.zip"
 
-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::
+		.. 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.
 
-	$name = 'my_bio.txt';
-	$data = 'I was born in an elevator...';
+	.. method:: get_zip()
 
-	$this->zip->add_data($name, $data);
-	$zip_file = $this->zip->get_zip();
+		:returns:	Zip file content
+		:rtype:	string
+
+		Returns the Zip-compressed file data. Generally you will not need this method unless you want to do something unique with the data. Example::
+
+			$name = 'my_bio.txt';
+			$data = 'I was born in an elevator...';
+
+			$this->zip->add_data($name, $data);
+
+			$zip_file = $this->zip->get_zip();
+
+	.. method:: clear_data()
+
+		:rtype:	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