Feature - DateTime::createFromImmutable() method

[Rican7]

Introduction

The DateTimeImmutable class, added in version 5.5, was a very convenient addition to the bundled date/time extension. Unfortunately, when migrating legacy codebases or when using an application that needed to mix immutable/mutable instances, the DateTimeImmutable class fell short in convenience by not providing a clear/clean way to build an immutable instance from a mutable instance.

This problem was solved in version 5.6 with the addition of a convenient factory method: DateTimeImmutable::createFromMutable(). Unfortunately, however, this addition created a one-sided convenience where a similar problem has been unresolved: Its still just as difficult to create mutable DateTime instances from an immutable DateTimeImmutable instance.

Arguably, creating DateTime instances from the immutable representations is something that an application would actually do more often, as any current (or legacy) applications and libraries are more likely to have function/method API's that require DateTime instances as parameters. While ideally the parameter types of new libraries would be DateTimeInterface (or at least DateTimeImmutable), that option is only available to libraries and applications that support PHP 5.5 as a minimum version... which is currently not the majority.

Without this factory method available to the DateTime class, its quite cumbersome to translate back and forth between the types, and honestly is quite the deterrent to even using the DateTimeImmutable class because of this. For example, if I was using a new library or application that dealt with DateTimeImmutable objects, but still had to interact with current/older libraries, I'd need to do work like this quite often:

// Use some cool new library that returns a `DateTimeImmutable`
$date_time_immutable = $new_cool_library->getStartTime();

// Use an existing library that accepts a `DateTime` concrete type
$date_time = new DateTime(null, $date_time_immutable->getTimeZone());
$date_time->setTimestamp($date_time_immutable->getTimestamp());
$existing_event_library->setTriggerAt($date_time);

As you can imagine, doing the above for multiple calls around an application/library is quite cumbersome, and often leads to potentially buggy user-land implementations to keep the code "DRY" or even worse: simply deters a library/application author from using the new DateTimeImmutable object despite its wonderful advantages.

Proposal

This PR proposes to introduce a single new method on the DateTime class with the following signature:

public static DateTime DateTime::createFromImmutable (DateTimeImmutable $datetime)

The resulting object would contain the same date/time value as the provided immutable parameter, however modifications to the resultant DateTime object would only modify that instance and not the immutable instance that was given as an argument. In other words, this simply copies state. It would be quite similar to a type-casted clone (if that were possible).

This proposal was designed to mirror the currently accepted and in-use DateTimeImmutable::createFromMutable() method. It contains a similar signature and would compliment the aforementioned method well.

Backward Incompatible Changes

None. This is a new static method on the concrete DateTime class (not on the Interface), so no extending classes would have to worry about breaking here.

Proposed PHP Version(s)

PHP 7

Affected PHP Functionality

To SAPIs

None

To Existing Extensions

None

To Opcache

None

[ghost]

Can one of the admins verify this patch?

[smalyshev]

Looks ok. @jpauli, @Tyrael - what do you think about merging this into 5.5/5.6?

[derickr]

The */ should be on the previous line, at the end.

[Rican7]

I was just following the file's current style, which has the ending comment marker on a new line. Examples:

• https://github.com/Rican7/php-src/blob/429b0bb38a32b85e2f56d7669724f1c5aa902baa/ext/date/php_date.c#L2592-L2594
• https://github.com/Rican7/php-src/blob/429b0bb38a32b85e2f56d7669724f1c5aa902baa/ext/date/php_date.c#L3741-L3743
• https://github.com/Rican7/php-src/blob/429b0bb38a32b85e2f56d7669724f1c5aa902baa/ext/date/php_date.c#L4089-L4091

[Rican7]

Travis is 💚

[Rican7]

Oh wow! Thank you so much! My first official PHP source-code contribution! 😊

[smalyshev]

Reverted following ML discussion and Derick's objections here: http://markmail.org/message/3aesaaoqv6ihiw53#query:+page:1+mid:ukwizupev32ld5tg+state:results
Looks like this needs an RFC.

[Kubo2]

@smalyshev @php-pulls Shouldn't this one be reopened?
@Rican7 👍

[Majkl578]

What has happened to this PR? I guess noone cared enough to make an RFC? :(
Absence of this method is another great incompatibility in PHP core...

The arguments in http://markmail.org/message/3aesaaoqv6ihiw53#query:+page:1+mid:ukwizupev32ld5tg+state:results do not make any sense. This method is not intended for emulating immutability in PHP <5.5.
How should one proceed when a library relies on DateTime only, for BC reasons? E.g. semver does not allow changing method signature from DateTime to DateTimeInterface.

So now, instead of clean:

DateTime::createFromImmutable($dateTime)

one has to write a nonsense like this:

DateTime::createFromFormat(\DateTime::ISO8601, $dateTime->format(\DateTime::ISO8601), $dateTime->getTimezone())

Is this really what you indirectly suggest, @derickr?

[Kubo2]

+1

On 26 August 2015 at 18:44, Michael Moravec notifications@github.com
wrote:

What has happened to this PR? I guess noone cared enough to make an RFC? :(
Absence of this method is another great incompatibility in PHP core...

The arguments in
http://markmail.org/message/3aesaaoqv6ihiw53#query:+page:1+mid:ukwizupev32ld5tg+state:results
do not make any sense. This method is not intended for emulating
immutability in PHP <5.5.
How should one proceed when a library relies on DateTime only, for BC
reasons? E.g. semver does not allow changing method signature from DateTime
to DateTimeInterface.

So now, instead of clean:

DateTime::createFromImmutable($dateTime)

one has to write a nonsense like this:

DateTime::createFromFormat(\DateTime::ISO8601, $dateTime->format(\DateTime::ISO8601), $dateTime->getTimezone())

Is this really what you indirectly suggest, @derickr
https://github.com/derickr?

—
Reply to this email directly or view it on GitHub
#1145 (comment).

[enumag]

ping @derickr

Your reason is not exactly valid. I want to use DateTimeImmutable everywhere in my application. However there are some libraries then historically require DateTime instead of DateTimeInterface. I need to convert the DateTimeImmutable I work with normally to DateTime when calling them.

[Majkl578]

Hi, I opened #2484 as a follow-up, because I still think this is a legitimate feature and the objections against did not make much sense.