Should I use `DateTimeInterface` in my php project? - php

Question

Recently, I discovered that there is a DateTimeInterface. As I was working with \DateTime and \DateTimeImmutable, I thought that it'd be good to typehint for.
Yet on the Changelog on php.net it says that since 5.5.8:
Trying to implement DateTimeInterface raises a fatal error now. Formerly implementing the interface didn't raise an error, but the
behavior was erroneous.
This reads that I never be able to implement my own CustomDateTime class implementing the DateTimeInterface, which seems rather odd.
Should I use the DateTimeInterface in my userland code?
My gut feeling tells me not to. Yet it also doesn't feel right to typehint the object, i.e.
#var \DateTime|\DateTimeImmutable|\MyCustomDateTime

Answer 1

You can use the DateTimeInterface typehint when you expect either one of the native DateTime variants, e.g. \DateTime or \DateTimeImmutable.
But as the docs say
It is not possible to implement this interface with userland classes.
So if you plan to implement \DateTimeInterface with your own implementation, this will not work, e.g.
class MyDateTime implements \DateTimeInterface {} // will raise an error
However, you can create your own interface and adapt the native DateTime classes.
interface MyDateTime { /* some methods */ }
class NativeDateTime implements MyDateTime
{
private $dateTime;
public function __construct($args = 'now') {
$this->dateTime = new \DateTimeImmutable($args);
}
/* some methods */
}
Or you can extend the native DateTime variants, which will then implement the DateTimeInterface obviously, e.g.
class MyDateTime extends \DateTimeImmutable
{
/* your modifications */
}
var_dump(new MyDateTime instanceof \DateTimeInterface); // true
Details why you cannot implement your own classes implementing \DateTimeInterface:
https://github.com/php/php-src/pull/512
https://www.mail-archive.com/internals#lists.php.net/msg79534.html
tl;dr core functions that accept DateTime and DateTimeImmutable (DateTimeInterface basically) operate directly on timelib structures hence they will break if you pass them a user-defined class. There's a workaround though - it's to always call user-defined class's method directly from built-in functions, so if you would call (new DateTime())->diff(new UserDefinedDateTime()) it would call UserDefinedDateTime#diff in the end which would need to implement the logic.

Answer 2

I would say you should not.
The \DateTimeInterface is an implementation detail of ext/date that should not have been exposed to userland code.
See the RFC created for removing it: https://wiki.php.net/rfc/drop-datetimeinterface

Answer 3

You are encouraged to type hint against DateTimeInterface when you accept
DateTime
DateTimeImmutable
Any class derived from these
You can however not implement DateTimeInterface without extending from either DateTime or DateTimeImmutable due to internal details.
You can ignore https://wiki.php.net/rfc/drop-datetimeinterface as by now - years after the question - we know that the community decided against removing the interface.