diff --git a/core/includes/common.inc b/core/includes/common.inc index d849381..98db856 100644 --- a/core/includes/common.inc +++ b/core/includes/common.inc @@ -5,8 +5,8 @@ use Symfony\Component\HttpKernel\Exception\NotFoundHttpException; use Drupal\Component\Utility\NestedArray; use Drupal\Core\Cache\CacheBackendInterface; -use Drupal\Core\Datetime\DrupalDateTime; use Drupal\Core\Database\Database; +use Drupal\Core\Datetime\DrupalDateTime; use Drupal\Core\Template\Attribute; /** diff --git a/core/lib/Drupal/Component/Datetime/DateTimePlus.php b/core/lib/Drupal/Component/Datetime/DateTimePlus.php index f5c3cc7..4995e92 100644 --- a/core/lib/Drupal/Component/Datetime/DateTimePlus.php +++ b/core/lib/Drupal/Component/Datetime/DateTimePlus.php @@ -2,49 +2,66 @@ /** * @file - * Definition of Drupal\Component\Datetime\DateTimePlus + * Contains Drupal\Component\Datetime\DateTimePlus */ + namespace Drupal\Component\Datetime; /** * Extends DateTime(). * * This class extends the PHP DateTime class with more flexible initialization - * parameters, allowing a date to be created from an existing date object, - * a timestamp, a string with an unknown format, a string with a known - * format, or an array of date parts. It also adds an errors array - * and a __toString() method to the date object. + * parameters, allowing a date to be created from an existing date object, a + * timestamp, a string with an unknown format, a string with a known format, or + * an array of date parts. It also adds an errors array and a __toString() + * method to the date object. * - * In addition, it swaps the IntlDateFormatter into the format() method, - * if it is available. The format() method is also extended with a settings - * array to provide settings needed by the IntlDateFormatter. It will - * will only be used if the class is available, a langcode, country, and - * calendar have been set, and the format is in the right pattern, otherwise - * the parent format() method is used in the usual way. These values can - * either be set globally in the object and reused over and over as the date - * is repeatedly formatted, or set specifically in the format() method - * for the requested format. + * In addition, it swaps the IntlDateFormatter into the format() method, if it + * is available. The format() method is also extended with a settings array to + * provide settings needed by the IntlDateFormatter. It will will only be used + * if the class is available, a langcode, country, and calendar have been set, + * and the format is in the right pattern, otherwise the parent format() method + * is used in the usual way. These values can either be set globally in the + * object and reused over and over as the date is repeatedly formatted, or set + * specifically in the format() method for the requested format. * - * This class is less lenient than the parent DateTime class. It changes - * the default behavior for handling date values like '2011-00-00'. - * The parent class would convert that value to '2010-11-30' and report - * a warning but not an error. This extension treats that as an error. + * This class is less lenient than the parent DateTime class. It changes the + * default behavior for handling date values like '2011-00-00'. The parent class + * would convert that value to '2010-11-30' and report a warning but not an + * error. This extension treats that as an error. * - * As with the base class, a date object may be created even if it has - * errors. It has an errors array attached to it that explains what the - * errors are. This is less disruptive than allowing datetime exceptions - * to abort processing. The calling script can decide what to do about - * errors using hasErrors() and getErrors(). + * As with the base class, a date object may be created even if it has errors. + * It has an errors array attached to it that explains what the errors are. This + * is less disruptive than allowing datetime exceptions to abort processing. The + * calling script can decide what to do about errors using hasErrors() and + * getErrors(). */ class DateTimePlus extends \DateTime { - const FORMAT = 'Y-m-d H:i:s'; + /** + * ??? + */ + const FORMAT = 'Y-m-d H:i:s'; + + /** + * ??? + */ const CALENDAR = 'gregorian'; - const PHP = 'php'; - const INTL = 'intl'; + + /** + * ??? + */ + const PHP = 'php'; + + /** + * ??? + */ + const INTL = 'intl'; /** * An array of possible date parts. + * + * @var array */ protected static $dateParts = array( 'year', @@ -57,51 +74,71 @@ class DateTimePlus extends \DateTime { /** * The value of the time value passed to the constructor. + * + * @var string */ protected $inputTimeRaw = ''; /** * The prepared time, without timezone, for this date. + * + * @var string */ protected $inputTimeAdjusted = ''; /** * The value of the timezone passed to the constructor. + * + * @var string */ protected $inputTimeZoneRaw = ''; /** * The prepared timezone object used to construct this date. + * + * @var string */ protected $inputTimeZoneAdjusted = ''; /** * The value of the format passed to the constructor. + * + * @var string */ protected $inputFormatRaw = ''; /** * The prepared format, if provided. + * + * @var string */ protected $inputFormatAdjusted = ''; /** * The value of the language code passed to the constructor. + * + * @var string|null */ protected $langcode = NULL; /** * The value of the country code passed to the constructor. + * + * @var string|null */ protected $country = NULL; /** * The value of the calendar setting passed to the constructor. + * + * @var string|null */ protected $calendar = NULL; /** * An array of errors encountered when creating this date. + * + * @var array */ protected $errors = array(); @@ -109,40 +146,43 @@ class DateTimePlus extends \DateTime { * Constructs a date object set to a requested date and timezone. * * @param mixed $time - * A DateTime object, a date/time string, a unix timestamp, - * or an array of date parts, like ('year' => 2014, 'month => 4). - * Defaults to 'now'. + * (optional) A DateTime object, a date/time string, a unix timestamp, or an + * array of date parts, like ('year' => 2014, 'month => 4). Defaults to + * 'now'. * @param mixed $timezone - * PHP DateTimeZone object, string or NULL allowed. - * Defaults to NULL. - * @param string $format - * PHP date() type format for parsing the input. This is recommended - * for specialized input with a known format. If provided the - * date will be created using the createFromFormat() method. - * Defaults to NULL. - * @see http://us3.php.net/manual/en/datetime.createfromformat.php + * (optional) PHP DateTimeZone object, string or NULL allowed. Defaults to + * NULL. + * @param string|null $format + * (optional) A PHP date() type format for parsing the input. This is + * recommended for specialized input with a known format. If provided, the + * date will be created using the createFromFormat() method. Defaults to + * NULL. * @param array $settings - * - validate_format: (optional) Boolean choice to validate the - * created date using the input format. The format used in - * createFromFormat() allows slightly different values than format(). - * Using an input format that works in both functions makes it - * possible to a validation step to confirm that the date created - * from a format string exactly matches the input. This option - * indicates the format can be used for validation. Defaults to TRUE. - * - langcode: (optional) String two letter language code to construct - * the locale string by the intlDateFormatter class. Used to control - * the result of the format() method if that class is available. - * Defaults to NULL. - * - country: (optional) String two letter country code to construct - * the locale string by the intlDateFormatter class. Used to control - * the result of the format() method if that class is available. - * Defaults to NULL. - * - calendar: (optional) String calendar name to use for the date. + * (optional) An array whcih may contain the following keys: + * - validate_format: (optional) A Boolean choice to validate the created + * date using the input format. The format used in createFromFormat() + * allows slightly different values than format(). Using an input format + * that works in both functions makes it possible to a validation step to + * confirm that the date created from a format string exactly matches the + * input. This option indicates the format can be used for validation. + * Defaults to TRUE. + * - langcode: (optional) A two-letter language code string to construct the + * locale string by the intlDateFormatter class. Used to control the + * result of the format() method if that class is available. Defaults to + * NULL. + * - country: (optional) A two-letter country code string to construct the + * locale string by the intlDateFormatter class. Used to control the + * result of the format() method if that class is available. Defaults to + * NULL. + * - calendar: (optional) A calendar name as a string to use for the date. * Defaults to DateTimePlus::CALENDAR. - * - debug: (optional) Boolean choice to leave debug values in the - * date object for debugging purposes. Defaults to FALSE. + * - debug: (optional) A Boolean choice to leave debug values in the date + * object for debugging purposes. Defaults to FALSE. + * Defaults to an empty array. + * + * @see http://us3.php.net/manual/en/datetime.createfromformat.php */ - public function __construct($time = 'now', $timezone = NULL, $format = NULL, $settings = array()) { + public function __construct($time = 'now', $timezone = NULL, $format = NULL, array $settings = array()) { // Unpack settings. $this->validateFormat = !empty($settings['validate_format']) ? $settings['validate_format'] : TRUE; @@ -189,7 +229,7 @@ public function __construct($time = 'now', $timezone = NULL, $format = NULL, $se $this->checkErrors(); $this->errors = array_unique($this->errors); - // Now that we've validated the input, clean up the extra values. + // Now that we have validated the input, clean up the extra values. if (empty($settings['debug'])) { unset( $this->inputTimeRaw, @@ -220,12 +260,12 @@ public function __toString() { /** * Prepares the input time value. * - * Changes the input value before trying to use it, if necessary. - * Can be overridden to handle special cases. + * Changes the input value before trying to use it, if necessary. This can be + * overridden to handle special cases. * * @param mixed $time - * An input value, which could be a timestamp, a string, - * or an array of date parts. + * An input value, which could be a timestamp, a string, or an array of date + * parts. */ protected function prepareTime($time) { $this->inputTimeAdjusted = $time; @@ -234,12 +274,12 @@ protected function prepareTime($time) { /** * Prepares the input timezone value. * - * Changes the timezone before trying to use it, if necessary. - * Most imporantly, makes sure there is a valid timezone - * object before moving further. + * This method changes the timezone before trying to use it, if necessary. + * Most imporantly, it makes sure there is a valid timezone object before + * proceding further. * * @param mixed $timezone - * Either a timezone name or a timezone object or NULL. + * One of a timezone name, a timezone object, or NULL. */ protected function prepareTimezone($timezone) { // If the input timezone is a valid timezone object, use it. @@ -247,8 +287,8 @@ protected function prepareTimezone($timezone) { $timezone_adjusted = $timezone; } - // When the passed-in time is a DateTime object with its own - // timezone, try to use the date's timezone. + // When the passed-in time is a DateTime object with its own timezone, try + // to use the date's timezone. elseif (empty($timezone) && $this->inputTimeAdjusted instanceOf \DateTime) { $timezone_adjusted = $this->inputTimeAdjusted->getTimezone(); } @@ -258,8 +298,8 @@ protected function prepareTimezone($timezone) { $timezone_adjusted = new \DateTimeZone($timezone); } - // Default to the system timezone when not explicitly provided. - // If the system timezone is missing, use 'UTC'. + // Default to the system timezone when not explicitly provided. If the + // system timezone is missing, use 'UTC'. if (empty($timezone_adjusted) || !$timezone_adjusted instanceOf \DateTimezone) { $system_timezone = date_default_timezone_get(); $timezone_name = !empty($system_timezone) ? $system_timezone : 'UTC'; @@ -273,8 +313,8 @@ protected function prepareTimezone($timezone) { /** * Prepares the input format value. * - * Changes the input format before trying to use it, if necessary. - * Can be overridden to handle special cases. + * This method changes the input format before trying to use it, if necessary. + * This format can be overridden to handle special cases. * * @param string $format * A PHP format string. @@ -286,8 +326,8 @@ protected function prepareFormat($format) { /** * Checks whether input is a DateTime object. * - * @return boolean - * TRUE if the input time is a DateTime object. + * @return bool + * TRUE if the input time is a DateTime object; otherwise FALSE. */ public function inputIsObject() { return $this->inputTimeAdjusted instanceOf \DateTime; @@ -295,6 +335,9 @@ public function inputIsObject() { /** * Creates a date object from an input date object. + * + * @throws \Exception + * ??? */ protected function constructFromObject() { try { @@ -307,15 +350,15 @@ protected function constructFromObject() { } /** - * Checks whether input time seems to be a timestamp. + * Checks whether the input time seems to be a timestamp. * - * Providing an input format will prevent ISO values without separators - * from being mis-interpreted as timestamps. Providing a format can also - * avoid interpreting a value like '2010' with a format of 'Y' as a - * timestamp. The 'U' format indicates this is a timestamp. + * Providing an input format will prevent ISO values without separators from + * being mis-interpreted as timestamps. Providing a format can also avoid + * interpreting a value like '2010' with a format of 'Y' as a timestamp. The + * 'U' format indicates this is a timestamp. * - * @return boolean - * TRUE if the input time is a timestamp. + * @return bool + * TRUE if the input time is a timestamp; otherwise, FALSE. */ public function inputIsTimestamp() { return is_numeric($this->inputTimeAdjusted) && (empty($this->inputFormatAdjusted) || $this->inputFormatAdjusted == 'U'); @@ -324,8 +367,11 @@ public function inputIsTimestamp() { /** * Creates a date object from timestamp input. * - * The timezone of a timestamp is always UTC. The timezone for a - * timestamp indicates the timezone used by the format() method. + * The timezone of a timestamp is always UTC. The timezone for a timestamp + * indicates the timezone used by the format() method. + * + * @throws \Exception + * ??? */ protected function constructFromTimestamp() { try { @@ -340,8 +386,8 @@ protected function constructFromTimestamp() { /** * Checks if input is an array of date parts. * - * @return boolean - * TRUE if the input time is a DateTime object. + * @return bool + * TRUE if the input time is a DateTime object; otherwise, FALSE. */ public function inputIsArray() { return is_array($this->inputTimeAdjusted); @@ -350,18 +396,21 @@ public function inputIsArray() { /** * Creates a date object from an array of date parts. * - * Converts the input value into an ISO date, forcing a full ISO - * date even if some values are missing. + * Converts the input value into an ISO date, forcing a full ISO date even if + * some values are missing. + * + * @throws \Exception + * ??? */ protected function constructFromArray() { try { parent::__construct('', $this->inputTimeZoneAdjusted); $this->inputTimeAdjusted = static::prepareArray($this->inputTimeAdjusted, TRUE); if (static::checkArray($this->inputTimeAdjusted)) { - // Even with validation, we can end up with a value that the - // parent class won't handle, like a year outside the range - // of -9999 to 9999, which will pass checkdate() but - // fail to construct a date object. + // Even with validation, we can end up with a value that the parent + // class will not handle, like a year outside the range of -9999 to + // 9999, which will pass checkdate(), but will fail to construct a date + // object. $this->inputTimeAdjusted = static::arrayToISO($this->inputTimeAdjusted); parent::__construct($this->inputTimeAdjusted, $this->inputTimeZoneAdjusted); } @@ -377,8 +426,9 @@ protected function constructFromArray() { /** * Checks if input is a string with an expected format. * - * @return boolean - * TRUE if the input time is a string with an expected format. + * @return bool + * TRUE if the input time is a string with an expected format; otherwise, + * FALSE. */ public function inputIsFormat() { return is_string($this->inputTimeAdjusted) && !empty($this->inputFormatAdjusted); @@ -386,11 +436,14 @@ public function inputIsFormat() { /** * Creates a date object from an input format. + * + * @throws \Exception + * ??? */ protected function constructFromFormat() { - // Tries to create a date from the format and use it if possible. - // A regular try/catch won't work right here, if the value is - // invalid it doesn't return an exception. + // Tries to create a date from the format and use it if possible. A regular + // try/catch will not work right here. If the value is invalid, it does not + // return an exception. try { parent::__construct('', $this->inputTimeZoneAdjusted); $date = parent::createFromFormat($this->inputFormatAdjusted, $this->inputTimeAdjusted, $this->inputTimeZoneAdjusted); @@ -402,13 +455,12 @@ protected function constructFromFormat() { $this->setTimezone($date->getTimezone()); try { - // The createFromFormat function is forgiving, it might - // create a date that is not exactly a match for the provided - // value, so test for that. For instance, an input value of - // '11' using a format of Y (4 digits) gets created as - // '0011' instead of '2011'. - // Use the parent::format() because we do not want to use - // the IntlDateFormatter here. + // The createFromFormat function is forgiving, it might create a date + // that is not exactly a match for the provided value, so test for + // that. For instance, an input value of '11' using a format of Y (4 + // digits) gets created as '0011' instead of '2011'. Use the + // parent::format() because we do not want to use the + // IntlDateFormatter here. if ($this->validateFormat && parent::format($this->inputFormatAdjusted) != $this->inputTimeRaw) { throw new \Exception('The created date does not match the input value.'); } @@ -426,9 +478,12 @@ protected function constructFromFormat() { /** * Creates a date when none of the other methods are appropriate. * - * Fallback construction for values that don't match any of the - * other patterns. Lets the parent dateTime attempt to turn this string - * into a valid date. + * Fallback construction for values that do not match any of the other + * patterns. Let the parent dateTime attempt to turn this string into a valid + * date. + * + * @throws \Exception + * ??? */ protected function constructFallback() { @@ -457,10 +512,10 @@ protected function constructFallback() { /** * Examines getLastErrors() to see what errors to report. * - * Two kinds of errors are important: anything that DateTime - * considers an error, and also a warning that the date was invalid. - * PHP creates a valid date from invalid data with only a warning, - * 2011-02-30 becomes 2011-03-03, for instance, but we don't want that. + * Two kinds of errors are important: anything that DateTime considers an + * error, and also a warning that the date was invalid. PHP creates a valid + * date from invalid data with only a warning, '2011-02-30' becomes + * '2011-03-03', for instance, but we do not want that. * * @see http://us3.php.net/manual/en/time.getlasterrors.php */ @@ -469,10 +524,10 @@ public function checkErrors() { if (!empty($errors['errors'])) { $this->errors += $errors['errors']; } - // Most warnings are messages that the date could not be parsed - // which causes it to be altered. For validation purposes, a warning - // as bad as an error, because it means the constructed date does - // not match the input value. + // Most warnings are messages that the date could not be parsed, which + // causes it to be altered. For validation purposes, a warning is as bad as + // an error, because it means the constructed date does not match the input + // value. if (!empty($errors['warnings'])) { $this->errors[] = 'The date is invalid.'; } @@ -480,6 +535,9 @@ public function checkErrors() { /** * Detects if there were errors in the processing of this date. + * + * @return bool + * ??? */ public function hasErrors() { return (boolean) count($this->errors); @@ -488,7 +546,10 @@ public function hasErrors() { /** * Retrieves error messages. * - * Public function to return the error messages. + * This is public method to return the error messages. + * + * @return ??? + * ??? */ public function getErrors() { return $this->errors; @@ -500,8 +561,8 @@ public function getErrors() { * @param array $array * An array of date values keyed by date part. * @param bool $force_valid_date - * (optional) Whether to force a full date by filling in missing - * values. Defaults to FALSE. + * (optional) A Boolean indicating whether to force a full date by filling + * in missing values. Defaults to FALSE. * * @return string * The date as an ISO string. @@ -537,8 +598,8 @@ public static function arrayToISO($array, $force_valid_date = FALSE) { * @param array $array * An array of date values keyed by date part. * @param bool $force_valid_date - * (optional) Whether to force a valid date by filling in missing - * values with valid values or just to use empty values instead. + * (optional) A Boolean indicating whether to force a valid date by filling + * in missing values with valid values or just to use empty values instead. * Defaults to FALSE. * * @return array @@ -572,29 +633,29 @@ public static function prepareArray($array, $force_valid_date = FALSE) { /** * Checks that arrays of date parts will create a valid date. * - * Checks that an array of date parts has a year, month, and day, - * and that those values create a valid date. If time is provided, - * verifies that the time values are valid. Sort of an - * equivalent to checkdate(). + * Checks that an array of date parts has a year, month, and day, and that + * those values create a valid date. If time is provided, This method verifies + * that the time values are valid. This is sort of an equivalent to + * checkdate(). * * @param array $array * An array of datetime values keyed by date part. * - * @return boolean - * TRUE if the datetime parts contain valid values, otherwise FALSE. + * @return bool + * TRUE if the datetime parts contain valid values; otherwise, FALSE. */ - public static function checkArray($array) { + public static function checkArray(array $array) { $valid_date = FALSE; $valid_time = TRUE; - // Check for a valid date using checkdate(). Only values that - // meet that test are valid. + // Check for a valid date using checkdate(). Only values that meet that test + // are valid. if (array_key_exists('year', $array) && array_key_exists('month', $array) && array_key_exists('day', $array)) { if (@checkdate($array['month'], $array['day'], $array['year'])) { $valid_date = TRUE; } } - // Testing for valid time is reversed. Missing time is OK, - // but incorrect values are not. + // Testing for valid time is reversed. Missing time is OK, but incorrect + // values are not. foreach (array('hour', 'minute', 'second') as $key) { if (array_key_exists($key, $array)) { $value = $array[$key]; @@ -625,7 +686,7 @@ public static function checkArray($array) { * @param int $value * The value to pad. * @param int $size - * (optional) Size expected, usually 2 or 4. Defaults to 2. + * (optional) The size expected, usually 2 or 4 characters. Defaults to 2. * * @return string * The padded value. @@ -637,6 +698,9 @@ public static function datePad($value, $size = 2) { /** * Tests whether the IntlDateFormatter can be used. + * + * @return ??? + * ??? */ public function canUseIntl() { return class_exists('IntlDateFormatter') && !empty($this->calendar) && !empty($this->langcode) && !empty($this->country); @@ -645,44 +709,49 @@ public function canUseIntl() { /** * Formats the date for display. * - * Uses the IntlDateFormatter to display the format, if possible. - * Adds an optional array of settings that provides the information - * the IntlDateFormatter will need. + * This method uses the IntlDateFormatter() to display the format, if + * possible. It adds an optional array of settings that provides the + * information that the IntlDateFormatter() will need. * * @param string $format - * A format string using either PHP's date() or the - * IntlDateFormatter() format. + * A format string using either PHP's date() or the IntlDateFormatter() + * format. * @param array $settings - * - format_string_type: (optional) DateTimePlus::PHP or - * DateTimePlus::INTL. Identifies the pattern used by the format - * string. When using the Intl formatter, the format string must - * use the Intl pattern, which is different from the pattern used - * by the DateTime format function. Defaults to DateTimePlus::PHP. - * - timezone: (optional) String timezone name. Defaults to the timezone - * of the date object. - * - langcode: (optional) String two letter language code to construct the + * (optional) An array that may include the follwoing keys: + * - format_string_type: (optional) DateTimePlus::PHP or DateTimePlus::INTL. + * Identifies the pattern used by the format string. When using the Intl + * formatter, the format string must use the Intl pattern, which is + * different from the pattern used by the DateTime format function. + * Defaults to DateTimePlus::PHP. + * - timezone: (optional) A timezone name as a string. Defaults to the + * timezone of the date object. + * - langcode: (optional) A two-letter language code string to construct the * locale string by the intlDateFormatter class. Used to control the - * result of the format() method if that class is available. Defaults - * to NULL. - * - country: (optional) String two letter country code to construct the + * result of the format() method if that class is available. Defaults to + * NULL. + * - country: (optional) A two-letter country code string to construct the * locale string by the intlDateFormatter class. Used to control the - * result of the format() method if that class is available. Defaults - * to NULL. - * - calendar: (optional) String calendar name to use for the date, + * result of the format() method if that class is available. Defaults to + * NULL. + * - calendar: (optional) The calendar name as string to use for the date. * Defaults to DateTimePlus::CALENDAR. - * - date_type: (optional) Integer date type to use in the formatter, - * defaults to IntlDateFormatter::FULL. - * - time_type: (optional) Integer date type to use in the formatter, - * defaults to IntlDateFormatter::FULL. - * - lenient: (optional) Boolean choice of whether or not to use lenient - * processing in the intl formatter. Defaults to FALSE; + * - date_type: (optional) An integer date type to use in the formatter. + * Defaults to IntlDateFormatter::FULL. + * - time_type: (optional) An integer date type to use in the formatter. + * Defaults to IntlDateFormatter::FULL. + * - lenient: (optional) A Boolean choice of whether or not to use lenient + * processing in the intl formatter. Defaults to FALSE. + * Defaults to an empty array. * * @return string * The formatted value of the date. + * + * @throws \Exception + * ??? */ public function format($format, $settings = array()) { - // If there were construction errors, we can't format the date. + // If there were construction errors, we cannot format the date. if ($this->hasErrors()) { return; } diff --git a/core/lib/Drupal/Core/Datetime/DrupalDateTime.php b/core/lib/Drupal/Core/Datetime/DrupalDateTime.php index 775e668..9110529 100644 --- a/core/lib/Drupal/Core/Datetime/DrupalDateTime.php +++ b/core/lib/Drupal/Core/Datetime/DrupalDateTime.php @@ -2,8 +2,9 @@ /** * @file - * Definition of Drupal\Core\Datetime\DrupalDateTime. + * Contains Drupal\Core\Datetime\DrupalDateTime. */ + namespace Drupal\Core\Datetime; use Drupal\Component\Datetime\DateTimePlus; @@ -11,8 +12,8 @@ /** * Extends DateTimePlus(). * - * This class extends the basic component and adds in Drupal-specific - * handling, like translation of the format() method. + * This class extends the basic component and adds in Drupal-specific handling, + * like translation of the format() method. * * @see Drupal/Component/Datetime/DateTimePlus.php */ @@ -22,39 +23,42 @@ class DrupalDateTime extends DateTimePlus { * Constructs a date object. * * @param mixed $time - * A DateTime object, a date/input_time_adjusted string, a unix timestamp, + * (optional) A DateTime object, a date/input_time_adjusted string, a unix timestamp, * or an array of date parts, like ('year' => 2014, 'month => 4). * Defaults to 'now'. * @param mixed $timezone - * PHP DateTimeZone object, string or NULL allowed. + * (optional) PHP DateTimeZone object, string or NULL allowed. * Defaults to NULL. * @param string $format - * PHP date() type format for parsing the input. This is recommended + * (optional) PHP date() type format for parsing the input. This is recommended * to use things like negative years, which php's parser fails on, or * any other specialized input with a known format. If provided the * date will be created using the createFromFormat() method. * Defaults to NULL. - * @see http://us3.php.net/manual/en/datetime.createfromformat.php * @param array $settings - * - validate_format: (optional) Boolean choice to validate the - * created date using the input format. The format used in - * createFromFormat() allows slightly different values than format(). - * Using an input format that works in both functions makes it - * possible to a validation step to confirm that the date created - * from a format string exactly matches the input. This option - * indicates the format can be used for validation. Defaults to TRUE. - * - langcode: (optional) String two letter language code to construct - * the locale string by the intlDateFormatter class. Used to control - * the result of the format() method if that class is available. - * Defaults to NULL. - * - country: (optional) String two letter country code to construct - * the locale string by the intlDateFormatter class. Used to control - * the result of the format() method if that class is available. - * Defaults to NULL. - * - calendar: (optional) String calendar name to use for the date. + * (optional) An array that may contain the following keys: + * - validate_format: (optional) A Boolean choice to validate the created + * date using the input format. The format used in createFromFormat() + * allows slightly different values than format(). Using an input format + * that works in both methods makes it possible as a validation step to + * confirm that the date created from a format string exactly matches the + * input. This option indicates the format can be used for validation. + * Defaults to TRUE. + * - langcode: (optional) A two-letter language code string to construct the + * locale string by the intlDateFormatter class. This is used to control + * the result of the format() method if that class is available. Defaults + * to NULL. + * - country: (optional) String two letter country code to construct the + * locale string by the intlDateFormatter class. This is used to control + * the result of the format() method if that class is available. Defaults + * to NULL. + * - calendar: (optional) A calendar name as a string to use for the date. * Defaults to DateTimePlus::CALENDAR. - * - debug: (optional) Boolean choice to leave debug values in the - * date object for debugging purposes. Defaults to FALSE. + * - debug: (optional) A Boolean choice to leave debug values in the date + * object for debugging purposes. Defaults to FALSE. + * Defaults to an empty array. + * + * @see http://us3.php.net/manual/en/datetime.createfromformat.php */ public function __construct($time = 'now', $timezone = NULL, $format = NULL, $settings = array()) { @@ -68,10 +72,13 @@ public function __construct($time = 'now', $timezone = NULL, $format = NULL, $se } /** - * Overrides prepareTimezone(). + * Overrides \???\prepareTimezone(). + * + * Override basic component timezone handling to use Drupal's knowledge of the + * preferred user timezone. * - * Override basic component timezone handling to use Drupal's - * knowledge of the preferred user timezone. + * @param ??? $timezone + * ??? */ protected function prepareTimezone($timezone) { $user_timezone = drupal_get_user_timezone(); @@ -82,42 +89,47 @@ protected function prepareTimezone($timezone) { } /** - * Overrides format(). + * Overrides \???::format(). * - * Uses the IntlDateFormatter to display the format, if possible. - * Adds an optional array of settings that provides the information - * the IntlDateFormatter will need. + * This method uses the IntlDateFormatter to display the format, if possible. + * It adds an optional array of settings that provides the information the + * IntlDateFormatter will need. * * @param string $format - * A format string using either PHP's date() or the - * IntlDateFormatter() format. + * A format string using either PHP's date() or the IntlDateFormatter() + * format. * @param array $settings - * - format_string_type: (optional) DateTimePlus::PHP or - * DateTimePlus::INTL. Identifies the pattern used by the format - * string. When using the Intl formatter, the format string must - * use the Intl pattern, which is different from the pattern used - * by the DateTime format function. Defaults to DateTimePlus::PHP. - * - timezone: (optional) String timezone name. Defaults to the timezone - * of the date object. - * - langcode: (optional) String two letter language code to construct the + * (optional) An array with the following possible keys: + * - format_string_type: (optional) A DateTimePlus::PHP or + * DateTimePlus::INTL. Identifies the pattern used by the format string. + * When using the Intl formatter, the format string must use the Intl + * pattern, which is different from the pattern used by the DateTime + * format function. Defaults to DateTimePlus::PHP. + * - timezone: (optional) A timezone name as a string. Defaults to the + * timezone of the date object. + * - langcode: (optional) A two-letter language code string to construct the * locale string by the intlDateFormatter class. Used to control the - * result of the format() method if that class is available. Defaults - * to NULL. - * - country: (optional) String two letter country code to construct the + * result of the format() method if that class is available. Defaults to + * NULL. + * - country: (optional) A two-letter country code string to construct the * locale string by the intlDateFormatter class. Used to control the - * result of the format() method if that class is available. Defaults - * to NULL. - * - calendar: (optional) String calendar name to use for the date, - * Defaults to DateTimePlus::CALENDAR. - * - date_type: (optional) Integer date type to use in the formatter, - * defaults to IntlDateFormatter::FULL. - * - time_type: (optional) Integer date type to use in the formatter, - * defaults to IntlDateFormatter::FULL. - * - lenient: (optional) Boolean choice of whether or not to use lenient - * processing in the intl formatter. Defaults to FALSE; + * result of the format() method if that class is available. Defaults to + * NULL. + * - calendar: (optional) The calendar name to use for the date. Defaults to + * DateTimePlus::CALENDAR. + * - date_type: (optional) An integer date type to use in the formatter. + * Defaults to IntlDateFormatter::FULL. + * - time_type: (optional) An integer date type to use in the formatter. + * Defaults to IntlDateFormatter::FULL. + * - lenient: (optional) A Boolean choice of whether or not to use lenient + * processing in the intl formatter. Defaults to FALSE. + * Defaults to an empty array. * * @return string * The formatted value of the date. + * + * @throws \Exception + * ??? */ public function format($format, $settings = array()) { @@ -137,12 +149,11 @@ public function format($format, $settings = array()) { // Otherwise, use the default Drupal method. else { - // Encode markers that should be translated. 'A' becomes - // '\xEF\AA\xFF'. xEF and xFF are invalid UTF-8 sequences, - // and we assume they are not in the input string. - // Paired backslashes are isolated to prevent errors in - // read-ahead evaluation. The read-ahead expression ensures that - // A matches, but not \A. + // Encode markers that should be translated. 'A' becomes '\xEF\AA\xFF'. + // xEF and xFF are invalid UTF-8 sequences, and we assume they are not + // in the input string. Paired backslashes are isolated to prevent + // errors in read-ahead evaluation. The read-ahead expression ensures + // that A matches, but not \A. $format = preg_replace(array('/\\\\\\\\/', '/(?value = $value; } @@ -57,6 +57,7 @@ public function getString() { * Implements TypedDataInterface::validate(). */ public function validate() { - // TODO: Implement validate() method. + // @todo Implement validate() method. } + } diff --git a/core/modules/system/lib/Drupal/system/Tests/Datetime/DateTimePlusTest.php b/core/modules/system/lib/Drupal/system/Tests/Datetime/DateTimePlusTest.php index 9eb0162..caec2ca 100644 --- a/core/modules/system/lib/Drupal/system/Tests/Datetime/DateTimePlusTest.php +++ b/core/modules/system/lib/Drupal/system/Tests/Datetime/DateTimePlusTest.php @@ -2,7 +2,7 @@ /** * @file - * Definition of Drupal\system\Tests\Datetime\DateTimePlusTest. + * Defines Drupal\system\Tests\Datetime\DateTimePlusTest. */ namespace Drupal\system\Tests\Datetime; @@ -11,11 +11,11 @@ use Drupal\Component\Datetime\DateTimePlus; use DateTimeZone; +/** + * Test the functionality of the DateTimePlus object. + */ class DateTimePlusTest extends UnitTestBase { - /** - * Test information. - */ public static function getInfo() { return array( 'name' => 'DateTimePlus', @@ -25,12 +25,7 @@ public static function getInfo() { } /** - * Set up required modules. - */ - public static $modules = array(); - - /** - * Test creating dates from string input. + * Tests creating dates from string input. */ public function testDateStrings() { @@ -85,7 +80,7 @@ public function testDateStrings() { } /** - * Test creating dates from arrays of date parts. + * Tests creating dates from arrays of date parts. */ function testDateArrays() { @@ -124,7 +119,7 @@ function testDateArrays() { } /** - * Test creating dates from timestamps. + * Tests creating dates from timestamps. */ function testDateTimestamp() { @@ -189,7 +184,7 @@ function testDateTimestamp() { } /** - * Test timezone manipulation. + * Tests timezone manipulation. */ function testTimezoneConversion() { @@ -270,7 +265,7 @@ function testTimezoneConversion() { } /** - * Test creating dates from format strings. + * Tests creating dates from format strings. */ function testDateFormat() { @@ -313,7 +308,7 @@ function testDateFormat() { } /** - * Test invalid date handling. + * Tests invalid date handling. */ function testInvalidDates() { @@ -381,8 +376,9 @@ function testInvalidDates() { } /** - * Test that DrupalDateTime can detect the right timezone to use. - * When specified or not. + * Tests that DrupalDateTime can detect the right timezone to use. + * + * This checks whether the timezone is specified or not. */ public function testDateTimezone() { global $user; @@ -415,4 +411,5 @@ public function testDateTimezone() { $this->assertTrue($timezone == 'Pacific/Midway', 'DateTimePlus uses the specified timezone if provided.'); } + } diff --git a/core/modules/system/lib/Drupal/system/Tests/Datetime/DrupalDateTimeTest.php b/core/modules/system/lib/Drupal/system/Tests/Datetime/DrupalDateTimeTest.php index ea10896..34cee78 100644 --- a/core/modules/system/lib/Drupal/system/Tests/Datetime/DrupalDateTimeTest.php +++ b/core/modules/system/lib/Drupal/system/Tests/Datetime/DrupalDateTimeTest.php @@ -10,11 +10,13 @@ use Drupal\simpletest\WebTestBase; use Drupal\Core\Datetime\DrupalDateTime; +/** + * Tests the functionality of the DrupalDateTime class. + */ class DrupalDateTimeTest extends WebTestBase { - /** - * Test information. - */ + public static $modules = array(); + public static function getInfo() { return array( 'name' => 'DrupalDateTime', @@ -23,24 +25,16 @@ public static function getInfo() { ); } - /** - * Set up required modules. - */ - public static $modules = array(); - - /** - * Test setup. - */ public function setUp() { parent::setUp(); } /** - * Test that DrupalDateTime can detect the right timezone to use. - * Test with a variety of less commonly used timezone names to - * help ensure that the system timezone will be different than the - * stated timezones. + * Tests that DrupalDateTime can detect the right timezone to use. + * + * Test with a variety of less commonly used timezone names to help ensure + * that the system timezone will be different than the stated timezones. */ public function testDateTimezone() { global $user; @@ -54,8 +48,8 @@ public function testDateTimezone() { // Detect the system timezone. $system_timezone = date_default_timezone_get(); - // Create a date object with an unspecified timezone, which should - // end up using the system timezone. + // Create a date object with an unspecified timezone, which should end up + // using the system timezone. $date = new DrupalDateTime($date_string); $timezone = $date->getTimezone()->getName(); $this->assertTrue($timezone == $system_timezone, 'DrupalDateTime uses the system timezone when there is no site timezone.'); @@ -68,8 +62,8 @@ public function testDateTimezone() { // Set a site timezone. variable_set('date_default_timezone', 'Europe/Warsaw'); - // Create a date object with an unspecified timezone, which should - // end up using the site timezone. + // Create a date object with an unspecified timezone, which should end up + // using the site timezone. $date = new DrupalDateTime($date_string); $timezone = $date->getTimezone()->getName(); $this->assertTrue($timezone == 'Europe/Warsaw', 'DrupalDateTime uses the site timezone if provided.'); @@ -92,9 +86,8 @@ public function testDateTimezone() { // Simulate a Drupal bootstrap with the logged-in user. date_default_timezone_set(drupal_get_user_timezone()); - // Create a date object with an unspecified timezone, which should - // end up using the user timezone. - + // Create a date object with an unspecified timezone, which should end up + // using the user timezone. $date = new DrupalDateTime($date_string); $timezone = $date->getTimezone()->getName(); $this->assertTrue($timezone == 'Asia/Manila', 'DrupalDateTime uses the user timezone, if configurable timezones are used and it is set.'); @@ -105,6 +98,6 @@ public function testDateTimezone() { date_default_timezone_set(drupal_get_user_timezone()); drupal_save_session(TRUE); - } + }