Общий интерфейс для доступа к часам

Этот документ описывает простой интерфейс для чтения системных часов.

Ключевые слова «ОБЯЗАН», «НЕ ДОЛЖЕН», «REQUIRED», «SHALL», «SHALL NOT», «СЛЕДУЕТ», «SHOULD NOT», «RECOMMENDED», «МОЖЕТ» и «OPTIONAL» в данном документе следует интерпретировать так, как описано в RFC 2119.

Финальные реализации МОГУТ дополнять объекты дополнительной функциональностью сверх предложенной, однако они ОБЯЗАНЫ в первую очередь реализовать указанные интерфейсы/функциональность.

1. Спецификация

1.1 Введение

Создание стандартного способа доступа к часам обеспечит совместимость при тестировании поведения, которое имеет побочные эффекты, зависящие от времени. Распространённые способы получить текущее время включают вызов \time() или new DateTimeImmutable('now'). Однако в некоторых ситуациях это делает подмену текущего времени невозможной.

1.2 Определения

• Часы (Clock) — часы способны считывать текущее время и дату.

• Временная метка (Timestamp) — текущее время в виде целого числа секунд, прошедших с 1 января 1970 00:00:00 UTC.

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

Ниже описаны наиболее распространённые паттерны использования:

Получение текущей временной метки

Это следует делать с помощью метода getTimestamp() на возвращаемом объекте \DateTimeImmutable:

$timestamp = $clock->now()->getTimestamp();

2. Интерфейсы

2.1 ClockInterface

Интерфейс часов определяет наиболее базовую операцию чтения текущего времени и даты с часов. Он ОБЯЗАН возвращать время в виде объекта DateTimeImmutable.

<?php

namespace Psr\Clock;

interface ClockInterface
{
    /**
     * Returns the current time as a DateTimeImmutable Object
     */
    public function now(): \DateTimeImmutable;

}