diff --git a/README.md b/README.md index ee9e0a0..a9017b4 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,9 @@ [![Code Coverage](https://img.shields.io/coveralls/ICanBoogie/DateTime.svg)](https://coveralls.io/r/ICanBoogie/DateTime) [![Packagist](https://img.shields.io/packagist/dm/icanboogie/datetime.svg?maxAge=2592000)](https://packagist.org/packages/icanboogie/datetime) -This package extends the features of PHP [DateTime](http://www.php.net/manual/en/class.datetime.php) +This package extends the features of PHP +[DateTime](http://www.php.net/manual/en/class.datetime.php), +[DateTimeImmutable](http://www.php.net/manual/en/class.datetimeimmutable.php), and [DateTimeZone](http://www.php.net/manual/en/class.datetimezone.php) classes to ease the handling of times, time zones and time zone locations. Getting the UTC or local representation of a time, formatting the time to a predefined format, accessing common properties such as day, month, @@ -83,11 +85,11 @@ The implementation of the [DateTime][] class is vastly inspired by Ruby's ## DateTime is a value object -Starting from v2.0, date time instances are immutable [value -objects](https://en.wikipedia.org/wiki/Value_object). A class to create mutable date time instances -is available, but it's important to remember the difference with PHP implementation. Thus, -[ICanBoogie\DateTime][] extends [\DateTimeImmutable][] and [ICanBoogie\MutableDateTime][] extends -[\DateTime][]. +Starting from v2.0, date time instances are immutable [value objects][]. A class to create mutable +date time instances is available, but it's important to remember the difference with PHP +implementation. Thus, [ICanBoogie\DateTime][] extends [\DateTimeImmutable][] and +[ICanBoogie\MutableDateTime][] extends [\DateTime][]. Alose [ICanBoogie\Contract\DateTime], which is +implemented by both [DateTime][] and [MutableDateTime][], extends [\DateTimeInterface][]. You can switch from immutable to mutable instances using the `mutable` and `immutable` properties, or the static `from()` method: @@ -485,16 +487,17 @@ The package is continuously tested by [Travis CI](http://about.travis-ci.org/). -[ICanBoogie/CLDR]: https://github.com/ICanBoogie/CLDR -[JsonSerializable interface]: http://php.net/manual/en/class.jsonserializable.php -[documentation]: http://api.icanboogie.org/datetime/latest/ -[\DateTime]: http://php.net/manual/en/class.datetime.php -[\DateTimeImmutable]: http://php.net/manual/en/class.datetimeimmutable.php -[DateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.DateTime.html -[ICanBoogie\DateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.DateTime.html -[ICanBoogie\MutableDateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.MutableDateTime.html -[MutableDateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.MutableDateTime.html -[TimeZone]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.TimeZone.html -[TimeZoneLocation]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.TimeZoneLocation.html -[PropertyNotDefined]: http://api.icanboogie.org/common/1.2/class-ICanBoogie.PropertyNotDefined.html -[PropertyNotWritable]: http://api.icanboogie.org/common/1.2/class-ICanBoogie.PropertyNotWritable.html +[ICanBoogie/CLDR]: https://github.com/ICanBoogie/CLDR +[JsonSerializable interface]: http://php.net/manual/en/class.jsonserializable.php +[documentation]: http://api.icanboogie.org/datetime/latest/ +[\DateTime]: http://php.net/manual/en/class.datetime.php +[\DateTimeImmutable]: http://php.net/manual/en/class.datetimeimmutable.php +[\DateTimeInterface]: http://php.net/manual/en/class.datetimeinterface.php +[DateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.DateTime.html +[ICanBoogie\Contract\DateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.Contract.DateTime.html +[ICanBoogie\DateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.DateTime.html +[ICanBoogie\MutableDateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.MutableDateTime.html +[MutableDateTime]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.MutableDateTime.html +[TimeZone]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.TimeZone.html +[TimeZoneLocation]: http://api.icanboogie.org/datetime/2.0/class-ICanBoogie.TimeZoneLocation.html +[value objects]: https://en.wikipedia.org/wiki/Value_object diff --git a/lib/Contract/DateTime.php b/lib/Contract/DateTime.php new file mode 100644 index 0000000..552695f --- /dev/null +++ b/lib/Contract/DateTime.php @@ -0,0 +1,149 @@ + + * + * + * @param mixed $source + * @param mixed $timezone The time zone to use to create the time. The value is ignored if the + * source is an instance of {@link \DateTime}. + * + * @return static + */ + static public function from($source, $timezone = null); + + /** + * Returns an instance representing an empty date ("0000-00-00"). + * + *
+	 * is_empty;                      // true
+	 * $d->timezone->name;                // "UTC"
+	 *
+	 * $d = DateTime::none('Asia/Tokyo');
+	 * $d->is_empty;                      // true
+	 * $d->timezone->name;                // "Asia/Tokio"
+	 * 
+ * + * @param \DateTimeZone|string $timezone The time zone in which the empty date is created. + * Defaults to "UTC". + * + * @return DateTime + */ + static public function none($timezone = 'utc'); + + /** + * Returns an instance with the current local time and the local time zone. + * + * **Note:** Subsequent calls return equal times, event if they are minutes apart. _now_ + * actually refers to the `REQUEST_TIME` or, if it is now available, to the first time + * the method was invoked. + * + * @return static + */ + static public function now(); + + /** + * Returns an instance with the current local time and the local time zone. + * + * **Note:** Subsequent calls may return different times. + * + * @return static + */ + static public function right_now(); + + /** + * Modifies the properties of the instance according to the options. + * + * The following properties can be updated: {@link $year}, {@link $month}, {@link $day}, + * {@link $hour}, {@link $minute} and {@link $second}. + * + * Note: Values exceeding ranges are added to their parent values. + * + *
+	 * change([ 'year' => 2000, 'second' => 0 ]);
+	 * 
+ * + * @param array $options + * @param bool $cascade If `true`, time options (`hour`, `minute`, `second`) reset + * cascading, so if only the hour is passed, then minute and second is set to 0. If the hour + * and minute is passed, then second is set to 0. + * + * @return $this + */ + public function change(array $options, $cascade = false); + + /** + * Returns a new instance with changes properties. + * + * @param array $options + * @param bool $cascade + * + * @return DateTime + */ + public function with(array $options, $cascade = false); + + /** + * Returns a localized instance. + * + * @param string $locale + * + * @return mixed + * + * @throws \LogicException if the instance cannot be localized. + */ + public function localize($locale = 'en'); +} diff --git a/lib/DateTime.php b/lib/DateTime.php index 716b555..5987ce1 100644 --- a/lib/DateTime.php +++ b/lib/DateTime.php @@ -11,8 +11,6 @@ namespace ICanBoogie; -use ICanBoogie\DateTime\AdditionalFormats; - /** * Representation of a date and time. * @@ -102,7 +100,7 @@ * * @see http://en.wikipedia.org/wiki/ISO_8601 */ -class DateTime extends \DateTimeImmutable implements \JsonSerializable, AdditionalFormats +class DateTime extends \DateTimeImmutable implements \JsonSerializable, Contract\DateTime { use DateTime\Shared; use DateTime\Readers; @@ -130,13 +128,7 @@ class DateTime extends \DateTimeImmutable implements \JsonSerializable, Addition static public $localizer = null; /** - * Returns an instance with the current local time and the local time zone. - * - * **Note:** Subsequent calls return equal times, event if they are minutes apart. _now_ - * actually refers to the `REQUEST_TIME` or, if it is now available, to the first time - * the method was invoked. - * - * @return static + * @inheritdoc */ static public function now() { @@ -161,12 +153,7 @@ public function __set($property, $value) } /** - * Instantiate a new instance with changes properties. - * - * @param array $options - * @param bool $cascade - * - * @return DateTime + * @inheritdoc */ public function with(array $options, $cascade = false) { diff --git a/lib/DateTime/AdditionalFormats.php b/lib/DateTime/AdditionalFormats.php deleted file mode 100644 index 8d90349..0000000 --- a/lib/DateTime/AdditionalFormats.php +++ /dev/null @@ -1,46 +0,0 @@ - - * - * For the full copyright and license information, please view the LICENSE - * file that was distributed with this source code. - */ - -namespace ICanBoogie\DateTime; - -/** - * - */ -interface AdditionalFormats -{ - /** - * DB (example: 2013-02-03 20:59:03) - * - * @var string - */ - const DB = 'Y-m-d H:i:s'; - - /** - * Number (example: 20130203205903) - * - * @var string - */ - const NUMBER = 'YmdHis'; - - /** - * Date (example: 2013-02-03) - * - * @var string - */ - const DATE = 'Y-m-d'; - - /** - * Time (example: 20:59:03) - * - * @var string - */ - const TIME = 'H:i:s'; -} diff --git a/lib/DateTime/Shared.php b/lib/DateTime/Shared.php index 4b63e53..a53fe68 100644 --- a/lib/DateTime/Shared.php +++ b/lib/DateTime/Shared.php @@ -72,23 +72,7 @@ abstract public function setDate($year, $month, $day); abstract public function setTime($hour, $minute, $second = null); /** - * Creates a {@link DateTime} instance from a source. - * - *
-	 * 
-	 *
-	 * @param mixed $source
-	 * @param mixed $timezone The time zone to use to create the time. The value is ignored if the
-	 * source is an instance of {@link \DateTime}.
-	 *
-	 * @return DateTime
+	 * @inheritdoc
 	 */
 	static public function from($source, $timezone = null)
 	{
@@ -106,26 +90,7 @@ static public function from($source, $timezone = null)
 	}
 
 	/**
-	 * Returns an instance representing an empty date ("0000-00-00").
-	 *
-	 * 
-	 * is_empty;                      // true
-	 * $d->timezone->name;                // "UTC"
-	 *
-	 * $d = DateTime::none('Asia/Tokyo');
-	 * $d->is_empty;                      // true
-	 * $d->timezone->name;                // "Asia/Tokio"
-	 * 
- * - * @param \DateTimeZone|string $timezone The time zone in which the empty date is created. - * Defaults to "UTC". - * - * @return DateTime + * @inheritdoc */ static public function none($timezone = 'utc') { @@ -133,11 +98,7 @@ static public function none($timezone = 'utc') } /** - * Returns an instance with the current local time and the local time zone. - * - * **Note:** Subsequent calls may return different times. - * - * @return static + * @inheritdoc */ static public function right_now() { @@ -254,28 +215,7 @@ public function format($format) } /** - * Modifies the properties of the instance according to the options. - * - * The following properties can be updated: {@link $year}, {@link $month}, {@link $day}, - * {@link $hour}, {@link $minute} and {@link $second}. - * - * Note: Values exceeding ranges are added to their parent values. - * - *
-	 * change([ 'year' => 2000, 'second' => 0 ]);
-	 * 
- * - * @param array $options - * @param bool $cascade If `true`, time options (`hour`, `minute`, `second`) reset - * cascading, so if only the hour is passed, then minute and second is set to 0. If the hour - * and minute is passed, then second is set to 0. - * - * @return $this + * @inheritdoc */ public function change(array $options, $cascade = false) { @@ -340,13 +280,7 @@ public function change(array $options, $cascade = false) } /** - * Returns a localized instance. - * - * @param string $locale - * - * @return mixed - * - * @throws \LogicException if {@link $localizer} is not defined. + * @inheritdoc */ public function localize($locale = 'en') { diff --git a/lib/MutableDateTime.php b/lib/MutableDateTime.php index 773484e..2f66cac 100644 --- a/lib/MutableDateTime.php +++ b/lib/MutableDateTime.php @@ -11,8 +11,6 @@ namespace ICanBoogie; -use ICanBoogie\DateTime\AdditionalFormats; - /** * @property int $year Year. * @property int $month Month of the year. @@ -29,19 +27,13 @@ * * @method $this change(array $options, $cascade = false) */ -class MutableDateTime extends \DateTime implements \JsonSerializable, AdditionalFormats +class MutableDateTime extends \DateTime implements \JsonSerializable, Contract\DateTime { use DateTime\Shared; use DateTime\Readers; /** - * Returns an instance with the current local time and the local time zone. - * - * **Note:** Subsequent calls return equal times, event if they are minutes apart. _now_ - * actually refers to the `REQUEST_TIME` or, if it is now available, to the first time - * the method was invoked. - * - * @return static + * @inheritdoc */ static public function now() { @@ -124,14 +116,8 @@ public function __set($property, $value) throw new \LogicException("Property is not defined: $property."); } - /** - * Instantiate a new instance with changes properties. - * - * @param array $options - * @param bool $cascade - * - * @return MutableDateTime + * @inheritdoc */ public function with(array $options, $cascade = false) {