PHPackages                             tarasterletskij/true-service-time - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. tarasterletskij/true-service-time

ActiveLibrary[Utility & Helpers](/categories/utility)

tarasterletskij/true-service-time
=================================

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

v2.2.0(3mo ago)03MITPHPPHP ^8.3CI passing

Since Mar 10Pushed 3mo agoCompare

[ Source](https://github.com/tarasterletskij/true-service-time)[ Packagist](https://packagist.org/packages/tarasterletskij/true-service-time)[ RSS](/packages/tarasterletskij-true-service-time/feed)WikiDiscussions main Synced 3w ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

True Service Time
=================

[](#true-service-time)

[![Latest Version on Packagist](https://camo.githubusercontent.com/91bb9ebf92b80047044f637316b12ea5833ed1c6d73cfdf63c4a974df6d06a21/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74617261737465726c6574736b696a2f747275652d736572766963652d74696d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tarasterletskij/true-service-time)[![Tests](https://camo.githubusercontent.com/e2167162edc3f5727f85f77ac8cf8f7683fce5fbe5756e3480f5f6963c305a95/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f74617261737465726c6574736b696a2f747275652d736572766963652d74696d652f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/tarasterletskij/true-service-time/actions/workflows/tests.yml)[![Total Downloads](https://camo.githubusercontent.com/04d00641e9b3d191dcad207474353bc7f2a3f3f99735fc37adc489eceb9c7db1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74617261737465726c6574736b696a2f747275652d736572766963652d74696d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tarasterletskij/true-service-time)

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

Features
--------

[](#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
------------

[](#installation)

```
composer require tarasterletskij/true-service-time
```

Requirements
------------

[](#requirements)

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

Usage
-----

[](#usage)

### Quick Start

[](#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

[](#with-specific-ip-address)

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

### Custom HTTP Client

[](#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

[](#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
------------

[](#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
-----------------

[](#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
--------------

[](#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
-------

[](#testing)

```
# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer phpstan
```

Architecture
------------

[](#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
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance80

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

107d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/57ce0e42a66f770d1d1ca108d6ee6d37c8b1cc31d592f687e21ea6eb9329ca3d?d=identicon)[tarasterletskij](/maintainers/tarasterletskij)

---

Top Contributors

[![tarasterletskij](https://avatars.githubusercontent.com/u/12433743?v=4)](https://github.com/tarasterletskij "tarasterletskij (2 commits)")

---

Tags

clockpsr-20timeserver-time

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tarasterletskij-true-service-time/health.svg)

```
[![Health](https://phpackages.com/badges/tarasterletskij-true-service-time/health.svg)](https://phpackages.com/packages/tarasterletskij-true-service-time)
```

###  Alternatives

[symfony/clock

Decouples applications from the system clock

434192.7M337](/packages/symfony-clock)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)[ecotone/ecotone

Enterprise architecture layer for Laravel and Symfony — CQRS, Event Sourcing, Durable Workflows (Sagas, Orchestrators), Projections, and Outbox messaging via PHP attributes.

562565.8k42](/packages/ecotone-ecotone)[beste/clock

A collection of Clock implementations

7426.0M26](/packages/beste-clock)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

252.5k](/packages/eslazarev-wildberries-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)