thekid/rfc — Issue #115: RFC 0115: Make Date objects represent an instance in time
Author: thekid
Created: 2011-10-09 15:11:46+00:00
State: closed
Labels: implemented, rfc

Scope of Change
====
The Date class will be changed to also hold the timezone offset, thus
making it a representation of an instance in time rather than a certain
date and time.

Also, internally it will be backed by the new DateTime and related
classes provided by PHP5. As part of that, all public members of
util.Date will be removed.

Accessing separate values of the object will be possible through
the public get*()-methods.

The serialization format of util.Date will change completely due to
the internal change - deserialization of objects stored in the old
format will be supported to maintain external backwards compatibility.

The method format() will not support any locale-dependent format
tokens any more. The toString() method can output a Date object
in any requested (and known) timezone.

Rationale
====

Addition of timezone
----
Problems with timezone conversions.

Backing by PHP5's DateTime
----
Many lines with complex date calculations can be removed which
should make util.Date less error prone - provided that DateTime
is in use in the PHP community and therefore error tested.

Also, timezone calculations require a timezone database, which
would be extremely tedious to maintain ourselves. DateTime, in
contrary to util.Date, makes use of either a timezone database
provided by PHP, or the operating system.

Because it slows down speed of util.Date to update the public
member variables every time the backing object has been modified,
the public members will be removed alltogether.

Removing of format() method's locale support
----
Locale support comes from the OS's ability to support those locales,
and as such a feature is obviously heavily OS-dependent and XP's
philosophy is to be as OS independent as possible, any locale
format tokens will be unsupported and throw an exception.

Other tokens are still supported.

Functionality
====
This statement is now true:

```php
equals(new Date('31.12.1999 23:00:00', new TimeZone('Europe/London'))) // London
;
?>
```

A date object can be output in a specified timezone:

```php
toString('r', new TimeZone('Australia/Sydney'));
?>
```

will output:

```
Wed, 25 Jul 2007 06:00:00 +1000

```

Serialization format of an util.Date object will be done using a fully formatted
date string, and will always store the date in GMT.

```php

```

will output:

```
O:4:"Date":2:{s:5:"value";s:24:"2007-07-24 20:00:00+0000";s:4:"__id";N;}

```

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
- PHP 5.2.0 (which is XP-core default requirement)

Related documents
====
- xp-framework/rfc #36 (initial but a bit different idea)

- http://experiments.xp-framework.net/?people,kiesel,rfc0115
Classes implementing this RFC

Comments
====
- kiesel, Tue Jul 24 23:31:15 2007
The default order of how PHP gets the default timezone is:
- the timezone set using the date_default_timezone_set() function (if any)
- the TZ environment variable (if non empty)
- the date.timezone ini option (if set)
- "magical" guess (if the operating system supports it)
- if none of the above options succeeds, return UTC

Should lang.base.php contain:

date_default_timezone_set(ini_get("date.timezone"))

to make XP independent of "TZ" environment variable?

- kiesel, Tue Jul 24 23:40:50 2007
Should a new DateException be introduced which can be used
in util.Date, util.DateUtil, util.Calendar and util.TimeSpan?

- kiesel, Tue Jul 24 23:41:51 2007
The date object supports modifications to an existing object. XP's
util.Date was immutable, and changes to it are only supported through
util.DateUtil - by creating a new object.

Should util.Date be made mutable and introduce new methods to
change its state? Should util.DateUtil be marked as deprecated,
if so?

- kiesel, Wed Aug 29 10:45:38 CEST 2007
Dates should remain immutable.

- kiesel, Wed Aug 29 10:45:57 CEST 2007
No new exception will be introduces at this point.

- kiesel, Tue Sep 4 17:17:41 CEST 2007
lang.base.php will not be changed during this RFC.