README.md

Clock

Provides current time for runtime and controllable time for testing

PSR-20 compatible

Content

• Setup
• Current time
• Sleep
• Shortcut function
• Clock
  • System clock
  • Frozen clock
  • Measurement clock
• Clock adapters
  • PSR to Orisai clock adapter
  • Symfony to Orisai clock adapter
  • Orisai to Symfony clock adapter
• Integrations and extensions

Setup

Install with Composer

composer require orisai/clock

Create Clock instance and setup for shortcut function usage

use Orisai\Clock\SystemClock;
use Orisai\Clock\ClockHolder;

$clock = new SystemClock();
ClockHolder::setClock($clock);

Current time

Request Clock interface and get current time (or Psr\Clock\ClockInterface for psr/clock compatibility)

use Orisai\Clock\Clock;

class ExampleService
{

	private Clock $clock;

	public function __construct(Clock $clock)
	{
		$this->clock = $clock;
	}

	public function doSomething(): void
	{
		$currentTime = $this->clock->now();
	}

}

Sleep

To prevent waiting periods in tests, replace calls to sleep() and usleep() functions with Clock->sleep() method.

$clock->sleep(
	1, // Seconds
	2, // Milliseconds
	3, // Microseconds
);

Or with named arguments, just:

$clock->sleep(microseconds: 10);

Shortcut function

Get current time statically

use function Orisai\Clock\now;

$currentTime = now(); // \DateTimeImmutable

It is also possible to access clock statically

use Orisai\Clock\ClockHolder;

$clock = ClockHolder::getClock();

Clock

System clock

For standard usage in application runtime. Returns same time as new DateTimeImmutable('now') would.

use Orisai\Clock\SystemClock;

$clock = new SystemClock();

Specify timezone (otherwise current timezone is used)

use DateTimeZone;

$clock = new SystemClock(new DateTimeZone('UTC'));

Frozen clock

For testing exact times. Does not change unless explicitly requested.

use Orisai\Clock\FrozenClock;

$timestamp = 0.0;
$clock = new FrozenClock($timestamp);
$clock->now()->format('U.u'); // 0.000_000

Specify timezone (otherwise current timezone is used)

use DateTimeZone;

$clock = new FrozenClock(0, new DateTimeZone('UTC'));

You can also create clock from datetime

use DateTime;
use DateTimeImmutable;

$clock = new FrozenClock(new DateTimeImmutable());
// or
$clock = new FrozenClock(new DateTime());

Sleeping does not put thread to sleep but just moves timestamp of clock's internal DateTimeImmutable.

Measurement clock

For accurate measurement of time. Unlike standard system clock is not affected by clock drifting (which is wanted for normal usage, but makes time measuring unreliable).

use Orisai\Clock\MeasurementClock;

$clock = new MeasurementClock();

Specify timezone (otherwise current timezone is used)

use DateTimeZone;

$clock = new MeasurementClock(new DateTimeZone('UTC'));

Clock adapters

Use ClockAdapterFactory to automatically create the best adapter for Orisai\Clock\Clock compatibility from your Psr\Clock\ClockInterface.

• It creates no adapter for Orisai\Clock\Clock instance and just returns it
• It prefers Symfony adapter over PSR adapter for sleep() method compatibility

use Orisai\Clock\Adapter\ClockAdapterFactory;
use Symfony\Component\Clock\NativeClock;

$clock = ClockAdapterFactory::create($somePsrCompatibleClock);

PSR to Orisai clock adapter

Decorate any Psr\Clock\ClockInterface implementation to conform interface Orisai\Clock\Clock.

use Orisai\Clock\Adapter\PsrToOrisaiClockAdapter;

$clock = new PsrToOrisaiClockAdapter(new ExamplePsrClock());

Symfony to Orisai clock adapter

Decorate any Symfony\Component\Clock\ClockInterface implementation to conform interface Orisai\Clock\Clock.

use Orisai\Clock\Adapter\SymfonyToOrisaiClockAdapter;
use Symfony\Component\Clock\NativeClock;

$clock = new SymfonyToOrisaiClockAdapter(new NativeClock());

Orisai to Symfony clock adapter

Decorate any Orisai\Clock\Clock implementation to conform interface Symfony\Component\Clock\ClockInterface.

use Orisai\Clock\Adapter\OrisaiToSymfonyClockAdapter;
use Orisai\Clock\SystemClock;

$clock = new OrisaiToSymfonyClockAdapter(new SystemClock());

Integrations and extensions

• Nette integration - orisai/nette-clock