README

A lightweight PHP package that resolves an IANA timezone identifier from address data, using the GeoNames API.

Requirements

• PHP 8.4+
• A free GeoNames account with the web services enabled

Installation

composer require myparcelcom/timezone-resolver

Usage

use MyParcelCom\TimezoneResolver\GeoNames;

$resolver = new GeoNames(username: 'your-geonames-username');

$timezone = $resolver->getTimezone(
    countryCode: 'NL',
    postalCode: '1043NT',
    city: 'Amsterdam',
);

// 'Europe/Amsterdam'

Method signature

public function getTimezone(
    string $countryCode,
    ?string $postalCode = null,
    ?string $city = null,
): ?string

• Tries to resolve by postalCode first.
• Falls back to city if the postal code yields no results.
• Returns null if no timezone can be determined.

Using the interface

Depend on TimezoneResolverInterface instead of the concrete class to keep your code decoupled:

use MyParcelCom\TimezoneResolver\TimezoneResolverInterface;

class MyService
{
    public function __construct(
        private readonly TimezoneResolverInterface $timezoneResolver,
    ) {}
}

Configuration

The GeoNames username is passed directly to the constructor. In a Laravel application, bind the interface in a service provider:

use MyParcelCom\TimezoneResolver\GeoNames;
use MyParcelCom\TimezoneResolver\TimezoneResolverInterface;

$this->app->bind(
    TimezoneResolverInterface::class,
    fn () => new GeoNames(config('services.geonames.username')),
);

// config/services.php
'geonames' => [
    'username' => env('GEONAMES_USERNAME'),
],

Testing

composer install
vendor/bin/phpunit

License

Proprietary — © MyParcel.com