alex-no / server-time-clock
PSR-20 clock implementation that returns the current server time based on its local timezone.
Requires
- php: ^8.1
- psr/clock: ^1.0
Requires (Dev)
- phpunit/phpunit: ^10.0
Suggests
- laravel/framework: Required if you use the Laravel service provider.
- yiisoft/yii2: Required if you use the ServerClockComponent in Yii2.
README
PSR-20 clock implementation that returns the current server time based on its local timezone or online providers.
Installation
Install via Composer:
composer require alex-no/server-time-clock
Usage
use ServerTimeClock\ServerClock; $clock = new ServerClock([ 'client' => 'WorldTimeApi', // or 'IpGeoLocation', 'TimeApiIo' 'credentials' => [ 'IpGeoLocation' => 'your-api-key', // optional, depending on the provider ], 'enable_cache' => true, 'cache_ttl' => 300, // seconds ]); $now = $clock->now(); // instance of DateTimeImmutable echo $now->format(DATE_ATOM);
Configuration Options
Key | Type | Description |
---|---|---|
client |
string | Preferred time provider (WorldTimeApi , IpGeoLocation , etc.) |
credentials |
array | API keys for time providers (optional) |
enable_cache |
bool | Enable APCu-based caching (default: false ) |
cache_ttl |
int | Cache duration in seconds |
Providers
🌐 WorldTimeApi – no key required
🌐 IpGeoLocation – requires free API key from ipgeolocation.io
🌐 TimeApiIo – no key required
Laravel Integration
You can integrate this package into Laravel with minimal setup.
Configuration (Optional)
To publish the config file:
php artisan vendor:publish --tag=server-clock-config
This will create config/server-clock.php:
return [ 'client' => 'WorldTimeApi', 'credentials' => [ // 'IpGeoLocation' => '', ], 'enable_cache' => true, 'cache_ttl' => 300, ];
Usage in Laravel
use ServerTimeClock\ServerClock; $clock = app(ServerClock::class); echo $clock->now()->format('c');
Yii2 Integration
Configuration
You may use the ServerClock class directly or configure it as a Yii2 component:
'components' => [ 'serverClock' => [ 'class' => \ServerTimeClock\Yii\ServerClockComponent::class, 'client' => 'WorldTimeApi', 'credentials' => [ // 'IpGeoLocation' => '', ], 'enableCache' => true, 'cacheTtl' => 300, ], ],
Usage
Then use it:
Yii::$app->serverClock->now();
Note: Yii2 support is optional and requires yiisoft/yii2 to be installed in your project.
Optional Dependencies
This package is framework-agnostic. Laravel and Yii2 integrations are provided for convenience.
Framework | Package | Required? |
---|---|---|
Laravel | laravel/framework |
Optional |
Yii2 | yiisoft/yii2 |
Optional |
APCu Cache Requirements
If you enable caching (enable_cache => true), make sure the APCu extension is installed and enabled in your PHP configuration. This typically means:
- The apcu extension must be installed (e.g., via pecl install apcu or appropriate package manager).
- For CLI usage (e.g., when running tests), ensure apc.enable_cli=1 is set in your php.ini.
You can verify if APCu is available by running:
php -i | grep apcu
Testing
Run PHPUnit tests:
vendor/bin/phpunit
License
MIT License
Made with ❤️ by Oleksandr Nosov