[ci skip] Deprecate extra parameters of the CAPTCHA helper

4 files changed, 26 insertions, 8 deletions

diff --git a/system/helpers/captcha_helper.php b/system/helpers/captcha_helper.php
index 8f44806cc..b1a7eedd0 100644
--- a/system/helpers/captcha_helper.php
+++ b/system/helpers/captcha_helper.php
@@ -54,10 +54,10 @@ if ( ! function_exists('create_captcha'))
 	/**
 	 * Create CAPTCHA
 	 *
-	 * @param	array	$data		data for the CAPTCHA
-	 * @param	string	$img_path	path to create the image in
-	 * @param	string	$img_url	URL to the CAPTCHA image folder
-	 * @param	string	$font_path	server path to font
+	 * @param	array	$data		Data for the CAPTCHA
+	 * @param	string	$img_path	Path to create the image in (deprecated)
+	 * @param	string	$img_url	URL to the CAPTCHA image folder (deprecated)
+	 * @param	string	$font_path	Server path to font (deprecated)
 	 * @return	string
 	 */
 	function create_captcha($data = '', $img_path = '', $img_url = '', $font_path = '')
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 647fe4817..1793108d8 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -11,6 +11,7 @@ Release Date: Not Released
 
    -  Updated :doc:`Form Validation Library <libraries/form_validation>` rule ``valid_email`` to use ``INTL_IDNA_VARIANT_UCS46`` for non-ASCII domain names.
    -  Updated :doc:`Email Library <libraries/email>` to use ``INTL_IDNA_VARIANT_UCS46`` for non-ASCII domain names.
+   -  Deprecated usage of :doc:`CAPTCHA Helper <helpers/captcha_helper>` function :php:func:`create_captcha()` with parameters other than ``$data``.
 
 Bug fixes for 3.1.7
 -------------------
diff --git a/user_guide_src/source/helpers/captcha_helper.rst b/user_guide_src/source/helpers/captcha_helper.rst
index 986c1d3e1..be1b20aaf 100644
--- a/user_guide_src/source/helpers/captcha_helper.rst
+++ b/user_guide_src/source/helpers/captcha_helper.rst
@@ -135,9 +135,9 @@ The following functions are available:
 .. php:function:: create_captcha([$data = ''[, $img_path = ''[, $img_url = ''[, $font_path = '']]]])
 
 	:param	array	$data: Array of data for the CAPTCHA
-	:param	string	$img_path: Path to create the image in
-	:param	string	$img_url: URL to the CAPTCHA image folder
-	:param	string	$font_path: Server path to font
+	:param	string	$img_path: Path to create the image in (DEPRECATED)
+	:param	string	$img_url: URL to the CAPTCHA image folder (DEPRECATED)
+	:param	string	$font_path: Server path to font (DEPRECATED)
 	:returns:	array('word' => $word, 'time' => $now, 'image' => $img)
 	:rtype:	array
 
@@ -161,4 +161,8 @@ The following functions are available:
 	file extension. It will be a number like this: 1139612155.3422
 
 	The **word** is the word that appears in the captcha image, which if not
-	supplied to the function, will be a random string.
\ No newline at end of file
+	supplied to the function, will be a random string.
+
+	.. note:: Usage of the ``$img_path``, ``$img_url`` and ``$font_path``
+		parameters is DEPRECATED. Provide them in the ``$data`` array
+		instead.
diff --git a/user_guide_src/source/installation/upgrade_317.rst b/user_guide_src/source/installation/upgrade_317.rst
index 93c37b687..dc1ee1868 100644
--- a/user_guide_src/source/installation/upgrade_317.rst
+++ b/user_guide_src/source/installation/upgrade_317.rst
@@ -12,3 +12,16 @@ Replace all files and directories in your *system/* directory.
 
 .. note:: If you have any custom developed files in these directories,
 	please make copies of them first.
+
+Step 2: Remove usage of CAPTCHA helper extra parameters (deprecation)
+=====================================================================
+
+The :doc:`CAPTCHA Helper <../helpers/captcha_helper>` function
+:php:func:`create_captcha()` allows passing of its ``img_path``, ``img_url``
+and ``font_path`` options as the 2nd, 3rd and 4th parameters respectively.
+
+This kind of usage is now deprecated and you should just pass the options
+in question as part of the first parameter array.
+
+.. note:: The functionality in question is still available, but you're
+	strongly encouraged to remove its usage sooner rather than later.