Deprecate Date helper standard_date()

4 files changed, 63 insertions, 15 deletions

diff --git a/system/helpers/date_helper.php b/system/helpers/date_helper.php
index 6686089c6..a45b3d7ac 100644
--- a/system/helpers/date_helper.php
+++ b/system/helpers/date_helper.php
@@ -117,6 +117,19 @@ if ( ! function_exists('standard_date'))
 	 *
 	 * Returns a date formatted according to the submitted standard.
 	 *
+	 * As of PHP 5.2, the DateTime extension provides constants that
+	 * serve for the exact same purpose and are used with date().
+	 * Due to that, this function is DEPRECATED and should be removed
+	 * in CodeIgniter 3.1+.
+	 *
+	 * Here are two examples of how you should replace it:
+	 *
+	 *	date(DATE_RFC822, now()); // default
+	 *	date(DATE_W3C, $time); // a different format and time
+	 *
+	 * Reference: http://www.php.net/manual/en/class.datetime.php#datetime.constants.types
+	 *
+	 * @deprecated
 	 * @param	string	the chosen format
 	 * @param	int	Unix timestamp
 	 * @return	string
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index efe49cfe0..37063f752 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -52,7 +52,11 @@ Release Date: Not Released
 
 -  Helpers
 
-   -  :doc:`Date Helper <helpers/date_helper>` function now() now works with all timezone strings supported by PHP.
+   -  :doc:`Date Helper <helpers/date_helper>` changes include:
+	 - ``now()`` now works with all timezone strings supported by PHP.
+	 - Added an optional third parameter to ``timespan()`` that constrains the number of time units displayed.
+	 - Added an optional parameter to ``timezone_menu()`` that allows more attributes to be added to the generated select tag.
+	 - Deprecated ``standard_date()``, which now just uses the native ``date()`` with `DateTime constants <http://bg2.php.net/manual/en/class.datetime.php#datetime.constants.types>`_.
    -  ``create_captcha()`` accepts additional colors parameter, allowing for color customization.
    -  :doc:`URL Helper <helpers/url_helper>` changes include:
 	 - ``url_title()`` will now trim extra dashes from beginning and end.
@@ -63,7 +67,6 @@ Release Date: Not Released
    -  Changed ``humanize()`` to include a second param for the separator.
    -  Refactored ``plural()`` and ``singular()`` to avoid double pluralization and support more words.
    -  Added an optional third parameter to ``force_download()`` that enables/disables sending the actual file MIME type in the Content-Type header (disabled by default).
-   -  Added an optional third parameter to ``timespan()`` that constrains the number of time units displayed.
    -  Added a work-around in ``force_download()`` for a bug Android <= 2.1, where the filename extension needs to be in uppercase.
    -  ``form_dropdown()`` will now also take an array for unity with other form helpers.
    -  ``do_hash()`` now uses PHP's native ``hash()`` function (supporting more algorithms) and is deprecated.
@@ -72,7 +75,6 @@ Release Date: Not Released
 	 - ``set_realpath()`` can now also handle file paths as opposed to just directories.
 	 - Added an optional paramater to ``delete_files()`` to enable it to skip deleting files such as .htaccess and index.html.
 	 - ``read_file()`` is now a deprecated alias of ``file_get_contents()``.
-   -  Added an optional parameter to :doc:`Date Helper <helpers/date_helper>` function ``timezone_menu()`` that allows more attributes to be added to the generated select tag.
    -  :doc:`Security Helper <helpers/security_helper>` function ``strip_image_tags()`` is now an alias for the same method in the :doc:`Security Library <libraries/security>`.
 
 -  Database
diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst
index 5adfb18d2..e332a913f 100644
--- a/user_guide_src/source/helpers/date_helper.rst
+++ b/user_guide_src/source/helpers/date_helper.rst
@@ -40,7 +40,7 @@ If a timezone is not provided, it will return time() based on "time_reference" s
 mdate()
 =======
 
-This function is identical to PHPs `date() <http://www.php.net/date>`_
+This function is identical to PHP's `date() <http://www.php.net/date>`_
 function, except that it lets you use MySQL style date codes, where each
 code letter is preceded with a percent sign: %Y %m %d etc.
 
@@ -85,21 +85,28 @@ Example
 The first parameter must contain the format, the second parameter must
 contain the date as a Unix timestamp.
 
+.. note:: This function is DEPRECATED. Use the native ``date()`` combined
+	with `DateTime's format constants <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_
+	instead:
+
+	|
+	| echo date(DATE_RFC822, time());
+
 Supported formats:
 
 ===============	=======================	======================================
 Constant		Description				Example
 ===============	=======================	======================================
-DATE_ATOM		Atom					2005-08-15T16:13:03+0000
-DATE_COOKIE		HTTP Cookies			Sun, 14 Aug 2005 16:13:03 UTC
-DATE_ISO8601   	ISO-8601				2005-08-14T16:13:03+00:00
-DATE_RFC822		RFC 822					Sun, 14 Aug 05 16:13:03 UTC
-DATE_RFC850		RFC 850					Sunday, 14-Aug-05 16:13:03 UTC
-DATE_RFC1036	RFC 1036				Sunday, 14-Aug-05 16:13:03 UTC
-DATE_RFC1123	RFC 1123				Sun, 14 Aug 2005 16:13:03 UTC
-DATE_RFC2822 	RFC 2822				Sun, 14 Aug 2005 16:13:03 +0000
-DATE_RSS		RSS						Sun, 14 Aug 2005 16:13:03 UTC
-DATE_W3C		W3C						2005-08-14T16:13:03+0000
+DATE_ATOM	Atom			2005-08-15T16:13:03+0000
+DATE_COOKIE	HTTP Cookies		Sun, 14 Aug 2005 16:13:03 UTC
+DATE_ISO8601   	ISO-8601		2005-08-14T16:13:03+00:00
+DATE_RFC822	RFC 822			Sun, 14 Aug 05 16:13:03 UTC
+DATE_RFC850	RFC 850			Sunday, 14-Aug-05 16:13:03 UTC
+DATE_RFC1036	RFC 1036		Sunday, 14-Aug-05 16:13:03 UTC
+DATE_RFC1123	RFC 1123		Sun, 14 Aug 2005 16:13:03 UTC
+DATE_RFC2822 	RFC 2822		Sun, 14 Aug 2005 16:13:03 +0000
+DATE_RSS	RSS			Sun, 14 Aug 2005 16:13:03 UTC
+DATE_W3C	W3C			2005-08-14T16:13:03+0000
 ===============	=======================	======================================
 
 local_to_gmt()
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 7b0d8abe9..6b93750d1 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -102,6 +102,32 @@ CodeIgniter 3.1+.
 .. note:: This function is still available, but you're strongly encouraged to remove it's usage sooner
 	rather than later.
 
+Date helper standard_date()
+===========================
+
+:doc:`Date Helper <../helpers/date_helper>` function ``standard_date()`` is being deprecated due
+to the availability of native PHP `constants <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_,
+which when combined with ``date()`` provide the same functionality. Furthermore, they have the
+exact same names as the ones suppored by ``standard_date()``. Here are examples of how to replace
+it's usage:
+
+::
+
+	// Old way
+	standard_date(); // defaults to stanard_date('DATE_RFC822', now());
+
+	// Replacement
+	date(DATE_RFC822, now());
+
+	// Old way
+	standard_date('DATE_ATOM', $time);
+
+	// Replacement
+	date(DATE_ATOM, $time);
+
+.. note:: This function is still available, but you're strongly encouraged to remove its' usage sooner
+	rather than later as it is scheduled for removal in CodeIgniter 3.1+.
+
 Pagination library 'anchor_class' setting
 =========================================
 
@@ -111,5 +137,5 @@ attribute to your anchors via the 'attributes' configuration setting. This inclu
 As a result of that, the 'anchor_class' setting is now deprecated and scheduled for removal in
 CodeIgniter 3.1+.
 
-.. note:: This setting is still available, but you're strongly encouraged to remove it's usage sooner
+.. note:: This setting is still available, but you're strongly encouraged to remove its' usage sooner
 	rather than later.
\ No newline at end of file