ted7021/geo-clock

PHP clock based on external IP and timezone providers

v1.0.0 2025-04-29 05:17 UTC

Requires

• php: ^8.2
• guzzlehttp/guzzle: ^7.5
• psr/clock: ^1.0

Requires (Dev)

• phpunit/phpunit: ^10

MIT

README

GeoClock is a lightweight PHP library that implements PSR-20 ClockInterface and returns the current time based on your server’s external IP address.

It supports multiple external providers with automatic fallback if the first one fails.

Installation

composer require ted7021/geo-clock

Features

• Returns DateTimeImmutable based on actual timezone from IP.
• Uses external providers like WorldTimeAPI, TimeAPI.io, ipgeolocation.io.
• Easily extendable: implement your own provider.
• PSR-20 compatible (ClockInterface).

Usage

use GeoClock\GeoClockFactory;

$clock = GeoClockFactory::create();

echo $clock->now()->format('Y-m-d H:i:s');

Want to specify IP?

$clock = GeoClockFactory::create('8.8.8.8');

Advanced usage with custom providers

use GeoClock\GeoClockFactory;
use GeoClock\Provider\WorldTimeApiProvider;

$clock = GeoClockFactory::createWithProviders([
    new WorldTimeApiProvider(),
]);

echo $clock->now()->format('Y-m-d H:i:s');

Providers

GeoClock includes the following providers:

Provider	Requires API key?
WorldTimeApiProvider	❌ No
TimeApiProvider	❌ No
IpGeolocationProvider	✅ Yes

Configuration: Timeout and Retries

Each provider supports configurable timeout and retries:

• Timeout: maximum number of seconds to wait for a response (default 5.0 seconds).
• Retries: number of retry attempts on network errors (default 3 retries).

Example: Custom timeout and retries

use GeoClock\Provider\WorldTimeApiProvider;

// Create a provider with 10 seconds timeout and 5 retries
$provider = new WorldTimeApiProvider(timeout: 10.0, maxRetries: 5);

Usage with API Key

Some providers require an API key, for example, ipgeolocation.io.

Example: Using IpGeolocationProvider

use GeoClock\GeoClockFactory;
use GeoClock\Provider\IpGeolocationProvider;

// Create provider with your API key
$provider = new IpGeolocationProvider('your-api-key-here');

// Create clock using custom provider
$clock = GeoClockFactory::createWithProviders([$provider]);

echo $clock->now()->format('Y-m-d H:i:s');

Testing

vendor/bin/phpunit

Requirements

• PHP 8.2+
• ext-curl
• Composer