[ci skip] Deprecate prep_for_form() in Form_validation

4 files changed, 28 insertions, 7 deletions

diff --git a/system/libraries/Form_validation.php b/system/libraries/Form_validation.php
index 9fb686892..6be593add 100644
--- a/system/libraries/Form_validation.php
+++ b/system/libraries/Form_validation.php
@@ -1515,10 +1515,11 @@ class CI_Form_validation {
 	 * This function allows HTML to be safely shown in a form.
 	 * Special characters are converted.
 	 *
-	 * @param	string
-	 * @return	string
+	 * @deprecated	3.0.6	Not used anywhere within the framework and pretty much useless
+	 * @param	mixed	$data	Input data
+	 * @return	mixed
 	 */
-	public function prep_for_form($data = '')
+	public function prep_for_form($data)
 	{
 		if ($this->_safe_form_data === FALSE OR empty($data))
 		{
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index de488a995..e88b68f85 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -10,6 +10,7 @@ Release Date: Not Released
 -  General Changes
 
    -  Added a destructor to :doc:`Cache Library <libraries/caching>` 'memcached' driver to ensure that Memcache(d) connections are properly closed.
+   -  Deprecated :doc:`Form Validation Library <libraries/form_validation>` method ``prep_for_form()``.
 
 Bug fixes for 3.0.6
 -------------------
diff --git a/user_guide_src/source/installation/upgrade_306.rst b/user_guide_src/source/installation/upgrade_306.rst
index e9c4bdd79..f6d2f13d4 100644
--- a/user_guide_src/source/installation/upgrade_306.rst
+++ b/user_guide_src/source/installation/upgrade_306.rst
@@ -12,3 +12,22 @@ 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 'prep_for_form' usage (deprecation)
+==================================================
+
+The :doc:`Form Validation Library <../libraries/form_validation>` has a
+``prep_for_form()`` method, which is/can also be used as a rule in
+``set_rules()`` to automatically perform HTML encoding on input data.
+
+Automatically encoding input (instead of output) data is a bad practice in
+the first place, and CodeIgniter and PHP itself offer other alternatives
+to this method anyway.
+For example, :doc:`Form Helper <../helpers/form_helper>` functions will
+automatically perform HTML escaping when necessary.
+
+Therefore, the *prep_for_form* method/rule is pretty much useless and is now
+deprecated and scheduled for removal in 3.1+.
+
+.. note:: The method is still available, but you're strongly encouraged to
+	remove its usage sooner rather than later.
diff --git a/user_guide_src/source/libraries/form_validation.rst b/user_guide_src/source/libraries/form_validation.rst
index 9189d082e..44adfd715 100644
--- a/user_guide_src/source/libraries/form_validation.rst
+++ b/user_guide_src/source/libraries/form_validation.rst
@@ -1007,14 +1007,14 @@ Prepping Reference
 The following is a list of all the prepping methods that are available
 to use:
 
-==================== ========= =======================================================================================================
+==================== ========= ==============================================================================================================
 Name                 Parameter Description
-==================== ========= =======================================================================================================
-**prep_for_form**    No        Converts special characters so that HTML data can be shown in a form field without breaking it.
+==================== ========= ==============================================================================================================
+**prep_for_form**    No        DEPRECATED: Converts special characters so that HTML data can be shown in a form field without breaking it.
 **prep_url**         No        Adds "\http://" to URLs if missing.
 **strip_image_tags** No        Strips the HTML from image tags leaving the raw URL.
 **encode_php_tags**  No        Converts PHP tags to entities.
-==================== ========= =======================================================================================================
+==================== ========= ==============================================================================================================
 
 .. note:: You can also use any native PHP functions that permits one
 	parameter, like ``trim()``, ``htmlspecialchars()``, ``urldecode()``,