alex-no/server-time-clock

PSR-20 clock implementation that returns the current server time based on its local timezone.

v1.0.7 2025-05-19 11:44 UTC

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.

MIT

• Oleksandr Nosov

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
        'WorldTimeApi' => 'your-api-key2',
    ],
    'enable_cache' => true,
    'cache_ttl' => 300, // seconds
    'useMock' => false, // Mosk is usually used for testing.
]);

$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
useMock	bool	Enable/Disable Mock for tests (default: false)

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', // Preferred time provider
    'credentials' => [
        'IpGeoLocation' => 'your-api-key',
        'WorldTimeApi' => 'your-api-key2',
    ],
    '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',  // Preferred time provider
        'credentials' => [
            'IpGeoLocation' => 'your-api-key',
            'WorldTimeApi' => 'your-api-key2',
        ],
        '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