Interfaces and classes supporting empty or null DateTime objects

1.0.0 2021-02-01 11:58 UTC

This package is auto-updated.

Last update: 2023-03-29 01:19:26 UTC



composer require deviantintegral/null-date-time

This package provides classes that decorate \DateTime so that it is always formattable as a string, even if the time is empty or null.

PHP's \DateTime object does not have any way to represent an "empty" date. While there is a \DateTimeInterface class, it's documentation explicitly says it is not for implementation but type hinting only.

We don't want calling code to have to check for null returns on every get call. DateTimeFormatInterface requires that format() return an empty string if the underlying date is not set.

When constructing a DateTime object, a common pattern would be:


function createTime(string $time = null): \Deviantintegral\NullDateTime\DateTimeFormatInterface
  if (null === $time || '' === $time) {
    return new \Deviantintegral\NullDateTime\NullDateTime();

  return \Deviantintegral\NullDateTime\ConcreteDateTime::fromString($time);

$dateTime = createTime('now');
$dateTime->format('U'); // Will return the current Unix timestamp.
if ($dateTime instanceof \Deviantintegral\NullDateTime\ConcreteDateTimeInterface) {
  $dateTime->getDateTime()->getOffset(); // Call any of the usual \DateTime methods.

$dateTime = createTime('');
$dateTime->format('U'); // Will return an empty string.