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