README

Предоставляет интерфейс и простую реализацию службы для получения текущего времени и часового пояса.

Чем плох распространённый подход с определением текущего времени с помощью new DateTimeImmutable(), date_create() и т. п.?

Вы полагаетесь глобальное состояние, которое не контролируете. Достаточно какой-нибудь, используемой вами сторонней библиотеке изменить часовой пояс, и приведённые выше конструкции начнут возвращать время в другом часовом поясе. И это может происходить только при определённых условиях, что крайне трудно выявить при отладке.
Такой код сложно тестировать. Сравнение фактического и реального времени в тестах превращается в лотерею с заданием допусков промежутков времени. Либо вообще происходит отказ от проверки времени в тестах.

Одно из возможных решений — служба времени, к которой обращается ваш код, чтобы узнать текущее время. Пример:

<?php
use DobroSite\TimeService\TimeService;

class SomeService {
  private TimeService $timeService;
  
  // Внедряем в ваш класс службу времени в качестве зависимости.
  public function __construct(TimeService $timeService)
  {
    $this->timeService = $timeService;
  }
  
  public function someMethod(): void
  {
    // Когда вам потребуется текущее время, обратитесь к службе времени:
    $currentTime = $this->timeService->getCurrentTime();
  }
}

Вы получаете полный контроль над временем в вашем приложении. Используя разные реализации интерфейса TimeService вы можете получать время из разных источников: системное время, сервер NTP и т. п. Так же вы можете задать в конфигурации нужный часовой пояс, который не может быть изменён без вашего ведома сторонним кодом.
Вы можете подменять в тестах службу времени тестовым двойником, чтобы тестируемый код получал заранее предопределённое время.
Написав свою реализацию, вы можете заставить ваше приложение перемещаться в будущее или прошлое, задавая нужное смещение относительно текущего времени. Это может быть полезно в приёмочном тестировании для проверки функций, которые должны выполниться через какой-то промежуток после некоторого действия.

Установка

composer require dobrosite/time-service

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

TimeService

Используйте интерфейс TimeService в качестве зависимости в классах, которым требуется получать текущее время.

Вы можете написать свою реализацию этого интерфейса, либо воспользоваться готовыми реализациями:

PhpTimeService — использует встроенные средства PHP.

Тестирование

TestTimeService

Тестовый двойник TimeService всегда возвращающий заданное время. Задать нужное время можно методом TestTimeService::setCurrentTime().

dobrosite / time-service

Maintainers

Details