You are here

Home » API reference » Datex 7.2 » datex_api.class.inc

abstract class DatexObject in Datex 7.2

Same name and namespace in other branches
  1. 7 datex_api/datex_api_classes.inc \DatexObject

Base class for localized DateTime.

Hierarchy

Expanded class hierarchy of DatexObject

File

datex_api/datex_api.class.inc, line 116
Provides an API to work with dates.

View source 
abstract class DatexObject extends DateTime {

  /**
   * Number of days in each Gregorian month. Leap year is not counted.
   */
  protected static $daysInGregorianMonth = array(
    31,
    28,
    31,
    30,
    31,
    30,
    31,
    31,
    30,
    31,
    30,
    31,
  );

  /**
   * Default format string.
   */
  protected $formatString;

  /**
   * IntlDateFormatter instance used by object instance.
   *
   * @TODO share with objects.
   */
  protected $intlFormatter;

  /**
   * Whether to use PHP-Intl or not.
   */
  protected $useINTL = DATEX_USE_INTL;

  /**
   * Result of formats handled by extended class.
   */
  protected $calendarFormats = array();

  /**
   * Localized year value.
   */
  protected $year;

  /**
   * Localized month value.
   */
  protected $month;

  /**
   * Localized day value.
   */
  protected $day;

  /**
   * Constructor for DatexObject.
   *
   * @param mixed $datetime
   *   For list of accepted values see objectFromDate().
   * @param mixed $tz
   *   DateTimeZone to use, Can be DateTimeZone object or name string of it.
   * @param string $format
   *   Default format string.
   * @param bool $use_intl
   *   Whether to use PHP-Intl or not.
   */
  public function __construct($datetime = NULL, $tz = NULL, $format = '', $use_intl = DATEX_USE_INTL) {
    parent::__construct();
    $this
      ->setUseINTL($use_intl);
    $this
      ->setDatetime($datetime, $tz);
    $this
      ->setFormat($format);
    return $this;
  }

  /**
   * Magic Function toString.
   */
  public function __toString() {
    return $this
      ->format();
  }

  /**
   * Determines wether PECL package PHP-Intl is available or not.
   */
  public static function hasINTL() {
    return class_exists('IntlDateFormatter');
  }

  /**
   * Set whether to use PHP-Intl or not.
   *
   * Checks and makes sure PHP-Intl is available.
   */
  public function setUseINTL($use = NULL) {
    if (!$this
      ->hasINTL()) {
      $this->useINTL = FALSE;
      return;
    }
    if ($use || $use === NULL && DATEX_USE_INTL) {
      $this
        ->setIntlArgs();
      $this->useINTL = TRUE;
      $this
        ->createINTLFormatter($this
        ->getTimezone());
    }
    else {
      $this->useINTL = FALSE;
    }
    return $this->useINTL;
  }

  /**
   * Makes sure a tz is object, Not string ID of it.
   */
  public static function getTzObject($tz = NULL) {
    return is_string($tz) ? new DateTimeZone($tz) : $tz;
  }

  /**
   * Makes sure $tz is string, Not tz object.
   */
  public static function getTzString($tz) {
    return $tz instanceof DateTimeZone ? $tz
      ->getName() : $tz;
  }

  /**
   * Similar to DateTime::format().
   *
   * If format is not given internal format string set by constructor will be
   * used.
   */
  public function format($format = NULL) {
    if ($format === NULL) {
      $format = $this->formatString;
    }
    return $this->useINTL ? $this
      ->formatINTL($format) : $this
      ->formatPHP($format);
  }

  /**
   * Set date-time of object instance by extracting timestamp from given date.
   *
   * Also calls conversion methods so internal values are set.
   */
  public function setDatetime($datetime, $tz = NULL) {
    $this
      ->checkSetTimezone($tz);
    $date = $this
      ->objectFromDate($datetime);
    $this
      ->setTimestamp($date
      ->getTimestamp());
    return $this;
  }

  /**
   * Same as DateTime::setTimestamp but also resets the object.
   */
  public function setTimestamp($timestamp) {
    parent::setTimestamp($timestamp);
    $this
      ->reset();
  }

  /**
   * Set date-time of object instance by extracting timestamp from given date.
   *
   * Treat datetime as a Gregorian date.
   */
  public function xsetDatetime($datetime, $tz = NULL) {
    $this
      ->checkSetTimezone($tz);
    $date = $this
      ->xobjectFromDate($datetime);
    $this
      ->setTimestamp($date
      ->getTimestamp());
    return $this;
  }

  /**
   * Same as DateTime::setDate().
   */
  public function setDate($year = NULL, $month = NULL, $day = NULL) {
    list($year, $month, $day) = $this
      ->toGregorian($year, $month, $day);
    $this
      ->xsetDate($year, $month, $day);
    return $this;
  }

  /**
   * Set default format string of object.
   */
  public function setFormat($format) {
    $this->formatString = $format;
    return $this;
  }

  /**
   * Returns format string set by setFormat.
   */
  public function getFormat() {
    return $this->formatString;
  }

  /**
   * Sets Time Zone of internal date object.
   *
   * Accepts a DateTimeZone Object or an string representing a timezone.
   */
  public function setTimezone($timezone) {
    $timezone = $this
      ->getTzObject($timezone);
    parent::setTimezone($timezone);
    $this
      ->reset();
    return $this;
  }

  /**
   * Check to see if given timezone is not NULL, Then if it's so, set it.
   */
  protected function checkSetTimezone($tz) {
    if ($tz) {
      $this
        ->setTimezone($tz);
    }
    return $this;
  }

  /**
   * Same as DateTime::format().
   */
  public function xformat($format = NULL) {
    if ($format === NULL) {
      $format = $this->formatString;
    }
    return parent::format($format);
  }

  /**
   * Same as DateTime::setDate().
   */
  public function xsetDate($year, $month, $day) {
    return parent::setDate($year, $month, $day);
    $this
      ->reset();
    return $this;
  }

  /**
   * When new date or time is set on object, This method must be called.
   *
   * Gives a chance to extended classes to recalculate converted date from new
   * date.
   */
  public function reset($reset_datetime = NULL) {

    // If no timestamp, Then just recalculate date and set timezone.
    if ($reset_datetime !== NULL) {
      $this
        ->setTimestamp(time());
    }
    $this->tzOffset = $this
      ->xformat('Z');
    $this
      ->setConvert();
    $this
      ->setIsLeap();
    return $this;
  }

  /**
   * Returns an object containing first day of month.
   */
  public function monthFirstDay() {
    $date = clone $this;
    $date
      ->setDate(NULL, NULL, 1);
    return $date;
  }

  /**
   * Returns an object containing last day of month.
   */
  public function monthLastDay() {
    $date = clone $this;
    $date
      ->setDate(NULL, NULL, $date
      ->format('t'));
    return $date;
  }

  /**
   * Returns this date object granularities, put in an array.
   */
  public function toArray() {
    return array(
      'year' => $this
        ->format('Y'),
      'month' => $this
        ->format('n'),
      'day' => $this
        ->format('j'),
      'hour' => $this
        ->format('H'),
      'minute' => $this
        ->format('i'),
      'second' => $this
        ->format('s'),
      'timezone' => $this
        ->format('e'),
    );
  }

  /**
   * Returns amount of time difference to another date object
   *
   * @TODO properly implement.
   */
  public function difference(DatexObject $date2_in, $measure = 'seconds', $absolute = TRUE) {

    // Create cloned objects or original dates will be impacted by the
    // date_modify() operations done in this code.
    $date1 = clone $this;
    $date2 = clone $date2_in;
    $diff = $date2
      ->format('U') - $date1
      ->format('U');
    if ($diff == 0) {
      return 0;
    }
    elseif ($diff < 0 && $absolute) {

      // Make sure $date1 is the smaller date.
      $temp = $date2;
      $date2 = $date1;
      $date1 = $temp;
      $diff = $date2
        ->format('U') - $date1
        ->format('U');
    }
    $year_diff = intval($date2
      ->format('Y') - $date1
      ->format('Y'));
    switch ($measure) {
      case 'seconds':
        return $diff;
      case 'minutes':
        return $diff / 60;
      case 'hours':
        return $diff / 3600;
      case 'years':
        return $year_diff;
      case 'months':
        $item1 = $date1
          ->format('n');
        $item2 = $date2
          ->format('n');
        if ($year_diff == 0) {
          return intval($item2 - $item1);
        }
        else {
          $item_diff = 12 - $item1;
          $item_diff += intval(($year_diff - 1) * 12);
          return $item_diff + $item2;
        }
        break;
      case 'days':
        break;
        $item1 = $date1
          ->format('z');
        $item2 = $date2
          ->format('z');
        if ($year_diff == 0) {
          return intval($item2 - $item1);
        }
        else {
          $item_diff = date_days_in_year($date1) - $item1;
          for ($i = 1; $i < $year_diff; $i++) {
            date_modify($date1, '+1 year');
            $item_diff += date_days_in_year($date1);
          }
          return $item_diff + $item2;
        }
        break;
      case 'weeks':
      default:
        break;
    }
    return NULL;
  }

  /**
   * Same as DatexObject toArray but in Gregorian format.
   */
  public function xtoArray() {
    return array(
      'year' => $this
        ->xformat('Y'),
      'month' => $this
        ->xformat('n'),
      'day' => $this
        ->xformat('j'),
      'hour' => $this
        ->xformat('H'),
      'minute' => $this
        ->xformat('i'),
      'second' => $this
        ->xformat('s'),
      'timezone' => $this
        ->xformat('e'),
    );
  }

  /**
   * Converts date format string (like 'Y-m-d') to it's PHP-Intl equivilant.
   */
  public static function phpToIntl($format) {
    static $format_map = array(
      'd' => 'dd',
      'D' => 'EEE',
      'j' => 'd',
      'l' => 'EEEE',
      'N' => 'e',
      'S' => 'LLLL',
      'w' => '',
      'z' => 'D',
      'W' => 'w',
      'm' => 'MM',
      'M' => 'MMM',
      'F' => 'MMMM',
      'n' => 'M',
      't' => '',
      'L' => '',
      'o' => 'yyyy',
      'y' => 'yy',
      'Y' => 'YYYY',
      'a' => 'a',
      'A' => 'a',
      'B' => '',
      'g' => 'h',
      'G' => 'H',
      'h' => 'hh',
      'H' => 'HH',
      'i' => 'mm',
      's' => 'ss',
      'u' => 'SSSSSS',
      'e' => 'z',
      'I' => '',
      'O' => 'Z',
      'P' => 'ZZZZ',
      'T' => 'v',
      'Z' => '',
      'c' => '',
      'r' => '',
      'U' => '',
      ' ' => ' ',
      '-' => '-',
      '.' => '.',
      '-' => '-',
      ':' => ':',
    );
    $replace_pattern = '/[^ \\:\\-\\/\\.\\\\dDjlNSwzWmMFntLoyYaABgGhHisueIOPTZcrU]/';
    return strtr(preg_replace($replace_pattern, '', $format), $format_map);
  }

  /**
   * Format datetime using PHP-Intl.
   */
  protected function formatINTL($format) {
    $this->intlFormatter
      ->setPattern($this
      ->phpToIntl($format));
    $date = $this->intlFormatter
      ->format($this
      ->getTimestamp());

    // Replace localized number charachters with english equivalant.
    // @TODO check to see if Intl has support of this by itself?
    return self::decor($date, FALSE);
  }

  /**
   * Creates a DateTime object containing date extracted from $date.
   */
  public function xobjectFromDate($date = NULL, $tz = NULL) {
    if (is_object($date)) {
      $date = clone $date;
    }
    else {
      if (is_numeric($date)) {
        $date = '@' . $date;
      }
      elseif (is_array($date)) {
        $now = getdate();
        $year = isset($date['year']) ? intval($date['year']) : $now['year'];
        $month = isset($date['month']) ? intval($date['month']) : $now['mon'];
        $day = isset($date['day']) ? intval($date['day']) : $now['mday'];
        $hour = isset($date['hour']) ? intval($date['hour']) : $now['hours'];
        $minute = isset($date['minute']) ? intval($date['minute']) : $now['minutes'];
        $second = isset($date['second']) ? intval($date['second']) : $now['seconds'];
        $date = '@' . mktime($hour, $minute, $second, $month, $day, $year);
      }
      elseif ($date == NULL) {
        $date = 'now';
      }
      $date = new DateTime($date);
    }

    // For anyone reading this comment: Passing a DateTimeZone to datetime
    // constructor has no effect on it! You MUST use setTimezone to set a
    // tz on the stupid object.
    // Tested on PHP 5.4.15 (built: May 12 2013 13:11:23) Archlinux.
    if (isset($tz)) {
      $tz = $this
        ->getTzObject($tz);
      $date
        ->setTimeZone($tz);
    }
    return $date;
  }

  /**
   * Created datex object from a localized date.
   *
   * The only way to create an object from localized date is using an array,
   * Other type of dates have no difference in localized format such as
   * timestamp. String are not supported yet till parser() is fully
   * implemented.
   */
  public function objectFromDate($date, $tz = NULL) {
    if (is_array($date)) {
      foreach (array(
        'year',
        'month',
        'day',
      ) as $name) {
        if (!isset($date[$name])) {
          $date[$name] = 0;
        }
      }
      list($date['year'], $date['month'], $date['day']) = $this
        ->toGregorian($date['year'], $date['month'], $date['day']);
    }
    return $this
      ->xobjectFromDate($date, $tz);
  }

  /**
   * Create an IntlDateFormatter fot this object.
   */
  protected function createINTLFormatter($tz = NULL) {
    $args = $this->intlArgs;
    if (!$tz) {
      $tz = date_default_timezone_get();
    }
    $this->intlFormatter = new IntlDateFormatter($args[0], $args[1], $args[2], $this
      ->getTzString($tz), $args[3]);
  }

  /**
   * Use php to format date
   */
  protected function formatPHP($format) {
    static $t = FALSE;
    if (!$t) {
      $t = _datex_get_translator();
    }
    $names = $this
      ->getInfo('names');
    $monthDays = $this
      ->getInfo('month_days');
    $this
      ->setConvert();
    $this
      ->setIsLeap();

    // Should contain N, w, W, z, S, M,
    $this
      ->setCalendarFormats();
    $ampm = $this
      ->xformat('a');

    // A series of calls to str replace can not be used since format may
    // contain \ charachter which should not be replaced.
    $formatted = '';
    for ($i = 0; $i < strlen($format); $i++) {
      $f = $format[$i];

      // If extended class wants to override some formats, It should put it
      // in here.
      if (isset($this->calendarFormats[$f])) {
        $formatted .= $this->calendarFormats[$f];
      }
      else {
        switch ($f) {
          case '\\':
            $date .= $format[++$i];
          case 'd':
            $formatted .= sprintf('%02d', $this->day);
            break;
          case 'q':
            $formatted .= $t($names['day_abbr'][$this->dayOfWeek]);
            break;
          case 'D':
            $formatted .= $t($names['day_abbr_short'][$this->dayOfWeek]);
            break;
          case 'j':
            $formatted .= intval($this->day);
            break;
          case 'l':
            $formatted .= $t($names['day'][$this->dayOfWeek]);
            break;
          case 'S':
            $formatted .= $t($names['order'][$this->day - 1]);
            break;
          case 'W':
            $value_w = strval(ceil($this->dayOfYear / 7));
            $formatted = $formatted . $value_w;
            break;
          case 'z':
            $formatted = $this->dayOfYear;
            break;
          case 'M':
          case 'F':
            $formatted .= $t($names['months'][$this->month - 1]);
            break;
          case 'm':
            $formatted .= sprintf('%02d', $this->month);
            break;
          case 'n':
            $formatted .= intval($this->month);
            break;
          case 't':
            $formatted .= $this->isLeap && $this->month == 12 ? 30 : $month_days[$this->month - 1];
            break;
          case 'L':
            $formatted .= $this->isLeap ? 1 : 0;
            break;
          case 'Y':
            $formatted .= $this->year;
            break;
          case 'y':
            $formatted .= substr($this->year, 2, 4);
            break;
          case 'o':
            $formatted .= $this->year;
            break;
          case 'a':
            $formatted .= $t($names['ampm'][$ampm]);
            break;
          case 'A':
            $formatted .= $t($names['ampm'][$ampm]);
            break;
          case 'c':
            $formatted .= "{$this->year} - {$this->month} - {$this->day}T";
            $formatted .= $this
              ->xformat('H:i:sP');
            break;
          case 'r':
            $formatted .= $t($names['day_abbr'][$fw]) . ', ' . $cd . ' ' . $t($names['months'][$cm]) . ' ' . $cy . $this
              ->xformat('H:i:s P');
            break;
          default:

            // Any format charachter not handled by Datex or extended class,
            // Will be handled by DateTime.
            $formatted .= ctype_alpha($format[$i]) ? $this
              ->xformat($format[$i]) : $format[$i];
            break;
        }
      }
    }
    return $formatted;
  }

  /**
   * Call calendarFormat() on extended classes but hide storage details.
   *
   * Get extended classes opportunity to format date formats which Datex should
   * not handle.
   */
  protected function setCalendarFormats() {
    $this->calendarFormats = $this
      ->calendarFormat();
  }

  /**
   * Transliterate English numbers to localized numbers and vice versa.
   */
  public function decor($str, $decorate = FALSE) {
    static $en = array(
      0,
      1,
      2,
      3,
      4,
      5,
      6,
      7,
      8,
      9,
    );
    $localized = $this
      ->getInfo('numbers');
    return $decorate ? str_replace($en, $localized, $str) : str_replace($localized, $en, $str);
  }

  /**
   * Call extended class convert and set converted date on object instance,
   */
  protected function setConvert() {
    list($this->year, $this->month, $this->day, $this->hour, $this->minute, $this->second, $this->dayOfYear, $this->dayOfWeek) = $this
      ->convert($this
      ->xformat('U'), $this->tzOffset);
    return $this;
  }

  /**
   * Call extended class isLeap and set isLeap on object instance,
   */
  protected function setIsLeap() {
    $this->isLeap = $this
      ->isLeap($this->year);
    return $this;
  }

  /**
   * A bad method which set's day directly.
   *
   * A must have for when dealing with dates which have been stored as
   * timestamp according to a format without month but with year and
   * day.
   */
  public function setDayBad($day) {
    $this->day = $day;
    return $this;
  }

  /**
   * Generate arguments passed to INTL formatter.
   */
  public function setIntlArgs($a1 = NULL, $a2 = NULL, $a3 = NULL, $a4 = NULL) {
    $default_intl_args = $this
      ->getIntlArgs();
    $this->intlArgs = array();
    foreach (func_get_args() as $index => $arg) {
      if ($arg === NULL) {
        $this->intlArgs[$index] = $default_intl_args[$index];
      }
      else {
        $this->intlArgs[$index] = $arg;
      }
    }
    $this->intlArgs = $default_intl_args;
  }

  /**
   * Names of date granularities.
   */
  public static function granularityNames() {
    return array(
      'year',
      'month',
      'day',
      'hour',
      'minute',
      'second',
    );
  }

  /**
   * Helper method to make up for time difference if some granularites are
   * missing.
   */
  public function fixByGranularities(array $granularities) {
    $this
      ->setTimestamp($this
      ->getTimestamp() + $this
      ->fixMissingGranularities($granularities));
  }

}

Members

Namesort descending Modifiers Type Description Overrides
DatexObject::$calendarFormats protected property Result of formats handled by extended class.
DatexObject::$day protected property Localized day value.
DatexObject::$daysInGregorianMonth protected static property Number of days in each Gregorian month. Leap year is not counted.
DatexObject::$formatString protected property Default format string.
DatexObject::$intlFormatter protected property IntlDateFormatter instance used by object instance.
DatexObject::$month protected property Localized month value.
DatexObject::$useINTL protected property Whether to use PHP-Intl or not.
DatexObject::$year protected property Localized year value.
DatexObject::checkSetTimezone protected function Check to see if given timezone is not NULL, Then if it's so, set it.
DatexObject::createINTLFormatter protected function Create an IntlDateFormatter fot this object.
DatexObject::decor public function Transliterate English numbers to localized numbers and vice versa.
DatexObject::difference public function Returns amount of time difference to another date object
DatexObject::fixByGranularities public function Helper method to make up for time difference if some granularites are missing.
DatexObject::format public function Similar to DateTime::format().
DatexObject::formatINTL protected function Format datetime using PHP-Intl.
DatexObject::formatPHP protected function Use php to format date
DatexObject::getFormat public function Returns format string set by setFormat.
DatexObject::getTzObject public static function Makes sure a tz is object, Not string ID of it.
DatexObject::getTzString public static function Makes sure $tz is string, Not tz object.
DatexObject::granularityNames public static function Names of date granularities.
DatexObject::hasINTL public static function Determines wether PECL package PHP-Intl is available or not.
DatexObject::monthFirstDay public function Returns an object containing first day of month.
DatexObject::monthLastDay public function Returns an object containing last day of month.
DatexObject::objectFromDate public function Created datex object from a localized date.
DatexObject::phpToIntl public static function Converts date format string (like 'Y-m-d') to it's PHP-Intl equivilant.
DatexObject::reset public function When new date or time is set on object, This method must be called.
DatexObject::setCalendarFormats protected function Call calendarFormat() on extended classes but hide storage details.
DatexObject::setConvert protected function Call extended class convert and set converted date on object instance,
DatexObject::setDate public function Same as DateTime::setDate().
DatexObject::setDatetime public function Set date-time of object instance by extracting timestamp from given date.
DatexObject::setDayBad public function A bad method which set's day directly.
DatexObject::setFormat public function Set default format string of object.
DatexObject::setIntlArgs public function Generate arguments passed to INTL formatter.
DatexObject::setIsLeap protected function Call extended class isLeap and set isLeap on object instance,
DatexObject::setTimestamp public function Same as DateTime::setTimestamp but also resets the object.
DatexObject::setTimezone public function Sets Time Zone of internal date object.
DatexObject::setUseINTL public function Set whether to use PHP-Intl or not.
DatexObject::toArray public function Returns this date object granularities, put in an array.
DatexObject::xformat public function Same as DateTime::format().
DatexObject::xobjectFromDate public function Creates a DateTime object containing date extracted from $date.
DatexObject::xsetDate public function Same as DateTime::setDate().
DatexObject::xsetDatetime public function Set date-time of object instance by extracting timestamp from given date.
DatexObject::xtoArray public function Same as DatexObject toArray but in Gregorian format.
DatexObject::__construct public function Constructor for DatexObject.
DatexObject::__toString public function Magic Function toString.