PHPackages                             hexogen/timesync - 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. hexogen/timesync

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

hexogen/timesync
================

A simple time synchronization library for PHP.

v0.3.1(1mo ago)03↓100%MITPHPPHP ^8.4CI passing

Since Mar 9Pushed 1mo agoCompare

[ Source](https://github.com/hexogen/timesync)[ Packagist](https://packagist.org/packages/hexogen/timesync)[ RSS](/packages/hexogen-timesync/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (7)Versions (8)Used By (0)

Timesync
========

[](#timesync)

[![Package Version](https://camo.githubusercontent.com/a9d3d6924f919d76763c88c26608287dd1016a4ddacff05b5d2c33224db42f36/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6865786f67656e2f74696d6573796e632e737667)](https://packagist.org/packages/hexogen/timesync)[![Tests](https://github.com/hexogen/timesync/workflows/tests/badge.svg)](https://github.com/hexogen/timesync/actions)[![Code Coverage](https://camo.githubusercontent.com/1456101ff6a3a45b50599d5712032091aff16e881172eaba91645f565da60ccc/68747470733a2f2f636f6465636f762e696f2f67682f6865786f67656e2f74696d6573796e632f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/hexogen/timesync)[![PHP Version](https://camo.githubusercontent.com/2aed50cc19486e0407775311c22f530383b2791ca08b8c9583ebb80cb5e364e7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e342532422d626c75652e737667)](https://www.php.net/releases/8.4/)[![License](https://camo.githubusercontent.com/8bb50fd2278f18fc326bf71f6e88ca8f884f72f179d3e555e20ed30157190d0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e2e737667)](LICENSE)

A simple and elegant time synchronization library for PHP that allows you to synchronize your application's clock with a remote time source based on IP geolocation.

Features
--------

[](#features)

- 🕐 **PSR-20 Clock Interface** - Fully compliant with the PSR-20 Clock standard
- 🌍 **IP Geolocation** - Fetch time data for an IPv4 address via ipgeolocation.io
- 🔍 **Server IP Detection** - Automatically detect the current server IP via `SyncService`
- ⚡ **Microsecond Precision** - Maintains microsecond-level time accuracy
- 🔌 **PSR-18 HTTP Client** - Works with any PSR-18 compatible HTTP client
- 🧪 **Fully Tested** - Covered by PHPUnit tests
- 🎯 **Modern PHP** - Requires PHP 8.4+

Installation
------------

[](#installation)

Install via Composer:

```
composer require hexogen/timesync
```

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

[](#requirements)

- PHP 8.4 or higher
- A PSR-18 compatible HTTP client (for example Guzzle or Symfony HttpClient)

Upgrade Guide for 0.3.0
-----------------------

[](#upgrade-guide-for-030)

Version `0.3.0` contains a breaking API change:

- `IPGeolocationClient`, `SyncService`, and `IpifyIPDetector` now expose dedicated exception classes as part of the public contract
- Catch `InvalidIpAddressException`, `GeolocationServiceException`, and `ServerIpDetectionException` for precise failure handling
- All library-specific exceptions now implement `TimesyncException`, so you can catch a single domain-level type when preferred
- `0.2.x` already introduced the `SyncService` split for automatic server IP detection; that API remains the current usage model

### Before (`0.2.x`)

[](#before-02x)

```
use Psr\Http\Client\ClientExceptionInterface;

try {
    $clock = $syncService->getCurrentTime();
} catch (\InvalidArgumentException $e) {
    // Invalid IPv4 address format
} catch (\RuntimeException $e) {
    // API error, malformed response, or detector failure
} catch (ClientExceptionInterface $e) {
    // HTTP client error
}
```

### After (`0.3.0`)

[](#after-030)

```
use Hexogen\Timesync\GeolocationServiceException;
use Hexogen\Timesync\InvalidIpAddressException;
use Hexogen\Timesync\ServerIpDetectionException;
use Psr\Http\Client\ClientExceptionInterface;

try {
    $clock = $syncService->getCurrentTime();
} catch (InvalidIpAddressException $e) {
    // Invalid IPv4 address format
} catch (GeolocationServiceException $e) {
    // ipgeolocation.io returned an error or malformed payload
} catch (ServerIpDetectionException $e) {
    // The current server IP could not be determined
} catch (ClientExceptionInterface $e) {
    // HTTP client transport error
}
```

You can also catch `Hexogen\Timesync\TimesyncException` to handle all library-specific failures with one catch block.

Quick Start
-----------

[](#quick-start)

```