virtual-web-studio/geo-clock

PSR-20 Clock implementation that returns current time based on server geolocation

v1.0.0 2025-05-21 18:24 UTC

Requires

• php: ^8.4
• guzzlehttp/guzzle: ^7.0
• psr/clock: ^1.0

Requires (Dev)

• phpunit/phpunit: ^10

Provides

• psr/clock-implementation: 1.0

MIT

README

GeoClock is a lightweight PHP library implementing the PSR-20 ClockInterface.

It provides the current time in the server’s geographical time zone using its public IP address, by querying the ipgeolocation.io API.

Features

• PSR-20 compatible ClockInterface
• Returns accurate time based on geolocation
• Automatically detects the public IP of the server
• Allows manually overriding the IP address
• Falls back to UTC on error
• Minimal dependencies

⚠️ API Key Required

This library uses the ipgeolocation.io API to resolve timezone and current time.
You must provide a valid API key when instantiating the clock.

To get an API key:

1. Register at https://ipgeolocation.io
2. Copy your key from the dashboard
3. Use it like this:

use GeoClock\GeoClock;

$clock = new GeoClock('your_api_key');
echo $clock->now()->format('c'); // ISO 8601 output

You can also specify a known IP manually:

$clock = new GeoClock('your_api_key', '8.8.8.8');

Installation

Recommended (after stable tag is released):

composer require virtual-web-studio/geo-clock

Development version (if using dev-main):

composer require virtual-web-studio/geo-clock:dev-main --with-all-dependencies

Testing

To run tests:

make test

License

MIT — see LICENSE