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 Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2024-11-17 (3 days ago) RSS 2.0 feedNot enough user ratingsTotal: 35 This week: 5All time: 11,020 This week: 11Up
Version License PHP version Categories
clock-abstraction 1.1.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
Number 2
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  
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 SymfonyInsight

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 (34)  
File Role Description
Files folder image.github (3 files, 2 directories)
Files folder imagesrc (3 files)
Files folder imagetests (1 directory)
Accessible without login Plain text file .gitattributes Data Auxiliary data
Accessible without login Plain text file .gitignore Data Auxiliary data
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 CODE_OF_CONDUCT.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

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:35
This week:5
All time:11,020
This week:11Up