README

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

Requirements

PHP 8.2+
A free GeoNames account with the web services enabled

To update dependencies on a system without PHP 8 use:

docker run --rm --mount type=bind,source="$(pwd)",target=/app composer:2 composer update

Installation

composer require myparcelcom/timezone-resolver

Usage

use MyParcelCom\TimezoneResolver\TimezoneResolver;

$resolver = new TimezoneResolver(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\TimezoneResolver;
use MyParcelCom\TimezoneResolver\TimezoneResolverInterface;

$this->app->singleton(
    TimezoneResolverInterface::class,
    fn () => new TimezoneResolver('my-geonames-username'),
);

Testing

docker run -v $(pwd):/app --rm -w /app php:8.4-cli vendor/bin/phpunit

myparcelcom / timezone-resolver

Maintainers

Package info

Statistics

Security