jeroen/simple-geocoder

Simple and minimalistic Geocoder interface with some basic implementations

1.3.1 2020-08-19 15:49 UTC

Requires

• php: >=7.0
• data-values/geo: ~4.0|~3.0|~2.0
• jeroen/file-fetcher: ~6.0|~5.0|~4.0
• willdurand/geocoder: ~4.1

Requires (Dev)

• geocoder-php/google-maps-provider: ~4.1
• guzzlehttp/psr7: ~1.4
• mediawiki/mediawiki-codesniffer: ~31.0
• ockcyp/covers-validator: ~1.2
• php-http/mock-client: ~1.0
• phpstan/phpstan: ^0.12.29
• phpunit/phpunit: ~6.2
• slevomat/coding-standard: ~6.0
• squizlabs/php_codesniffer: ~3.0

GPL-2.0-or-later

• Jeroen De Dauw

README

PHP 7.0+ library providing a simple and minimalistic Geocoder interface with some basic implementations.

interface Geocoder {
	/**
	 * Returns null when no result is found or when an error occurs.
	 * @return LatLongValue|null
	 */
	public function geocode( string $address );
}

Geocoders using real geocoding services over HTTP:

• GeoNamesGeocoder
• GoogleGeocoder
• NomatimGeocoder

Adapters:

• GeocoderPhpAdapter - adapts to the popular PHP Geocoder library

Trivial implementations (great for testing):

• InMemoryGeocoder
• NullGeocoder
• StubGeocoder

Decorators:

• CoordinateFriendlyGeocoder

This library is based on code extracted from the Maps extension for MediaWiki.

Installation

To use the Simple Geocoder library in your project, simply add a dependency on jeroen/simple-geocoder to your project's composer.json file. Here is a minimal example of a composer.json file that just defines a dependency on Simple Geocoder 1.x:

{
    "require": {
        "jeroen/simple-geocoder": "~1.0"
    }
}

Development

For development you need to have Docker and Docker-compose installed. Local PHP and Composer are not needed.

sudo apt-get install docker docker-compose

Running Composer

To pull in the project dependencies via Composer, run:

make composer install

You can run other Composer commands via make run, but at present this does not support argument flags. If you need to execute such a command, you can do so in this format:

docker run --rm --interactive --tty --volume $PWD:/app -w /app\
 --volume ~/.composer:/composer --user $(id -u):$(id -g) composer composer install -vvv

Running the CI checks

To run all CI checks, which includes PHPUnit tests, PHPCS style checks and coverage tag validation, run:

make

Running the tests

To run just the PHPUnit tests run

make test

To run only a subset of PHPUnit tests or otherwise pass flags to PHPUnit, run

docker-compose run --rm app ./vendor/bin/phpunit --filter SomeClassNameOrFilter

Release notes

1.3.1 (2020-08-19)

• Updated attribution

1.3.0 (2019-01-18)

• Installation with FileFetcher 6.x is now allowed

1.2.0 (2018-07-10)

• Added GeocoderPhpAdapter that allows using the popular PHP Geocoder library
• Installation with DataValues Geo 4.x is now allowed

1.1.0 (2018-03-20)

• Installation with DataValues Geo 3.x is now allowed

1.0.0 (2017-11-02)

Initial release as standalone component with

• FileFetcher based geocoders: GeoNamesGeocoder, GoogleGeocoder, NomatimGeocoder
• Trivial implementations: InMemoryGeocoder, NullGeocoder, StubGeocoder
• Decorators: CoordinateFriendlyGeocoder