Download the PHP package hexogen/timesync without Composer

Timesync

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

• 🕐 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

Install via Composer:

Requirements

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

Upgrade Guide for 0.3.0

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)

After (0.3.0)

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

Quick Start

Usage

Basic Clock Usage

The Clock class provides a synchronized time based on a reference timestamp:

Explicit IP Lookup with IPGeolocationClient

Use IPGeolocationClient when you already know which IPv4 address you want to resolve:

Automatic Server IP Detection with SyncService

Use SyncService when you want the library to detect the current server IP for you:

You can still override the detected IP explicitly:

Custom IP Detection

Implement your own IP detector:

API Reference

Clock

Implements Psr\Clock\ClockInterface

IPGeolocationClient

Implements SyncClientInterface

Throws InvalidIpAddressException, GeolocationServiceException, and ClientExceptionInterface.

SyncService

Implements SyncServiceInterface

Throws InvalidIpAddressException, GeolocationServiceException, ServerIpDetectionException, and ClientExceptionInterface.

IpifyIPDetector

Implements ServerIPDetectorInterface

Throws ServerIpDetectionException and ClientExceptionInterface.

Exception Types

• TimesyncException — marker interface implemented by all library-specific exceptions
• InvalidIpAddressException — invalid IPv4 input passed to the library
• GeolocationServiceException — geolocation API returned an error or malformed payload
• ServerIpDetectionException — public server IP lookup failed or returned an invalid payload

Configuration

Get an ipgeolocation.io API Key

1. Sign up at ipgeolocation.io
2. Get your API key from the dashboard
3. Pass it to IPGeolocationClient

Time Zones

The library automatically uses the timezone returned by the geolocation API. You can also manually specify a timezone when creating a Clock:

Testing

Run the test suite:

Run tests with coverage:

Check code style:

Fix code style:

Code Quality

This library follows:

• PER-CS (PHP Evolving Recommendations for Code Style)
• PSR-12 Extended Coding Style Guide
• Strict types declaration in all files
• Strong typing with explicit interfaces and return types

Architecture

How It Works

1. Optional IP Detection: SyncService fetches the current server IP when you do not provide one
2. Geolocation: IPGeolocationClient queries the ipgeolocation.io API with an IPv4 address
3. Time Extraction: The API returns the current time and timezone for that IP's location
4. Clock Creation: A Clock instance stores the time delta and timezone
5. Synchronized Time: The clock provides synchronized time adjusted for the delta

Error Handling

All library-specific exceptions implement Hexogen\Timesync\TimesyncException.

Performance

• Delta calculation: The clock calculates the time offset once per instance
• Lightweight: Minimal overhead, no background processes
• Composable: Cache Clock or SyncService results in your DI container if needed

Examples

Laravel Integration

Symfony Integration

Contributing

Contributions are welcome. Feel free to submit a Pull Request.

Development Setup

License

This library is licensed under the MIT License. See LICENSE for details.

Credits

• Developed by Hexogen
• Uses ipgeolocation.io for time synchronization
• Uses ipify.org for server IP detection

Changelog

0.3.0 (2026-03-11)

• Breaking: introduced dedicated domain exceptions as part of the public API: InvalidIpAddressException, GeolocationServiceException, and ServerIpDetectionException
• Breaking: added TimesyncException as a marker interface for all library-specific exceptions
• Updated interface contracts and README examples to document the new exception handling model
• Corrected the README PHP requirement to match composer.json (PHP 8.3+)

0.2.0 (2026-03-11)

• Breaking: moved optional server IP detection from IPGeolocationClient to SyncService
• Breaking: IPGeolocationClient::__construct() now accepts only apiKey and httpClient
• Breaking: IPGeolocationClient::getCurrentTime() now requires an explicit IPv4 string
• Updated documentation and examples to reflect the new API split

0.1.1 (2026-03-10)

• Added MIT LICENSE file
• Improved workflow with coverage reporting
• README fixes and consistency improvements

0.1.0 (2026-03-09)

• Initial release
• PSR-20 Clock implementation
• IP geolocation time synchronization
• Microsecond precision support
• Full test coverage

Support

• Issues: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions

Related Projects

• PSR-20: Clock
• PSR-18: HTTP Client
• Nyholm PSR-7
• Guzzle HTTP Client