README

Arp\DateTime

About

The library provides implementations of the PSR-20 Clock ClockInterface and a number of factories which abstract the creation of native PHP DateTime objects.

Installation

Installation via composer.

require alex-patterson-webdev/date-time ^0.6

Theory

By abstracting the creation of Date Time objects behind a simple collection of interfaces, we can allow developers to treat date time creation as a service. The Arp\DateTime\DateTimeFactory can be used as a replacement for any code that would normally require new \DateTime().

Consider an example UserService::updateLastLoginDate() method; designed to update a user's last login date with the current date and time.

class UserService
{
    public function updateLastLoginDate($user)
    {
        $user->setLastLoginDate(new \DateTime());
    }
}

This approach, while simple, would be difficult to assert a value for the 'current time' in a unit test. Alternatively, we could update this example to include the DateTimeFactory, which would abstract the creation of the \DateTime object.

class UserService
{
    private DateTimeFactoryInterface $dateTimeFactory;

    public function __construct(DateTimeFactoryInterface $dateTimeFactory)
    {
        $this->dateTimeFactory = $dateTimeFactory;
    }

    public function updateLastLoginDate($user)
    {
        $user->setLastLoginDate($this->dateTimeFactory->createDateTime());
    }
}

The approach has a number of notable benefits

• The DateTimeFactoryInterface provides an abstraction for all \DateTime object creation.
• Unit testing and asserting date time values becomes very easy as we can now mock the return value of $this->dateTimeFactory->createDateTime().
• Rather than returning a boolean false when unable to create date objects, the factory classes will instead throw a DateTimeException.

DateTimeFactoryInterface

The DateTimeFactoryInterface exposes two public methods, createDateTime() and createFromFormat(). The method signatures are similar to the PHP \DateTime methods.

interface DateTimeFactoryInterface
{
    /**
     * @throws DateTimeFactoryException
     */
    public function createDateTime(?string $spec = null, $timeZone = null): \DateTimeInterface;

    /**
     * @throws DateTimeFactoryException
     */
    public function createFromFormat(string $format, string $spec, $timeZone = null): \DateTimeInterface;
}

The createDateTime() method can replace uses of \DateTime::__construct. The createFromFormat() method can replace uses of \DateTime::createFromFormat().

There are however a number of differences to consider.

• The methods of the interface are defined as non-static and require a factory instance to invoke them.
• A DateTimeFactoryException will be thrown if the \DateTime instance cannot be created.
• The $spec parameter of createDateTime() accepts null. Passing null is equivalent to using the current date and time, i.e. now.
• The $timeZone can be either a string or \DateTimeZone instance. If a supported DateTimeZone string is provided, the \DateTimeZone instance will be created internally; otherwise a DateTimeFactoryException will be thrown.

Implementations

The package provides two default implementations of the DateTimeFactoryInterface.

• DateTimeFactory can be used to create \DateTime instances.
• DateTimeImmutableFactory can be used to create \DateTimeImmutible instances

Because both classes implement the DateTimeFactoryInterface, they can be used in the same way.

$dateTimeFactory = new \Arp\DateTime\DateTimeFactory();
$dateTimeImmutableFactory = new \Arp\DateTime\DateTimeImmutableFactory();

try {
    /** @var \DateTime $dateTime **/
    $dateTime = $dateTimeFactory->createDateTime();

    /** @var \DateTimeImmutable $dateTimeImmutable **/
    $dateTimeImmutable = $dateTimeImmutableFactory->createDateTime();
} catch (\DateTimeFactoryException $e) {
    // if the date creation fails
}

DateTimeZoneFactory

\DateTimeZone instances can be created using any class that implements Arp\DateTime\DateTimeZoneFactoryInterface.

/*
 * @throws DateTimeZoneFactoryException
 */
public function createDateTimeZone(string $spec): \DateTimeZone;

The default implementation of the interface is Arp\DateTime\DateTimeZoneFactory.

$dateTimeZoneFactory = new \Arp\DateTime\DateTimeZoneFactory();

try { 
    /** @var \DateTimeZone $dateTimeZone **/
    $dateTimeZone = $dateTimeZoneFactory->createDateTimeZone('UTC');
} catch (\DateTimeZoneFactoryException $e) {
    // The \DateTimeZone() could not be created
}

PSR-20 ClockInterface

Using the PSR standards provides implementing projects interoperability between other packages by creating a standard way of accessing the current time.

The package provides a number of implementations of the PSR-20 Clock interface.

• Arp\DateTime\Psr\Clock A default implementation of Psr\Clock\ClockInterface where a desired DateTimeZone can be provided.
• Arp\DateTime\Psr\SystemClock An implementation of Psr\Clock\ClockInterface that will always provide the current time using the configured system timezone.
• Arp\DateTime\Psr\FixedClock An implementation of Psr\Clock\ClockInterface that will always return a fixed \DateTimeImmutable; which can be useful in testing.

Example usages

use Arp\DateTime\DateTimeImmutableFactory;
use Arp\DateTime\Psr\SystemClock;

// Fetch the current time using the UTC timezone
$clock = new Clock(new DateTimeImmutableFactory(), 'UTC');
$utcTime = $clock->now();

// Fetch the current time using the systems configured timezone
$clock = new SystemClock(new DateTimeImmutableFactory());
$systemTime = $clock->now();

// Calls to FixedClock::now() will always return the same time provided in the constructor 
$clock = new FixedClock(new \DateTimeImmutable());
$fixedTime = $clock->now();

Unit tests

Unit tests can be executed using PHPUnit from the application root directory.

php vendor/bin/phpunit