phpsoftbox / clock

v1.0.0 2026-09-29 10:23 UTC

Requires

• php: ^8.5
• psr/clock: ^1.0

Requires (Dev)

• phpsoftbox/cs-fixer: ^1.2.2
• phpunit/phpunit: ^13.3

MIT

• Anton K.

Published on Packagist.org on 2026-09-29 10:29 UTC

README

Минимальный PSR-20 совместимый компонент времени.

Использование

use PhpSoftBox\Clock\Clock;

$now = Clock::now();

Фиксация времени (тесты)

use PhpSoftBox\Clock\Clock;

Clock::freeze(new \DateTimeImmutable('2026-02-27 00:00:00'));
// ... тесты
Clock::reset();

Путешествие во времени (тесты)

use PhpSoftBox\Clock\Clock;

Clock::freeze(new \DateTimeImmutable('2026-02-27 00:00:00'));
Clock::travel(60); // +60 секунд
Clock::travel('+1 hour'); // или строкой
Clock::reset();

DatePoint

DatePoint — value object, реализует DateTimeInterface и создаётся от Clock::now():

use PhpSoftBox\Clock\DatePoint;

$createdAt = new DatePoint();

DatePoint сохраняет таймзону исходного значения целиком, включая именованную (Europe/Berlin), поэтому арифметика через переход на летнее/зимнее время работает по правилам зоны. Исключение — момент в повторяющемся часе при переходе на зимнее время: его нельзя однозначно восстановить по локальному времени, и такая точка получает таймзону-смещение (+01:00), сохраняя сам момент времени.

Разбор строки

use PhpSoftBox\Clock\DatePoint;

$a = DatePoint::fromString('2026-02-27 12:30:00');          // свободный разбор PHP
$b = DatePoint::fromString('27/02/2026 12:30', 'd/m/Y H:i'); // строго по формату
$c = DatePoint::fromString('2026-02-27', '!Y-m-d');          // 2026-02-27 00:00:00
$d = DatePoint::fromString('2026-02-27', 'Y-m-d');           // время берётся из Clock::now()

• С явным форматом строка обязана ему соответствовать: при несовпадении, лишних данных или несуществующей дате (2024-02-30) бросается InvalidArgumentException. Свободного разбора «на всякий случай» нет.
• Если в формате нет ! или |, недостающие поля (дата и/или время) берутся из Clock::now() (в таймзоне значения), а не из системных часов, поэтому Clock::freeze() действует и здесь.
• Без формата используется свободный разбор PHP; относительные выражения (+1 day, tomorrow) считаются от системного времени — для замороженного времени используйте Clock::now()->modify(...). Неразбираемая строка — InvalidArgumentException.