EDTFUtils.php

<?php

namespace Drupal\controlled_access_terms;

/**
 * Utility functions for working with Extended Date Time Format.
 */
class EDTFUtils {

  // EDTF Date Parse REGEX Array Positions.
  const DATE_PARSE_REGEX       = '/^([%\?~])?(Y?(-?[\dX]+)(E\d)?(S\d)?)([%\?~])?-?([%\?~])?([\dX]{2})?([%\?~])?-?([%\?~])?([\dX]{2})?([%\?~])?$/';
  const FULL_MATCH             = 0;
  const QUALIFIER_YEAR_ONLY    = 1;
  const YEAR_FULL              = 2;
  const YEAR_BASE              = 3;
  const YEAR_EXPONENT          = 4;
  const YEAR_SIGNIFICANT_DIGIT = 5;
  const QUALIFIER_YEAR         = 6;
  const QUALIFIER_MONTH_ONLY   = 7;
  const MONTH                  = 8;
  const QUALIFIER_MONTH        = 9;
  const QUALIFIER_DAY_ONLY     = 10;
  const DAY                    = 11;
  const QUALIFIER_DAY          = 12;

  /**
   * Month/Season to text map.
   *
   * @var array
   */
  const MONTHS_MAP = [
    '01' => ['mmm' => 'Jan', 'mmmm' => 'January'],
    '02' => ['mmm' => 'Feb', 'mmmm' => 'February'],
    '03' => ['mmm' => 'Mar', 'mmmm' => 'March'],
    '04' => ['mmm' => 'Apr', 'mmmm' => 'April'],
    '05' => ['mmm' => 'May', 'mmmm' => 'May'],
    '06' => ['mmm' => 'Jun', 'mmmm' => 'June'],
    '07' => ['mmm' => 'Jul', 'mmmm' => 'July'],
    '08' => ['mmm' => 'Aug', 'mmmm' => 'August'],
    '09' => ['mmm' => 'Sep', 'mmmm' => 'September'],
    '10' => ['mmm' => 'Oct', 'mmmm' => 'October'],
    '11' => ['mmm' => 'Nov', 'mmmm' => 'November'],
    '12' => ['mmm' => 'Dec', 'mmmm' => 'December'],
    '21' => ['mmm' => 'Spr', 'mmmm' => 'Spring'],
    '22' => ['mmm' => 'Sum', 'mmmm' => 'Summer'],
    '23' => ['mmm' => 'Aut', 'mmmm' => 'Autumn'],
    '24' => ['mmm' => 'Win', 'mmmm' => 'Winter'],
    '25' => ['mmm' => 'Spr', 'mmmm' => 'Spring - Northern Hemisphere'],
    '26' => ['mmm' => 'Sum', 'mmmm' => 'Summer - Northern Hemisphere'],
    '27' => ['mmm' => 'Aut', 'mmmm' => 'Autumn - Northern Hemisphere'],
    '28' => ['mmm' => 'Win', 'mmmm' => 'Winter - Northern Hemisphere'],
    '29' => ['mmm' => 'Spr', 'mmmm' => 'Spring - Southern Hemisphere'],
    '30' => ['mmm' => 'Sum', 'mmmm' => 'Summer - Southern Hemisphere'],
    '31' => ['mmm' => 'Aut', 'mmmm' => 'Autumn - Southern Hemisphere'],
    '32' => ['mmm' => 'Win', 'mmmm' => 'Winter - Southern Hemisphere'],
    '33' => ['mmm' => 'Q1', 'mmmm' => 'Quarter 1'],
    '34' => ['mmm' => 'Q2', 'mmmm' => 'Quarter 2'],
    '35' => ['mmm' => 'Q3', 'mmmm' => 'Quarter 3'],
    '36' => ['mmm' => 'Q4', 'mmmm' => 'Quarter 4'],
    // I'm making up the rest of these abbreviations
    // because I can't find standardized ones.
    '37' => ['mmm' => 'Quad1', 'mmmm' => 'Quadrimester 1'],
    '38' => ['mmm' => 'Quad2', 'mmmm' => 'Quadrimester 2'],
    '39' => ['mmm' => 'Quad3', 'mmmm' => 'Quadrimester 3'],
    '40' => ['mmm' => 'Sem1', 'mmmm' => 'Semestral 1'],
    '41' => ['mmm' => 'Sem2', 'mmmm' => 'Semestral 2'],
  ];

  const SEASONS_MAP = [
    // Northern Hemisphere bias for 21-24.
    '21' => '03',
    '22' => '06',
    '23' => '09',
    '24' => '12',
    // Northern seasons.
    '25' => '03',
    '26' => '06',
    '27' => '09',
    '28' => '12',
    // Southern seasons.
    '29' => '09',
    '30' => '12',
    '31' => '03',
    '32' => '06',
    // Quarters.
    '33' => '01',
    '34' => '04',
    '35' => '07',
    '36' => '10',
    // Quadrimesters.
    '37' => '01',
    '38' => '05',
    '39' => '09',
    // Semesters.
    '40' => '01',
    '41' => '07',
  ];

  /**
   * Southern hemisphere season map.
   *
   * (Currently unused until a config for this is established.)
   *
   * @var array
   */
  private $seasonMapSouth = [
  // Spring => September.
    '21' => '03',
  // Summer => December.
    '22' => '06',
  // Autumn => March.
    '23' => '09',
  // Winter => June.
    '24' => '12',
  ];

  /**
   * Validate an EDTF expression.
   *
   * @param string $edtf_text
   *   The datetime string.
   * @param bool $intervals
   *   Are interval expressions permitted?
   * @param bool $sets
   *   Are set expressions permitted?
   * @param bool $strict
   *   Are only valid calendar dates permitted?
   *
   * @return array
   *   Array of error messages. Valid if empty.
   */
  public static function validate($edtf_text, $intervals = TRUE, $sets = TRUE, $strict = FALSE) {
    if (empty($edtf_text)) {
      return ["Cannot parse empty value."];
    }
    $msgs = [];
    // Sets.
    if ($sets) {
      if (strpos($edtf_text, '[') !== FALSE || strpos($edtf_text, '{') !== FALSE) {
        // Test for valid enclosing characters and valid characters inside.
        $has_match = preg_match('/^([\[\{])[\d\-XYES.,]+([\]\}])$/', $edtf_text, $match);
        if (!$has_match) {
          $msgs[] = "The set is improperly encoded.";
          return $msgs;
        }
        // Test each date in set.
        foreach (preg_split('/(,|\.\.)/', trim($edtf_text, '{}[]')) as $date) {
          if (!empty($date)) {
            $msgs = array_merge($msgs, self::validateDate($date, $strict));
          }
        }
        return $msgs;
      }
    }
    // Intervals.
    if ($intervals && str_contains($edtf_text, '/')) {
      if (strpos($edtf_text, 'T') !== FALSE) {
        $msgs[] = "Date intervals cannot include times.";
      }
      foreach (explode('/', $edtf_text) as $date) {
        if (!empty($date) && !($date == '..')) {
          $msgs = array_merge($msgs, self::validateDate($date, $strict));
        }
      }
      return $msgs;
    }
    // Single date (we assume at this point).
    return self::validateDate($edtf_text, $strict);
  }

  /**
   * Validate a single date.
   *
   * @param string $datetime_str
   *   The datetime string.
   * @param bool $strict
   *   Are only valid calendar dates permitted?
   *
   * @return array
   *   Array of error messages. Valid if empty.
   */
  public static function validateDate($datetime_str, $strict = FALSE) {
    $msgs = [];

    if (strpos($datetime_str, 'T') > -1) {
      [$date, $time] = explode('T', $datetime_str);
    }
    else {
      $date = (string) $datetime_str;
      $time = NULL;
    }

    if (preg_match(self::DATE_PARSE_REGEX, $date, $parsed_date) !== 1 ||
      $date !== $parsed_date[self::FULL_MATCH]) {

      // "Something" is wrong with the provided date if it doesn't round-trip.
      // Includes (non-exhaustive):
      // - no invalid characters present,
      // - two-digit months and days, and
      // - capturing group qualifiers.
      return ["Could not parse the date '$date'."];
    }

    // Year.
    if (strpos($parsed_date[self::YEAR_FULL], 'Y') === 0) {
      if ($strict) {
        $msgs[] = "Extended years are not supported with the 'strict dates' option enabled.";
      }
      // Expand exponents.
      if (!empty($parsed_date[self::YEAR_EXPONENT])) {
        $exponent = intval(substr($parsed_date[self::YEAR_EXPONENT], 1));
        $parsed_date[self::YEAR_BASE] = strval((10 ** $exponent) * intval($parsed_date[self::YEAR_BASE]));
        $parsed_date[self::YEAR_BASE] = self::expandYear($parsed_date[self::YEAR_FULL], $parsed_date[self::YEAR_BASE], $parsed_date[self::YEAR_EXPONENT]);
      }
    }
    elseif (strlen(ltrim($parsed_date[self::YEAR_BASE], '-')) > 4) {
      $msgs[] = "Years longer than 4 digits must be prefixed with a 'Y'.";
    }
    elseif (strlen($parsed_date[self::YEAR_BASE]) < 4) {
      $msgs[] = "Years must be at least 4 characters long.";
    }
    $strict_pattern = 'Y';

    // Month.
    if (array_key_exists(self::MONTH, $parsed_date) && !empty($parsed_date[self::MONTH])) {
      // Valid month values?
      if (
            // Month doesn't exist in mapping
            // and isn't a valid unspecified month value.
            (
              !array_key_exists($parsed_date[self::MONTH], self::MONTHS_MAP) &&
              (intval(str_replace('X', '1', $parsed_date[self::MONTH])) > 12)
            ) ||
            // Sub-year groupings with day values.
            (
              array_key_exists($parsed_date[self::MONTH], self::MONTHS_MAP) &&
              array_key_exists(self::DAY, $parsed_date) &&
              $parsed_date[self::MONTH] > 12
            ) ||
            // Unspecifed character comes before number.
            (
              preg_match('/X+\d/', $parsed_date[self::MONTH])
            )
        ) {
        $msgs[] = "Provided month value '" . $parsed_date[self::MONTH] . "' is not valid.";
      }
      $strict_pattern = 'Y-m';
    }

    // Day.
    if (array_key_exists(self::DAY, $parsed_date) && !empty($parsed_date[self::DAY])) {
      // Valid day values?
      if (strpos($parsed_date[self::DAY], 'X') === FALSE &&
          !in_array(intval($parsed_date[self::DAY]), range(1, 31))) {
        $msgs[] = "Provided day value '" . $parsed_date[self::DAY] . "' is not valid.";
      }
      $strict_pattern = 'Y-m-d';
    }
    // Time.
    if (strpos($datetime_str, 'T') !== FALSE && empty($time)) {
      $msgs[] = "Time not provided with time seperator (T).";
    }

    if ($time) {
      if (!preg_match('/^-?(\d{4})(-\d{2}){2}T\d{2}(:\d{2}){2}(Z|(\+|-)\d{2}:\d{2})?$/', $datetime_str, $matches)) {
        $msgs[] = "The date/time '$datetime_str' is invalid.";
      }
      $strict_pattern = 'Y-m-d\TH:i:s';
      if (count($matches) > 4) {
        if ($matches[4] === 'Z') {
          $strict_pattern .= '\Z';
        }
        else {
          $strict_pattern .= 'P';
        }
      }
    }

    if ($strict) {
      // Assemble the parts again.
      if ($time) {
        $cleaned_datetime = $datetime_str;
      }
      else {
        $cleaned_datetime = implode('-', array_filter([
          $parsed_date[self::YEAR_BASE],
          $parsed_date[self::MONTH],
          $parsed_date[self::DAY],
        ]));
      }
      $datetime_obj = \DateTime::createFromFormat('!' . $strict_pattern, $cleaned_datetime);
      $errors = \DateTime::getLastErrors();
      if (!$datetime_obj ||
          !empty($errors['warning_count']) ||
          // DateTime will create valid dates from Y-m without warning,
          // so validate we still have what it was given.
          !($cleaned_datetime === $datetime_obj->format($strict_pattern))
        ) {
        $msgs[] = "Strictly speaking, the date (and/or time) '$datetime_str' is invalid.";
      }
    }

    return $msgs;
  }

  /**
   * Expand an exponent year.
   *
   * @param string $year_full
   *   The full year expression from the EDTF string.
   * @param string $year_base
   *   The base expression from the EDTF string.
   * @param string $year_exponent
   *   The exponent expression from the EDTF string.
   *
   * @return string
   *   The expanded year value.
   */
  public static function expandYear($year_full, $year_base, $year_exponent) {
    if (!empty($year_exponent)) {
      $exponent = intval(substr($year_exponent, 1));
      return strval((10 ** $exponent) * intval($year_base));
    }
    else {
      return $year_base;
    }
  }

  /**
   * Converts an EDTF string into an ISO 8601 timestamp string.
   *
   * @param string $edtf
   *   The array containing the 'value' element.
   *
   * @return string
   *   Returns the ISO 8601 timestamp.
   */
  public static function iso8601Value(string $edtf) {

    if (count(self::validate($edtf)) > 0) {
      return '';
    }
    // Sets.
    if (strpos($edtf, '[') !== FALSE || strpos($edtf, '{') !== FALSE) {
      // Use first in set.
      $dates = preg_split('/(,|\.\.)/', trim($edtf, '{}[]'));
      return self::iso8601Value(array_shift($dates));
    }
    // Intervals.
    if (str_contains($edtf, '/')) {
      $dates = explode('/', $edtf);
      return self::iso8601Value(array_shift($dates));
    }

    $date_time = explode('T', $edtf);

    // Valid EDTF values with time portions are already ISO 8601 timestamps.
    if (array_key_exists(1, $date_time) && !empty($date_time[1])) {
      return $edtf;
    }

    preg_match(EDTFUtils::DATE_PARSE_REGEX, $date_time[0], $parsed_date);

    $year = '';
    $month = '';
    $day = '';

    // Expand the year if the Year Exponent exists.
    if (array_key_exists(EDTFUtils::YEAR_EXPONENT, $parsed_date) && !empty($parsed_date[EDTFUtils::YEAR_EXPONENT])) {
      $parsed_date[EDTFUtils::YEAR_BASE] = EDTFUtils::expandYear($parsed_date[EDTFUtils::YEAR_FULL], $parsed_date[EDTFUtils::YEAR_BASE], $parsed_date[EDTFUtils::YEAR_EXPONENT]);
    }

    // Clean-up unspecified year/decade.
    $year = str_replace('X', '0', $parsed_date[EDTFUtils::YEAR_BASE]);

    if (array_key_exists(EDTFUtils::MONTH, $parsed_date)) {
      $month = str_replace('XX', '01', $parsed_date[EDTFUtils::MONTH]);
      $month = str_replace('X', '0', $month);

      // ISO 8601 doesn't support seasonal notation yet. Swap them out.
      if (array_key_exists($month, EDTFUtils::SEASONS_MAP)) {
        $month = EDTFUtils::SEASONS_MAP[$month];
      }
    }

    if (array_key_exists(EDTFUtils::DAY, $parsed_date)) {
      $day = str_replace('XX', '01', $parsed_date[EDTFUtils::DAY]);
      $day = str_replace('X', '0', $day);
    }

    return implode('-', array_filter([$year, $month, $day]));

  }

}