diff options
Diffstat (limited to 'user_guide_src/source/helpers/date_helper.rst')
| -rw-r--r-- | user_guide_src/source/helpers/date_helper.rst | 464 |
1 files changed, 464 insertions, 0 deletions
diff --git a/user_guide_src/source/helpers/date_helper.rst b/user_guide_src/source/helpers/date_helper.rst new file mode 100644 index 000000000..e332a913f --- /dev/null +++ b/user_guide_src/source/helpers/date_helper.rst @@ -0,0 +1,464 @@ +########### +Date Helper +########### + +The Date Helper file contains functions that help you work with dates. + +.. contents:: Page Contents + +Loading this Helper +=================== + +This helper is loaded using the following code + +:: + + $this->load->helper('date'); + +The following functions are available: + +now() +===== + +Returns the current time as a Unix timestamp, referenced either to your +server's local time or any PHP suported timezone, based on the "time reference" +setting in your config file. If you do not intend to set your master time reference +to any other PHP suported timezone (which you'll typically do if you run a site that +lets each user set their own timezone settings) there is no benefit to using this +function over PHP's time() function. + +.. php:method:: now($timezone = NULL) + + :param string $timezone: The timezone you want to be returned + :returns: integer + +:: + echo now("Australia/Victoria"); + +If a timezone is not provided, it will return time() based on "time_reference" setting. + +mdate() +======= + +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. + +The benefit of doing dates this way is that you don't have to worry +about escaping any characters that are not date codes, as you would +normally have to do with the date() function. Example + +.. php:method:: mdate($datestr = '', $time = '') + + :param string $datestr: Date String + :param integer $time: time + :returns: integer + + +:: + + $datestring = "Year: %Y Month: %m Day: %d - %h:%i %a"; + $time = time(); + echo mdate($datestring, $time); + +If a timestamp is not included in the second parameter the current time +will be used. + +standard_date() +=============== + +Lets you generate a date string in one of several standardized formats. +Example + +.. php:method:: standard_date($fmt = 'DATE_RFC822', $time = '') + + :param string $fmt: the chosen format + :param string $time: Unix timestamp + :returns: string + +:: + + $format = 'DATE_RFC822'; + $time = time(); + echo standard_date($format, $time); + +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 +=============== ======================= ====================================== + +local_to_gmt() +============== + +Takes a Unix timestamp as input and returns it as GMT. + +.. php:method:: local_to_gmt($time = '') + + :param integer $time: Unix timestamp + :returns: string + +Example: + +:: + + $now = time(); + $gmt = local_to_gmt($now); + +gmt_to_local() +============== + +Takes a Unix timestamp (referenced to GMT) as input, and converts it to +a localized timestamp based on the timezone and Daylight Saving time +submitted. + +.. php:method:: gmt_to_local($time = '', $timezone = 'UTC', $dst = FALSE) + + :param integer $time: Unix timestamp + :param string $timezone: timezone + :param boolean $dst: whether DST is active + :returns: integer + +Example + +:: + + $timestamp = '1140153693'; + $timezone = 'UM8'; + $daylight_saving = TRUE; + echo gmt_to_local($timestamp, $timezone, $daylight_saving); + + +.. note:: For a list of timezones see the reference at the bottom of this page. + + +mysql_to_unix() +=============== + +Takes a MySQL Timestamp as input and returns it as Unix. + +.. php:method:: mysql_to_unix($time = '') + + :param integer $time: Unix timestamp + :returns: integer + +Example + +:: + + $mysql = '20061124092345'; + $unix = mysql_to_unix($mysql); + +unix_to_human() +=============== + +Takes a Unix timestamp as input and returns it in a human readable +format with this prototype + +.. php:method:: unix_to_human($time = '', $seconds = FALSE, $fmt = 'us') + + :param integer $time: Unix timestamp + :param boolean $seconds: whether to show seconds + :param string $fmt: format: us or euro + :returns: integer + +Example + +:: + + YYYY-MM-DD HH:MM:SS AM/PM + +This can be useful if you need to display a date in a form field for +submission. + +The time can be formatted with or without seconds, and it can be set to +European or US format. If only the timestamp is submitted it will return +the time without seconds formatted for the U.S. Examples + +:: + + $now = time(); + echo unix_to_human($now); // U.S. time, no seconds + echo unix_to_human($now, TRUE, 'us'); // U.S. time with seconds + echo unix_to_human($now, TRUE, 'eu'); // Euro time with seconds + +human_to_unix() +=============== + +The opposite of the above function. Takes a "human" time as input and +returns it as Unix. This function is useful if you accept "human" +formatted dates submitted via a form. Returns FALSE (boolean) if the +date string passed to it is not formatted as indicated above. + +.. php:method:: human_to_unix($datestr = '') + + :param integer $datestr: Date String + :returns: integer + +Example: + +:: + + $now = time(); + $human = unix_to_human($now); + $unix = human_to_unix($human); + +nice_date() +=========== + +This function can take a number poorly-formed date formats and convert +them into something useful. It also accepts well-formed dates. + +The function will return a Unix timestamp by default. You can, +optionally, pass a format string (the same type as the PHP date function +accepts) as the second parameter. + +.. php:method:: nice_date($bad_date = '', $format = FALSE) + + :param integer $bad_date: The terribly formatted date-like string + :param string $format: Date format to return (same as php date function) + :returns: string + +Example + +:: + + $bad_date = '199605'; + // Should Produce: 1996-05-01 + $better_date = nice_date($bad_date, 'Y-m-d'); + + $bad_date = '9-11-2001'; + // Should Produce: 2001-09-11 + $better_date = nice_date($bad_date, 'Y-m-d'); + +timespan() +========== + +Formats a unix timestamp so that is appears similar to this +:: + + 1 Year, 10 Months, 2 Weeks, 5 Days, 10 Hours, 16 Minutes + +The first parameter must contain a Unix timestamp. The second parameter +must contain a timestamp that is greater that the first timestamp. If +the second parameter empty, the current time will be used. The third +parameter is optional and limits the number of time units to display. +The most common purpose for this function is to show how much time has +elapsed from some point in time in the past to now. + +.. php:method:: timespan($seconds = 1, $time = '', $units = '') + + :param integer $seconds: a number of seconds + :param string $time: Unix timestamp + :param integer $units: a number of time units to display + :returns: string + +Example + +:: + + $post_date = '1079621429'; + $now = time(); + $units = 2; + echo timespan($post_date, $now, $units); + +.. note:: The text generated by this function is found in the following language + file: language/<your_lang>/date_lang.php + +days_in_month() +=============== + +Returns the number of days in a given month/year. Takes leap years into +account. + +.. php:method:: days_in_month($month = 0, $year = '') + + :param integer $month: a numeric month + :param integer $year: a numeric year + :returns: integer + +Example + +:: + + echo days_in_month(06, 2005); + +If the second parameter is empty, the current year will be used. + +timezones() +=========== + +Takes a timezone reference (for a list of valid timezones, see the +"Timezone Reference" below) and returns the number of hours offset from +UTC. + +.. php:method:: timezones($tz = '') + + :param string $tz: a numeric timezone + :returns: string + +Example + +:: + + echo timezones('UM5'); + + +This function is useful when used with `timezone_menu()`. + +timezone_menu() +=============== + +Generates a pull-down menu of timezones, like this one: + + +.. raw:: html + + <form action="#"> + <select name="timezones"> + <option value='UM12'>(UTC -12:00) Baker/Howland Island</option> + <option value='UM11'>(UTC -11:00) Samoa Time Zone, Niue</option> + <option value='UM10'>(UTC -10:00) Hawaii-Aleutian Standard Time, Cook Islands, Tahiti</option> + <option value='UM95'>(UTC -9:30) Marquesas Islands</option> + <option value='UM9'>(UTC -9:00) Alaska Standard Time, Gambier Islands</option> + <option value='UM8'>(UTC -8:00) Pacific Standard Time, Clipperton Island</option> + <option value='UM7'>(UTC -7:00) Mountain Standard Time</option> + <option value='UM6'>(UTC -6:00) Central Standard Time</option> + <option value='UM5'>(UTC -5:00) Eastern Standard Time, Western Caribbean Standard Time</option> + <option value='UM45'>(UTC -4:30) Venezuelan Standard Time</option> + <option value='UM4'>(UTC -4:00) Atlantic Standard Time, Eastern Caribbean Standard Time</option> + <option value='UM35'>(UTC -3:30) Newfoundland Standard Time</option> + <option value='UM3'>(UTC -3:00) Argentina, Brazil, French Guiana, Uruguay</option> + <option value='UM2'>(UTC -2:00) South Georgia/South Sandwich Islands</option> + <option value='UM1'>(UTC -1:00) Azores, Cape Verde Islands</option> + <option value='UTC' selected='selected'>(UTC) Greenwich Mean Time, Western European Time</option> + <option value='UP1'>(UTC +1:00) Central European Time, West Africa Time</option> + <option value='UP2'>(UTC +2:00) Central Africa Time, Eastern European Time, Kaliningrad Time</option> + <option value='UP3'>(UTC +3:00) Moscow Time, East Africa Time</option> + <option value='UP35'>(UTC +3:30) Iran Standard Time</option> + <option value='UP4'>(UTC +4:00) Azerbaijan Standard Time, Samara Time</option> + <option value='UP45'>(UTC +4:30) Afghanistan</option> + <option value='UP5'>(UTC +5:00) Pakistan Standard Time, Yekaterinburg Time</option> + <option value='UP55'>(UTC +5:30) Indian Standard Time, Sri Lanka Time</option> + <option value='UP575'>(UTC +5:45) Nepal Time</option> + <option value='UP6'>(UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time</option> + <option value='UP65'>(UTC +6:30) Cocos Islands, Myanmar</option> + <option value='UP7'>(UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam</option> + <option value='UP8'>(UTC +8:00) Australian Western Standard Time, Beijing Time, Irkutsk Time</option> + <option value='UP875'>(UTC +8:45) Australian Central Western Standard Time</option> + <option value='UP9'>(UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk Time</option> + <option value='UP95'>(UTC +9:30) Australian Central Standard Time</option> + <option value='UP10'>(UTC +10:00) Australian Eastern Standard Time, Vladivostok Time</option> + <option value='UP105'>(UTC +10:30) Lord Howe Island</option> + <option value='UP11'>(UTC +11:00) Magadan Time, Solomon Islands, Vanuatu</option> + <option value='UP115'>(UTC +11:30) Norfolk Island</option> + <option value='UP12'>(UTC +12:00) Fiji, Gilbert Islands, Kamchatka Time, New Zealand Standard Time</option> + <option value='UP1275'>(UTC +12:45) Chatham Islands Standard Time</option> + <option value='UP13'>(UTC +13:00) Phoenix Islands Time, Tonga</option> + <option value='UP14'>(UTC +14:00) Line Islands</option> + </select> + </form> + + +This menu is useful if you run a membership site in which your users are +allowed to set their local timezone value. + +The first parameter lets you set the "selected" state of the menu. For +example, to set Pacific time as the default you will do this + +.. php:method:: timezone_menu($default = 'UTC', $class = '', $name = 'timezones', $attributes = '') + + :param string $default: timezone + :param string $class: classname + :param string $name: menu name + :param mixed $attributes: attributes + :returns: string + +Example: + +:: + + echo timezone_menu('UM8'); + +Please see the timezone reference below to see the values of this menu. + +The second parameter lets you set a CSS class name for the menu. + +The fourth parameter lets you set one or more attributes on the generated select tag. + +.. note:: The text contained in the menu is found in the following + language file: `language/<your_lang>/date_lang.php` + + +Timezone Reference +================== + +The following table indicates each timezone and its location. + +Note some of the location lists have been abridged for clarity and formatting. + +=========== ===================================================================== +Time Zone Location +=========== ===================================================================== +UM2 (UTC - 12:00) Baker/Howland Island +UM1 (UTC - 11:00) Samoa Time Zone, Niue +UM0 (UTC - 10:00) Hawaii-Aleutian Standard Time, Cook Islands +UM95 (UTC - 09:30) Marquesas Islands +UM9 (UTC - 09:00) Alaska Standard Time, Gambier Islands +UM8 (UTC - 08:00) Pacific Standard Time, Clipperton Island +UM7 (UTC - 11:00) Mountain Standard Time +UM6 (UTC - 06:00) Central Standard Time +UM5 (UTC - 05:00) Eastern Standard Time, Western Caribbean +UM45 (UTC - 04:30) Venezuelan Standard Time +UM4 (UTC - 04:00) Atlantic Standard Time, Eastern Caribbean +UM35 (UTC - 03:30) Newfoundland Standard Time +UM3 (UTC - 03:00) Argentina, Brazil, French Guiana, Uruguay +UM2 (UTC - 02:00) South Georgia/South Sandwich Islands +UM (UTC -1:00) Azores, Cape Verde Islands +UTC (UTC) Greenwich Mean Time, Western European Time +UP1 (UTC +1:00) Central European Time, West Africa Time +UP2 (UTC +2:00) Central Africa Time, Eastern European Time +UP3 (UTC +3:00) Moscow Time, East Africa Time +UP35 (UTC +3:30) Iran Standard Time +UP4 (UTC +4:00) Azerbaijan Standard Time, Samara Time +UP45 (UTC +4:30) Afghanistan +UP5 (UTC +5:00) Pakistan Standard Time, Yekaterinburg Time +UP55 (UTC +5:30) Indian Standard Time, Sri Lanka Time +UP575 (UTC +5:45) Nepal Time +UP6 (UTC +6:00) Bangladesh Standard Time, Bhutan Time, Omsk Time +UP65 (UTC +6:30) Cocos Islands, Myanmar +UP7 (UTC +7:00) Krasnoyarsk Time, Cambodia, Laos, Thailand, Vietnam +UP8 (UTC +8:00) Australian Western Standard Time, Beijing Time +UP875 (UTC +8:45) Australian Central Western Standard Time +UP9 (UTC +9:00) Japan Standard Time, Korea Standard Time, Yakutsk +UP95 (UTC +9:30) Australian Central Standard Time +UP10 (UTC +10:00) Australian Eastern Standard Time, Vladivostok Time +UP105 (UTC +10:30) Lord Howe Island +UP11 (UTC +11:00) Magadan Time, Solomon Islands, Vanuatu +UP115 (UTC +11:30) Norfolk Island +UP12 (UTC +12:00) Fiji, Gilbert Islands, Kamchatka, New Zealand +UP1275 (UTC +12:45) Chatham Islands Standard Time +UP1 (UTC +13:00) Phoenix Islands Time, Tonga +UP14 (UTC +14:00) Line Islands +=========== =====================================================================
\ No newline at end of file |