tarasterletskij/true-service-time

PSR-20 Clock implementation that fetches accurate server time based on IP geolocation using external time APIs.

v2.2.0 2026-03-10 18:30 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.8
• psr/clock: ^1.0

Requires (Dev)

• mockery/mockery: ^1.6
• phpstan/phpstan: ^1.10
• phpunit/phpunit: ^11.0

MIT

• Taras Terletskiy

• time
• clock
• psr-20
• server-time

README

Get accurate server time and timezone based on IP address using external time APIs. Returns PSR-20 ClockInterface.

Features

• PSR-20 Clock interface implementation
• Time API provider using TimeAPI.io
• Automatic external IP detection via ipify.org
• Exception-based error handling
• Configurable HTTP client (Guzzle)
• Full test coverage with PHPUnit
• PHPStan level max compliance

Installation

composer require tarasterletskij/true-service-time

Requirements

• PHP 8.3+
• ext-json
• guzzlehttp/guzzle ^7.8
• psr/clock ^1.0

Usage

Quick Start

use TrueServiceTime\Application\Factory\TimeServiceFactory;

try {
    $service = TimeServiceFactory::create();
    $clock = $service->getServerTime();

    echo $clock->now()->format('Y-m-d H:i:s');
    echo $clock->now()->getTimezone()->getName();
} catch (\Exception $e) {
    // Handle error
}

With Specific IP Address

$service = TimeServiceFactory::create();
$clock = $service->getServerTime('8.8.8.8');

Custom HTTP Client

use GuzzleHttp\Client;
use TrueServiceTime\Application\Factory\TimeServiceFactory;

$httpClient = new Client([
    'timeout' => 10.0,
    'verify' => true,
]);

$service = TimeServiceFactory::create($httpClient);
$clock = $service->getServerTime();

Manual Configuration

use GuzzleHttp\Client;
use TrueServiceTime\Application\Service\TimeService;
use TrueServiceTime\Infrastructure\TimeProvider\TimeApiIoProvider;
use TrueServiceTime\Infrastructure\IpDetector\IpApiDetector;

$httpClient = new Client(['timeout' => 5.0]);

$timeProvider = new TimeApiIoProvider($httpClient);
$ipDetector = new IpApiDetector($httpClient);
$service = new TimeService($timeProvider, $ipDetector);
$clock = $service->getServerTime();

How It Works

1. IP Detection (if not provided): Calls ipify.org API to get external IP address
2. Time Retrieval: Fetches server time from TimeAPI.io based on IP geolocation
3. PSR-20 Clock: Wraps result in ClockInterface implementation
4. Error Handling: Throws exceptions on failure for proper error handling

API Services Used

• TimeAPI.io - Time provider (no API key required)
• ipify.org - IP detection service (no API key required)

All services are free and require no registration.

Error Handling

The package throws exceptions on errors for proper error handling:

use TrueServiceTime\Domain\Exception\TimeProviderException;
use TrueServiceTime\Domain\Exception\IpDetectionException;

$service = TimeServiceFactory::create();

try {
    $clock = $service->getServerTime();
} catch (TimeProviderException $e) {
    // Handle time provider API failure
} catch (IpDetectionException $e) {
    // Handle IP detection failure
} catch (\InvalidArgumentException $e) {
    // Handle invalid IP address
}

Exceptions:

• TimeProviderException - Time API failure or invalid response
• IpDetectionException - IP detection API failure
• InvalidArgumentException - Invalid IP address format

Timeouts:

• Time API: 5 seconds
• IP detection: 3 seconds

Testing

# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer phpstan

Architecture

src/
├── Domain/
│   ├── Entity/ServerTime.php
│   ├── ValueObject/IpAddress.php
│   ├── ValueObject/TimeZone.php
│   ├── Interface/TimeProviderInterface.php
│   ├── Interface/IpDetectorInterface.php
│   └── Exception/
├── Application/
│   ├── Service/TimeService.php
│   ├── Clock/ServerTimeClock.php
│   └── Factory/TimeServiceFactory.php
└── Infrastructure/
    ├── TimeProvider/
    │   ├── TimeProviderInterface.php
    │   └── TimeApiIoProvider.php
    └── IpDetector/
        ├── IpDetectorInterface.php
        └── IpApiDetector.php

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.