eegusakov/geo-search

A PHP library for finding location information, including geographic points, name, region, country, and time zone information.

v1.0.2 2023-08-06 11:25 UTC

Requires

• php: ^8.0
• laminas/laminas-diactoros: ^3.0
• psr/http-client: ^1.0
• psr/log: ^3.0
• psr/simple-cache: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.21
• phpunit/phpunit: ^9.6

MIT

• Gusakov Egor

README

Language: ENG, RUS

Geo Search - PHP library that will allow you to determine the geographical location of an object based on the transmitted data.

Third-party service APIs are used for the search, so the input data for the search may differ depending on the service. The entire list of available services is listed below.

Compatible with PSR

Any client compatible with PSR-18 is suitable for providing http requests. The examples will use the library Guzzle

Any client compatible with PSP-16 is suitable for working with the cache. The examples will use libraries SymfonyCache

Any client compatible with PSR-3 is suitable for error logging (Monolog and so on.). The examples will use the ConsoleLogger included in the current library.

Getting started

Installing Geo Search

The recommended way to install Geo Search is via Composer.

composer require eegusakov/geo-search

Services

Attention, to work with each service, you need to get an API access token. To get it, follow the link attached to a specific service

1. WeatherApi

Link to the service: https://www.weatherapi.com/my/

Link to documentation: https://www.weatherapi.com/api-explorer.aspx#tz

Performs a search on the following data:

1. US postal code,
2. UK postal code,
3. postal code of Canada,
4. IP address,
5. latitude/longitude (decimal degree),
6. name of the city;

Example:

use GuzzleHttp\Client;
use Eegusakov\GeoSearch\Engines\WeatherApi\WeatherApiSearchEngine;
use Eegusakov\GeoSearch\Engines\WeatherApi\ResponseFromGeoDtoMapper;

$weatherApiSearchEngine = new WeatherApiSearchEngine(
    '<API_TOKEN>',
    new Client(),
    new ResponseFromGeoDtoMapper()
);

$geoByCity = $weatherApiSearchEngine->search('Moscow');

$geoByCoordinates = $weatherApiSearchEngine->search('53,-0.12');

$geoByZipCode = $weatherApiSearchEngine->search('90201');

2. OpenMeteo

Link to the service: https://open-meteo.com/

Link to documentation: https://open-meteo.com/en/docs/geocoding-api

Performs a search on the following data:

1. name of the city,
2. postal code;

Example:

use GuzzleHttp\Client;
use Eegusakov\GeoSearch\Engines\OpenMeteo\OpenMeteoSearchEngine;
use Eegusakov\GeoSearch\Engines\OpenMeteo\ResponseFromGeoDtoMapper;

$openMeteoSearchEngine = new OpenMeteoSearchEngine(
  new Client(),
  new ResponseFromGeoDtoMapper()
);

$geoByCity = $openMeteoSearchEngine->search('Moscow');

$geoByZipCode = $openMeteoSearchEngine->search('10001');

Additional features

1. Using multiple services at once

This library allows you to use several services at once and get the result of the first service that returned a non-empty response.

use Eegusakov\GeoSearch\Engines\ChainSearchEngine;
use Eegusakov\GeoSearch\Engines\OpenMeteo\OpenMeteoSearchEngine;
use Eegusakov\GeoSearch\Engines\OpenMeteo\ResponseFromGeoDtoMapper as OpenMeteoResponseFromGeoDtoMapper;
use Eegusakov\GeoSearch\Engines\WeatherApi\ResponseFromGeoDtoMapper as WeatherApiResponseFromGeoDtoMapper;
use Eegusakov\GeoSearch\Engines\WeatherApi\WeatherApiSearchEngine;
use GuzzleHttp\Client;

$chainSearchEngine = new ChainSearchEngine(
    new WeatherApiSearchEngine(
        '<API_TOKEN_1>',
        new Client(),
        new WeatherApiResponseFromGeoDtoMapper()
    ),
    new WeatherApiSearchEngine(
        '<API_TOKEN_2>',
        new Client(),
        new WeatherApiResponseFromGeoDtoMapper()
    ),
    new OpenMeteoSearchEngine(
        new Client(),
        new OpenMeteoResponseFromGeoDtoMapper()
    )
);

$geo = $chainSearchEngine->search('Moscow');

2. The ability to ignore errors

The functionality is relevant when there is a need to ignore errors and move on to the next request.

ErrorHandler processes all errors and writes them to the log, the library includes a basic logger that simply outputs information to the console (ConsoleLogger).

Any client compatible with PSR-3 is suitable for logging.

use GuzzleHttp\Client;
use Eegusakov\GeoSearch\Engines\MuteSearchEngine;
use Eegusakov\GeoSearch\Handlers\ErrorHandler;
use Eegusakov\GeoSearch\Loggers\ConsoleLogger;
use Eegusakov\GeoSearch\Engines\WeatherApi\WeatherApiSearchEngine;
use Eegusakov\GeoSearch\Engines\WeatherApi\ResponseFromGeoDtoMapper;

$muteSearchEngine = new MuteSearchEngine(
    new WeatherApiSearchEngine(
        '<API_TOKEN>',
        new Client(),
        new ResponseFromGeoDtoMapper()
    ),
    new ErrorHandler(
        new ConsoleLogger()
    )
);

$geo = $muteSearchEngine->search('Moscow');

3. Ability to cache the response result

Any client compatible with PSP-16 is suitable for working with the cache. The example will use SymfonyCache.

use Eegusakov\GeoSearch\Engines\WeatherApi\ResponseFromGeoDtoMapper;
use Eegusakov\GeoSearch\Engines\WeatherApi\WeatherApiSearchEngine;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Eegusakov\GeoSearch\Engines\CacheSearchEngine;
use Symfony\Component\Cache\Psr16Cache;
use GuzzleHttp\Client;

$cacheSearchEngine = new CacheSearchEngine(
    new WeatherApiSearchEngine(
        '<API_TOKEN>',
        new Client(),
        new ResponseFromGeoDtoMapper()
    ),
    new Psr16Cache(
        new FilesystemAdapter()
    ),
    60
);

$geo = $cacheSearchEngine->search('Moscow');

4. The ability to combine the 1st, 2nd and 3rd item

use GuzzleHttp\Client;
use Symfony\Component\Cache\Psr16Cache;
use Eegusakov\GeoSearch\Handlers\ErrorHandler;
use Eegusakov\GeoSearch\Loggers\ConsoleLogger;
use Eegusakov\GeoSearch\Engines\MuteSearchEngine;
use Eegusakov\GeoSearch\Engines\CacheSearchEngine;
use Eegusakov\GeoSearch\Engines\ChainSearchEngine;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Eegusakov\GeoSearch\Engines\OpenMeteo\OpenMeteoSearchEngine;
use Eegusakov\GeoSearch\Engines\WeatherApi\WeatherApiSearchEngine;
use Eegusakov\GeoSearch\Engines\OpenMeteo\ResponseFromGeoDtoMapper as OpenMeteoResponseFromGeoDtoMapper;
use Eegusakov\GeoSearch\Engines\WeatherApi\ResponseFromGeoDtoMapper as WeatherApiResponseFromGeoDtoMapper;

$cacheChainMuteSearchEngine = new CacheSearchEngine(
    new ChainSearchEngine(
        new MuteSearchEngine(
            new WeatherApiSearchEngine(
                'API_TOKEN_1',
                new Client(),
                new WeatherApiResponseFromGeoDtoMapper()
            ),
            new ErrorHandler(
                new ConsoleLogger()
            )
        ),
        new MuteSearchEngine(
            new OpenMeteoSearchEngine(
                new Client(),
                new OpenMeteoResponseFromGeoDtoMapper()
            ),
            new ErrorHandler(
                new ConsoleLogger()
            )
        )
    ),
    new Psr16Cache(
        new FilesystemAdapter()
    ),
    60
);

$geo = $cacheChainMuteSearchEngine->search('Moscow');

Cooperation

Please read CONTRIBUTING for more information about our code of conduct and the process of sending us merge requests.

License

This project is licensed under the MIT license - see the LICENSE file for details