PHP Classes

How to Implement the Clock Interface with Package Clock Abstraction: Access the time clock values following PSR-20

Recommend this page to a friend!
  Info   View files View files (27)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2024-04-10 (1 month ago) RSS 2.0 feedNot enough user ratingsTotal: 27 This week: 1All time: 11,116 This week: 69Up
Version License PHP version Categories
clock-abstraction 1.0.0MIT/X Consortium ...8.2.0Time and Date, PSR, PHP 8
Description 

Author

This package can Access the time clock values following PSR-20.

It provides a clock interface definition that extends the PsrClockInterface interface to add a function to get a string representation of the current clock time and another function to set the current time clock from the UTC.

Currently, it provides two classes that implement the clock interface:

- The frozen clock class has the time set to a fixed value.

- The system clock class has the time set to the current system time.

Innovation Award
PHP Programming Innovation award nominee
April 2024
Nominee
Vote
PSR-20 is a PHP Standards Recommendation that defines an interface with functions to perform operations with dates and times.

This package implements PSR-20 with two classes that extend the base interface to provide more functionality.

Each class can be used by applications that need to access the current time or perform operations that may result in moments of the past or future.

Manuel Lemos
Picture of Eric Sizemore
  Performance   Level  
Name: Eric Sizemore is available for providing paid consulting. Contact Eric Sizemore .
Classes: 15 packages by
Country: United States United States
Age: 36
All time rank: 15119 in United States United States
Week rank: 19 Up3 in United States United States Up
Innovation award
Innovation award
Nominee: 4x

Winner: 2x

Instructions

Usage

Make your objects depend on the Esi\Clock\ClockInterface interface. You can then use SystemClock to retrieve the current time or FrozenClock to retrieve a specific time.

For example:

<?php

declare(strict_types=1);

use Esi\Clock\ClockInterface;
use Esi\Clock\FrozenClock;
use Esi\Clock\SystemClock;

class MyCoolObject
{
    public function __construct(private ClockInterface $clock) {}

    public function getCurrentTime(): \DateTimeImmutable
    {
        return $this->clock->now();
    }

    public function freezeTime(): FrozenClock
    {
        if ($this->clock instanceof SystemClock) {
            return $this->clock->freeze();
        }

        return $this->clock->now();
    }
    // ...
}

<?php

declare(strict_types=1);

use Esi\Clock\SystemClock;
// ...
// ...

$clock = new MyCoolObject(new SystemClock('America/New_York'));
\var_dump($clock->getCurrentTime());
/*
class DateTimeImmutable#6 (3) {
  public $date =>
  string(26) "2024-04-10 13:46:30.724222"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(16) "America/New_York"
}
*/

$frozenClock = $clock->freezeTime();
$now = $frozenClock->now();

\var_dump($now);
/*
class DateTimeImmutable#7 (3) {
  public $date =>
  string(26) "2024-04-10 13:46:30.727716"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(16) "America/New_York"
}
*/

\sleep(5);

$stillNow = $frozenClock->now();
\var_dump($stillNow);
/*
class DateTimeImmutable#7 (3) {
  public $date =>
  string(26) "2024-04-10 13:46:30.727716"
  public $timezone_type =>
  int(3)
  public $timezone =>
  string(16) "America/New_York"
}
*/

SystemClock

Object that will return the current time based on the given timezone. The timezone passed to the constructor of SystemClock can either be a string of the timezone identifier, or a DateTimeZone object.

Create a new system clock:

<?php

declare(strict_types=1);

use Esi\Clock\SystemClock;

/
 * You can either create your own \DateTimeZone object to pass to the SystemClock, or
 * you can pass the timezone string. E.g.:
 * 
 * @see https://www.php.net/datetimezone
 *
 * $clock = new SystemClock('America/New_York');
 */
$timezone = new \DateTimeZone('America/New_York');
$clock = new SystemClock($timezone);

$now = $clock->now();

/
 * You can also make use of either `fromUtc()` or `fromSystemTimezone()`
 */
// Create a clock using UTC
$clock = SystemClock::fromUtc();
$now = $clock->now();

// Or the default system timezone
$clock = SystemClock::fromSystemTimezone();
$now = $clock->now();

FrozenClock

Test object that always returns a fixed time object. When creating a FrozenClock, it must be passed a \DateTimeImmutable object in its constructor. See DateTimeImmutable at php.net.

When creating the DateTimeImmutable object to pass into FrozenClock, if instantiated with no arguments it uses now to create the object with the current time. You can also pass a date/time string to set the FrozenClock to a specific time.

You can use DateTimeImmutable directly, or:

Create a new frozen clock:

<?php

declare(strict_types=1);

use Esi\Clock\FrozenClock;

$now = new \DateTimeImmutable();
$clock = new FrozenClock($now);

\sleep(5);

$stillNow = $clock->now();

You can also set the frozen clock to a new time by using it's setTo() method, which also requires a DateTimeImmutable object:

<?php

declare(strict_types=1);

use Esi\Clock\FrozenClock;

$clock = new FrozenClock(new \DateTimeImmutable());
$now = $clock->now();

$clock->setTo(new \DateTimeImmutable('+3 hours'));
$newNow = $clock->now();

You can also create a new frozen clock by freezing a system clock:

<?php

declare(strict_types=1);

use Esi\Clock\SystemClock;

$timezone = new \DateTimeZone('America/New_York');
$clock = new SystemClock($timezone);

$frozenClock = $clock->freeze();

$now = $clock->now();

\sleep(5);

$stillNow = $clock->now();

Details

Clock

Build Status Code Coverage Scrutinizer Code Quality Tests PHPStan Psalm Static analysis

Type Coverage Psalm Level Latest Stable Version Downloads per Month License Mutation testing badge

Yet ...another... PSR-20 Clock implementation.

Installation

Composer

The script can be installed using composer. Add this repository as a dependency to the composer.json file.

$ composer require esi/clock:^1.0

Usage

About

Requirements

  • Clock works with PHP 8.2.0 or above.

Submitting bugs and feature requests

Bugs and feature requests are tracked on GitHub

Issues are the quickest way to report a bug. If you find a bug or documentation error, please check the following first:

  • That there is not an Issue already open concerning the bug
  • That the issue has not already been addressed (within closed Issues, for example)

Contributing

Backward Compatibility Promise

Author

Eric Sizemore - <admin@secondversion.com> - <https://www.secondversion.com>

License

Clock is licensed under the MIT License.


  Files folder image Files  
File Role Description
Files folder image.github (2 files, 1 directory)
Files folder imagesrc (3 files)
Files folder imagetests (1 directory)
Accessible without login Plain text file .php-cs-fixer.dist.php Example Example script
Accessible without login Plain text file .scrutinizer.yml Data Auxiliary data
Accessible without login Plain text file backward-compatibility.md Data Auxiliary data
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file CONTRIBUTING.md Data Auxiliary data
Accessible without login Plain text file infection.json5 Data Auxiliary data
Accessible without login Plain text file LICENSE Lic. License text
Accessible without login Plain text file phpstan.neon Data Auxiliary data
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file psalm.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file renovate.json Data Auxiliary data
Accessible without login Plain text file SECURITY.md Data Auxiliary data
Accessible without login Plain text file USAGE.md Doc. Documentation

  Files folder image Files  /  .github  
File Role Description
Files folder imageworkflows (4 files)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data

  Files folder image Files  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file main.yml Data Auxiliary data
  Accessible without login Plain text file mutations.yml Data Auxiliary data
  Accessible without login Plain text file psalm.yml Data Auxiliary data
  Accessible without login Plain text file tests.yml Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
  Plain text file ClockInterface.php Class Class source
  Plain text file FrozenClock.php Class Class source
  Plain text file SystemClock.php Class Class source

  Files folder image Files  /  tests  
File Role Description
Files folder imagesrc (2 files)

  Files folder image Files  /  tests  /  src  
File Role Description
  Plain text file FrozenClockTest.php Class Class source
  Plain text file SystemClockTest.php Class Class source

 Version Control Unique User Downloads Download Rankings  
 100%
Total:27
This week:1
All time:11,116
This week:69Up