Merge pull request #4891 from gxgpet/develop_31102016

Allow existing file rename-for-download in force_download() helper

2 files changed, 44 insertions, 11 deletions

diff --git a/system/helpers/download_helper.php b/system/helpers/download_helper.php
index a6463dfd7..9619c61b1 100644
--- a/system/helpers/download_helper.php
+++ b/system/helpers/download_helper.php
@@ -56,7 +56,7 @@ if ( ! function_exists('force_download'))
 	 *
 	 * Generates headers that force a download to happen
 	 *
-	 * @param	string	filename
+	 * @param	mixed	filename (or an array of local file path => destination filename)
 	 * @param	mixed	the data to be downloaded
 	 * @param	bool	whether to try and send the actual file MIME type
 	 * @return	void
@@ -69,14 +69,38 @@ if ( ! function_exists('force_download'))
 		}
 		elseif ($data === NULL)
 		{
-			if ( ! @is_file($filename) OR ($filesize = @filesize($filename)) === FALSE)
+			// Is $filename an array as ['local source path' => 'destination filename']?
+			if (is_array($filename))
 			{
-				return;
+				if (count($filename) !== 1)
+				{
+					return;
+				}
+
+				$filepath = key($filename);
+				$filename = current($filename);
+
+				if (is_int($filepath))
+				{
+					return;
+				}
+
+				if ( ! @is_file($filepath) OR ($filesize = @filesize($filepath)) === FALSE)
+				{
+					return;
+				}
+			}
+			else
+			{
+				if ( ! @is_file($filename) OR ($filesize = @filesize($filename)) === FALSE)
+				{
+					return;
+				}
+
+				$filepath = $filename;
+				$filename = explode('/', str_replace(DIRECTORY_SEPARATOR, '/', $filename));
+				$filename = end($filename);
 			}
-
-			$filepath = $filename;
-			$filename = explode('/', str_replace(DIRECTORY_SEPARATOR, '/', $filename));
-			$filename = end($filename);
 		}
 		else
 		{
diff --git a/user_guide_src/source/helpers/download_helper.rst b/user_guide_src/source/helpers/download_helper.rst
index 1a4065073..e11d92a14 100644
--- a/user_guide_src/source/helpers/download_helper.rst
+++ b/user_guide_src/source/helpers/download_helper.rst
@@ -26,7 +26,7 @@ The following functions are available:
 
 .. php:function:: force_download([$filename = ''[, $data = ''[, $set_mime = FALSE]]])
 
-	:param	string	$filename: Filename
+	:param	mixed	$filename: Filename
 	:param	mixed	$data: File contents
 	:param	bool	$set_mime: Whether to try to send the actual MIME type
 	:rtype:	void
@@ -37,8 +37,11 @@ The following functions are available:
 	file data.
 
 	If you set the second parameter to NULL and ``$filename`` is an existing, readable
-	file path, then its content will be read instead.
-
+	file path, then its content will be read instead. You may also set ``$filename``
+	as an associative array with a single element, where the key of that element would be 
+	the local file you are trying to read and where the value is the name of the downloadable
+	file that will be sent to browser. An example of this is provided below.
+	
 	If you set the third parameter to boolean TRUE, then the actual file MIME type
 	(based on the filename extension) will be sent, so that if your browser has a
 	handler for that type - it can use it.
@@ -53,4 +56,10 @@ The following functions are available:
 	do the following::
 
 		// Contents of photo.jpg will be automatically read
-		force_download('/path/to/photo.jpg', NULL);
\ No newline at end of file
+		force_download('/path/to/photo.jpg', NULL);
+
+	If you want to download an existing file from your server, but change the name
+	of the actual file sent to browser, you will need this::
+
+		// Contents of photo.jpg will be automatically read and sent as my-photo.jpg
+		force_download(array('/path/to/photo.jpg' => 'my-photo.jpg'), NULL);
\ No newline at end of file