Source for file date.php

Documentation is available at date.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Date
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. /**
  13.  * JDate is a class that stores a date and provides logic to manipulate
  14.  * and render that date in a variety of formats.
  15.  *
  16.  * @property-read  string   $daysinmonth   t - Number of days in the given month.
  17.  * @property-read  string   $dayofweek     N - ISO-8601 numeric representation of the day of the week.
  18.  * @property-read  string   $dayofyear     z - The day of the year (starting from 0).
  19.  * @property-read  boolean  $isleapyear    L - Whether it's a leap year.
  20.  * @property-read  string   $day           d - Day of the month, 2 digits with leading zeros.
  21.  * @property-read  string   $hour          H - 24-hour format of an hour with leading zeros.
  22.  * @property-read  string   $minute        i - Minutes with leading zeros.
  23.  * @property-read  string   $second        s - Seconds with leading zeros.
  24.  * @property-read  string   $month         m - Numeric representation of a month, with leading zeros.
  25.  * @property-read  string   $ordinal       S - English ordinal suffix for the day of the month, 2 characters.
  26.  * @property-read  string   $week          W - Numeric representation of the day of the week.
  27.  * @property-read  string   $year          Y - A full numeric representation of a year, 4 digits.
  28.  *
  29.  * @package     Joomla.Platform
  30.  * @subpackage  Date
  31.  * @since       11.1
  32.  */
  33. class JDate extends DateTime
  34. {
  35.     const DAY_ABBR = "\x021\x03";
  36.     const DAY_NAME = "\x022\x03";
  37.     const MONTH_ABBR = "\x023\x03";
  38.     const MONTH_NAME = "\x024\x03";
  39.  
  40.     /**
  41.      * The format string to be applied when using the __toString() magic method.
  42.      *
  43.      * @var    string 
  44.      * @since  11.1
  45.      */
  46.     public static $format = 'Y-m-d H:i:s';
  47.  
  48.     /**
  49.      * Placeholder for a DateTimeZone object with GMT as the time zone.
  50.      *
  51.      * @var    object 
  52.      * @since  11.1
  53.      */
  54.     protected static $gmt;
  55.  
  56.     /**
  57.      * Placeholder for a DateTimeZone object with the default server
  58.      * time zone as the time zone.
  59.      *
  60.      * @var    object 
  61.      * @since  11.1
  62.      */
  63.     protected static $stz;
  64.  
  65.     /**
  66.      * The DateTimeZone object for usage in rending dates as strings.
  67.      *
  68.      * @var    DateTimeZone 
  69.      * @since  12.1
  70.      */
  71.     protected $tz;
  72.  
  73.     /**
  74.      * Constructor.
  75.      *
  76.      * @param   string  $date  String in a format accepted by strtotime(), defaults to "now".
  77.      * @param   mixed   $tz    Time zone to be used for the date. Might be a string or a DateTimeZone object.
  78.      *
  79.      * @since   11.1
  80.      */
  81.     public function __construct($date = 'now', $tz = null)
  82.     {
  83.         // Create the base GMT and server time zone objects.
  84.         if (empty(self::$gmt) || empty(self::$stz))
  85.         {
  86.             self::$gmt = new DateTimeZone('GMT');
  87.             self::$stz = new DateTimeZone(@date_default_timezone_get());
  88.         }
  89.  
  90.         // If the time zone object is not set, attempt to build it.
  91.         if (!($tz instanceof DateTimeZone))
  92.         {
  93.             if ($tz === null)
  94.             {
  95.                 $tz = self::$gmt;
  96.             }
  97.             elseif (is_string($tz))
  98.             {
  99.                 $tz = new DateTimeZone($tz);
  100.             }
  101.         }
  102.  
  103.         // If the date is numeric assume a unix timestamp and convert it.
  104.         date_default_timezone_set('UTC');
  105.         $date = is_numeric($date) ? date('c', $date) : $date;
  106.  
  107.         // Call the DateTime constructor.
  108.         parent::__construct($date, $tz);
  109.  
  110.         // Reset the timezone for 3rd party libraries/extension that does not use JDate
  111.         date_default_timezone_set(self::$stz->getName());
  112.  
  113.         // Set the timezone object for access later.
  114.         $this->tz = $tz;
  115.     }
  116.  
  117.     /**
  118.      * Magic method to access properties of the date given by class to the format method.
  119.      *
  120.      * @param   string  $name  The name of the property.
  121.      *
  122.      * @return  mixed   A value if the property name is valid, null otherwise.
  123.      *
  124.      * @since   11.1
  125.      */
  126.     public function __get($name)
  127.     {
  128.         $value = null;
  129.  
  130.         switch ($name)
  131.         {
  132.             case 'daysinmonth':
  133.                 $value = $this->format('t', true);
  134.                 break;
  135.  
  136.             case 'dayofweek':
  137.                 $value = $this->format('N', true);
  138.                 break;
  139.  
  140.             case 'dayofyear':
  141.                 $value = $this->format('z', true);
  142.                 break;
  143.  
  144.             case 'isleapyear':
  145.                 $value = (boolean) $this->format('L', true);
  146.                 break;
  147.  
  148.             case 'day':
  149.                 $value = $this->format('d', true);
  150.                 break;
  151.  
  152.             case 'hour':
  153.                 $value = $this->format('H', true);
  154.                 break;
  155.  
  156.             case 'minute':
  157.                 $value = $this->format('i', true);
  158.                 break;
  159.  
  160.             case 'second':
  161.                 $value = $this->format('s', true);
  162.                 break;
  163.  
  164.             case 'month':
  165.                 $value = $this->format('m', true);
  166.                 break;
  167.  
  168.             case 'ordinal':
  169.                 $value = $this->format('S', true);
  170.                 break;
  171.  
  172.             case 'week':
  173.                 $value = $this->format('W', true);
  174.                 break;
  175.  
  176.             case 'year':
  177.                 $value = $this->format('Y', true);
  178.                 break;
  179.  
  180.             default:
  181.                 $trace = debug_backtrace();
  182.                 trigger_error(
  183.                     'Undefined property via __get(): ' . $name . ' in ' . $trace[0]['file'] . ' on line ' . $trace[0]['line'],
  184.                     E_USER_NOTICE
  185.                 );
  186.         }
  187.  
  188.         return $value;
  189.     }
  190.  
  191.     /**
  192.      * Magic method to render the date object in the format specified in the public
  193.      * static member JDate::$format.
  194.      *
  195.      * @return  string  The date as a formatted string.
  196.      *
  197.      * @since   11.1
  198.      */
  199.     public function __toString()
  200.     {
  201.         return (string) parent::format(self::$format);
  202.     }
  203.  
  204.     /**
  205.      * Proxy for new JDate().
  206.      *
  207.      * @param   string  $date  String in a format accepted by strtotime(), defaults to "now".
  208.      * @param   mixed   $tz    Time zone to be used for the date.
  209.      *
  210.      * @return  JDate 
  211.      *
  212.      * @since   11.3
  213.      */
  214.     public static function getInstance($date = 'now', $tz = null)
  215.     {
  216.         return new JDate($date, $tz);
  217.     }
  218.  
  219.     /**
  220.      * Translates day of week number to a string.
  221.      *
  222.      * @param   integer  $day   The numeric day of the week.
  223.      * @param   boolean  $abbr  Return the abbreviated day string?
  224.      *
  225.      * @return  string  The day of the week.
  226.      *
  227.      * @since   11.1
  228.      */
  229.     public function dayToString($day, $abbr = false)
  230.     {
  231.         switch ($day)
  232.         {
  233.             case 0:
  234.                 return $abbr ? JText::_('SUN') : JText::_('SUNDAY');
  235.             case 1:
  236.                 return $abbr ? JText::_('MON') : JText::_('MONDAY');
  237.             case 2:
  238.                 return $abbr ? JText::_('TUE') : JText::_('TUESDAY');
  239.             case 3:
  240.                 return $abbr ? JText::_('WED') : JText::_('WEDNESDAY');
  241.             case 4:
  242.                 return $abbr ? JText::_('THU') : JText::_('THURSDAY');
  243.             case 5:
  244.                 return $abbr ? JText::_('FRI') : JText::_('FRIDAY');
  245.             case 6:
  246.                 return $abbr ? JText::_('SAT') : JText::_('SATURDAY');
  247.         }
  248.     }
  249.  
  250.     /**
  251.      * Gets the date as a formatted string in a local calendar.
  252.      *
  253.      * @param   string   $format     The date format specification string (see {@link PHP_MANUAL#date})
  254.      * @param   boolean  $local      True to return the date string in the local time zone, false to return it in GMT.
  255.      * @param   boolean  $translate  True to translate localised strings
  256.      *
  257.      * @return  string   The date string in the specified format format.
  258.      *
  259.      * @since   11.1
  260.      */
  261.     public function calendar($format, $local = false, $translate = true)
  262.     {
  263.         return $this->format($format, $local, $translate);
  264.     }
  265.  
  266.     /**
  267.      * Gets the date as a formatted string.
  268.      *
  269.      * @param   string   $format     The date format specification string (see {@link PHP_MANUAL#date})
  270.      * @param   boolean  $local      True to return the date string in the local time zone, false to return it in GMT.
  271.      * @param   boolean  $translate  True to translate localised strings
  272.      *
  273.      * @return  string   The date string in the specified format format.
  274.      *
  275.      * @since   11.1
  276.      */
  277.     public function format($format, $local = false, $translate = true)
  278.     {
  279.         if ($translate)
  280.         {
  281.             // Do string replacements for date format options that can be translated.
  282.             $format = preg_replace('/(^|[^\\\])D/', "\\1" . self::DAY_ABBR, $format);
  283.             $format = preg_replace('/(^|[^\\\])l/', "\\1" . self::DAY_NAME, $format);
  284.             $format = preg_replace('/(^|[^\\\])M/', "\\1" . self::MONTH_ABBR, $format);
  285.             $format = preg_replace('/(^|[^\\\])F/', "\\1" . self::MONTH_NAME, $format);
  286.         }
  287.  
  288.         // If the returned time should not be local use GMT.
  289.         if ($local == false)
  290.         {
  291.             parent::setTimezone(self::$gmt);
  292.         }
  293.  
  294.         // Format the date.
  295.         $return = parent::format($format);
  296.  
  297.         if ($translate)
  298.         {
  299.             // Manually modify the month and day strings in the formatted time.
  300.             if (strpos($return, self::DAY_ABBR) !== false)
  301.             {
  302.                 $return = str_replace(self::DAY_ABBR, $this->dayToString(parent::format('w'), true), $return);
  303.             }
  304.  
  305.             if (strpos($return, self::DAY_NAME) !== false)
  306.             {
  307.                 $return = str_replace(self::DAY_NAME, $this->dayToString(parent::format('w')), $return);
  308.             }
  309.  
  310.             if (strpos($return, self::MONTH_ABBR) !== false)
  311.             {
  312.                 $return = str_replace(self::MONTH_ABBR, $this->monthToString(parent::format('n'), true), $return);
  313.             }
  314.  
  315.             if (strpos($return, self::MONTH_NAME) !== false)
  316.             {
  317.                 $return = str_replace(self::MONTH_NAME, $this->monthToString(parent::format('n')), $return);
  318.             }
  319.         }
  320.  
  321.         if ($local == false)
  322.         {
  323.             parent::setTimezone($this->tz);
  324.         }
  325.  
  326.         return $return;
  327.     }
  328.  
  329.     /**
  330.      * Get the time offset from GMT in hours or seconds.
  331.      *
  332.      * @param   boolean  $hours  True to return the value in hours.
  333.      *
  334.      * @return  float  The time offset from GMT either in hours or in seconds.
  335.      *
  336.      * @since   11.1
  337.      */
  338.     public function getOffsetFromGMT($hours = false)
  339.     {
  340.         return (float) $hours ? ($this->tz->getOffset($this) / 3600) : $this->tz->getOffset($this);
  341.     }
  342.  
  343.     /**
  344.      * Translates month number to a string.
  345.      *
  346.      * @param   integer  $month  The numeric month of the year.
  347.      * @param   boolean  $abbr   If true, return the abbreviated month string
  348.      *
  349.      * @return  string  The month of the year.
  350.      *
  351.      * @since   11.1
  352.      */
  353.     public function monthToString($month, $abbr = false)
  354.     {
  355.         switch ($month)
  356.         {
  357.             case 1:
  358.                 return $abbr ? JText::_('JANUARY_SHORT') : JText::_('JANUARY');
  359.             case 2:
  360.                 return $abbr ? JText::_('FEBRUARY_SHORT') : JText::_('FEBRUARY');
  361.             case 3:
  362.                 return $abbr ? JText::_('MARCH_SHORT') : JText::_('MARCH');
  363.             case 4:
  364.                 return $abbr ? JText::_('APRIL_SHORT') : JText::_('APRIL');
  365.             case 5:
  366.                 return $abbr ? JText::_('MAY_SHORT') : JText::_('MAY');
  367.             case 6:
  368.                 return $abbr ? JText::_('JUNE_SHORT') : JText::_('JUNE');
  369.             case 7:
  370.                 return $abbr ? JText::_('JULY_SHORT') : JText::_('JULY');
  371.             case 8:
  372.                 return $abbr ? JText::_('AUGUST_SHORT') : JText::_('AUGUST');
  373.             case 9:
  374.                 return $abbr ? JText::_('SEPTEMBER_SHORT') : JText::_('SEPTEMBER');
  375.             case 10:
  376.                 return $abbr ? JText::_('OCTOBER_SHORT') : JText::_('OCTOBER');
  377.             case 11:
  378.                 return $abbr ? JText::_('NOVEMBER_SHORT') : JText::_('NOVEMBER');
  379.             case 12:
  380.                 return $abbr ? JText::_('DECEMBER_SHORT') : JText::_('DECEMBER');
  381.         }
  382.     }
  383.  
  384.     /**
  385.      * Method to wrap the setTimezone() function and set the internal time zone object.
  386.      *
  387.      * @param   DateTimeZone  $tz  The new DateTimeZone object.
  388.      *
  389.      * @return  JDate 
  390.      *
  391.      * @since   11.1
  392.      * @note    This method can't be type hinted due to a PHP bug: https://bugs.php.net/bug.php?id=61483
  393.      */
  394.     public function setTimezone($tz)
  395.     {
  396.         $this->tz = $tz;
  397.  
  398.         return parent::setTimezone($tz);
  399.     }
  400.  
  401.     /**
  402.      * Gets the date as an ISO 8601 string.  IETF RFC 3339 defines the ISO 8601 format
  403.      * and it can be found at the IETF Web site.
  404.      *
  405.      * @param   boolean  $local  True to return the date string in the local time zone, false to return it in GMT.
  406.      *
  407.      * @return  string  The date string in ISO 8601 format.
  408.      *
  409.      * @link    http://www.ietf.org/rfc/rfc3339.txt
  410.      * @since   11.1
  411.      */
  412.     public function toISO8601($local = false)
  413.     {
  414.         return $this->format(DateTime::RFC3339, $local, false);
  415.     }
  416.  
  417.     /**
  418.      * Gets the date as an SQL datetime string.
  419.      *
  420.      * @param   boolean          $local  True to return the date string in the local time zone, false to return it in GMT.
  421.      * @param   JDatabaseDriver  $db     The database driver or null to use JFactory::getDbo()
  422.      *
  423.      * @return  string     The date string in SQL datetime format.
  424.      *
  425.      * @link    http://dev.mysql.com/doc/refman/5.0/en/datetime.html
  426.      * @since   11.4
  427.      */
  428.     public function toSql($local = false, JDatabaseDriver $db = null)
  429.     {
  430.         if ($db === null)
  431.         {
  432.             $db = JFactory::getDbo();
  433.         }
  434.  
  435.         return $this->format($db->getDateFormat(), $local, false);
  436.     }
  437.  
  438.     /**
  439.      * Gets the date as an RFC 822 string.  IETF RFC 2822 supercedes RFC 822 and its definition
  440.      * can be found at the IETF Web site.
  441.      *
  442.      * @param   boolean  $local  True to return the date string in the local time zone, false to return it in GMT.
  443.      *
  444.      * @return  string   The date string in RFC 822 format.
  445.      *
  446.      * @link    http://www.ietf.org/rfc/rfc2822.txt
  447.      * @since   11.1
  448.      */
  449.     public function toRFC822($local = false)
  450.     {
  451.         return $this->format(DateTime::RFC2822, $local, false);
  452.     }
  453.  
  454.     /**
  455.      * Gets the date as UNIX time stamp.
  456.      *
  457.      * @return  integer  The date as a UNIX timestamp.
  458.      *
  459.      * @since   11.1
  460.      */
  461.     public function toUnix()
  462.     {
  463.         return (int) parent::format('U');
  464.     }
  465. }

Documentation generated on Tue, 19 Nov 2013 14:57:55 +0100 by phpDocumentor 1.4.3