PHPackages                             cemerson/clock - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. cemerson/clock

Abandoned → [psr/clock](/?search=psr%2Fclock)Library[Utility & Helpers](/categories/utility)

cemerson/clock
==============

Ultra-simple clock abstraction for PHP 7+, allowing developers to properly mock time-related functions

v3.0(3y ago)02.0k1MITPHPPHP ^7.4 | ^8.0

Since Aug 25Pushed 3y ago1 watchersCompare

[ Source](https://github.com/chrisemerson/clock)[ Packagist](https://packagist.org/packages/cemerson/clock)[ RSS](/packages/cemerson-clock/feed)WikiDiscussions main Synced yesterday

READMEChangelogDependencies (1)Versions (6)Used By (1)

Clock
=====

[](#clock)

!DEPRECATED - DO NOT USE!
-------------------------

[](#deprecated---do-not-use)

Since this package was created, [PSR-20](https://www.php-fig.org/psr/psr-20/) has been proposed and accepted, and serves the same purpose as this package. It is highly recommended that you use PSR-20 instead of this package, as it is likely to receive a lot more community support and compatibility in the future.

v2.0 and v3.0 of cemerson/clock includes an adapter to help switch to a PSR-20 compatible clock interface, as well as having the provided `WallClock` implementation implement the newer interface too. You should switch out your dependent code to using `ClockInterface` instead. v2.0 implemented the interface from `stella-maris/clock` which provided a PSR-20-like interface while PSR-20 was under development. v3.0 removes this dependency and implements the PSR-20 interface directly now that it has been finalised and accepted.

**TLDR; There will be no further work done on this package! Migrate your code to use `psr/clock`**

Original ReadMe
---------------

[](#original-readme)

You can use this library to help unit test applications that have a reliance on the clock in some way.

Rationale
---------

[](#rationale)

Unit tests are better when they are completely isolated from the environment in which they are run, and don't ever access parts of that environment such as databases, file system, network sockets or even the current time. I have come across multiple examples of unit tests whose results changed based on when you run them, because they rely on the PHP time functions and behaviour changes as a result.

It's important to be able to test some classes with different time or date related inputs being used to test different aspects. Some libraries exist that let you change the results of the built in time functions by calling some code, but to me the solution is much simpler - you should isolate your code from the clock by injecting it into the class instead, therefore allowing you to mock the results using your favourite unit testing framework.

Libraries that I have found so far using this either come as part of a much bigger library that I didn't require all the complexity of, or didn't have a stable release tagged, or had other issues, so I created this library to use instead. I would often create a similar interface in applications and thought I may as well make it a reusable component.

It is deliberately ultra-simple, with no frills, containing just enough to achieve the required results without any added complexity.

Installing
----------

[](#installing)

Clock requires PHP 7. Install via composer:

```
composer require cemerson/clock

```

Usage
-----

[](#usage)

Whenever you have a class that needs to reference the current time, don't call any time related functions in PHP. Instead, hint for and inject the `Clock` interface from this library.

In production, you can set up your dependency injection container to inject the provided `Wallclock` class to obtain the current time. This class takes a `DateTimeZone` object in the constructor and provides a `DateTimeImmutable` object with the current time, using the time zone provided when its `getDateTime()` method is called.

```