lendable / clock
Clock Abstraction
Installs: 200 070
Dependents: 0
Suggesters: 0
Security: 0
Stars: 14
Watchers: 36
Forks: 3
Open Issues: 1
Requires
- php: >=8.2
- psr/clock: ^1.0
Requires (Dev)
- infection/infection: ^0.29.6
- lendable/composer-license-checker: ^1.2.1
- lendable/phpunit-extensions: ^0.3
- liuggio/fastest: ^1.8
- mikey179/vfsstream: ^1.6.11
- php-cs-fixer/shim: ^3.61.1
- php-parallel-lint/php-parallel-lint: ^1.4.0
- phpstan/phpstan: ^1.11.9
- phpstan/phpstan-deprecation-rules: ^1.2.0
- phpstan/phpstan-phpunit: ^1.4.0
- phpstan/phpstan-strict-rules: ^1.6.0
- phpunit/phpunit: ^11.3.0
- rector/rector: ^1.2.2
Provides
This package is auto-updated.
Last update: 2024-11-21 11:53:51 UTC
README
The Lendable Clock library provides an object-oriented interface for accessing the system time in PHP. While PHP offers direct instantiation of \DateTime
, and \DateTimeImmutable
to obtain the current system time, this library introduces the concept of a Clock to offer greater control and flexibility over time-related operations.
Why Use a Clock?
You might wonder why you need a clock when you can simply instantiate \DateTime
objects whenever you need them. Here's why a Clock abstraction is beneficial:
-
Control Over Time: By depending on a Clock rather than instantiating time objects directly, you gain the ability to reason about and control time within your application.
-
Testing Flexibility: Using a Clock allows you to swap underlying implementations, making it easier to test time-dependent code. You can stub time with fixed values, simulate time passing, and observe interactions with the Clock for more robust testing.
-
Dependency Management: Clear dependencies on the Clock class help in managing components that rely on accessing the current system time.
-
PSR-20 Compatibility: The library aligns with PSR-20, offering interoperability with other libraries and frameworks.
Installation
You can install the Lendable Clock library via Composer.
composer require lendable/clock
Clock Types
The library provides several types of Clocks to suit different use cases:
SystemClock
- Target: Runtime
- Description: Delegates to PHP for the current system time, using a fixed timezone at construction.
FixedClock
- Target: Unit/Functional Tests
- Description: Always provides a specific timestamp provided at construction, facilitating deterministic testing.
$clock = new FixedClock(new \DateTimeImmutable('2024-03-01 14:19:41')); echo $clock->now()->format('Y-m-d H:i:s'), "\n"; sleep(5); echo $clock->now()->format('Y-m-d H:i:s'), "\n";
2024-03-01 14:19:41
2024-03-01 14:19:41
TickingMockClock
- Target: Unit/Functional Tests
- Description: Mocks time starting from a given timestamp and simulates time progressing from that point. Useful for testing time-dependent functionality.
$clock = TickingMockClock::tickingFromCurrentTime(new \DateTimeImmutable('2024-03-01 14:19:41')); echo $clock->now()->format('Y-m-d H:i:s.u'), "\n"; sleep(5); echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";
2024-03-01 14:19:41.000006
2024-03-01 14:19:46.005175
PersistedFixedClock
- Target: Functional Tests (e.g., Behat vs. Symfony Kernel)
- Description: Similar to
FixedClock
, but can persist and load the given timestamp from disk. Ideal for scenarios where you need to reload your context during testing.
Use PersistedFixedClock::initializeWith(...)
to set up the timestamp and PersistedFixedClock::fromPersisted(...)
to load from the persisted value on disk.
By leveraging these Clock types, you can enhance the reliability, testability, and maintainability of your time-dependent PHP applications.
$clock = PersistedFixedClock::initializeWith( __DIR__, new FixedFileNameGenerator('time.json'), new \DateTimeImmutable('2024-03-01 14:19:41'), ); echo $clock->now()->format('Y-m-d H:i:s.u'), "\n"; sleep(5); $clock = PersistedFixedClock::fromPersisted(__DIR__, new FixedFileNameGenerator('time.json')); echo $clock->now()->format('Y-m-d H:i:s.u'), "\n";
2024-03-01 14:19:41.000000
2024-03-01 14:19:41.000000