Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/geocoder-php/geocoder
The most featured Geocoder library written in PHP.
https://github.com/geocoder-php/geocoder
geocoder
Last synced: 1 day ago
JSON representation
The most featured Geocoder library written in PHP.
- Host: GitHub
- URL: https://github.com/geocoder-php/geocoder
- Owner: geocoder-php
- License: mit
- Created: 2011-11-07T21:56:41.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2024-11-14T11:27:15.000Z (6 days ago)
- Last Synced: 2024-11-14T12:28:00.126Z (6 days ago)
- Topics: geocoder
- Language: PHP
- Homepage: https://geocoder-php.org
- Size: 39.3 MB
- Stars: 3,949
- Watchers: 128
- Forks: 519
- Open Issues: 56
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Geocoder
[](https://github.com/geocoder-php/Geocoder/actions/workflows/php.yml)
[](LICENSE)
> **Important:** You are browsing the documentation of Geocoder **4.x**.
>
> Documentation for version **3.x** is available here: [Geocoder 3.x
> documentation](https://github.com/geocoder-php/Geocoder/blob/3.x/README.md).
>
> Documentation for version **2.x** is available here: [Geocoder 2.x
> documentation](https://github.com/geocoder-php/Geocoder/blob/2.x/README.md).
---
**Geocoder** is a PHP library which helps you build geo-aware applications by
providing a powerful abstraction layer for geocoding manipulations.
* [Installation](#installation)
* [Cookbook](#cookbook)
* [Usage](#usage)
* [Providers](#providers)
* [Special Geocoders and Providers](#special-geocoders-and-providers)
* [Dumpers](#dumpers)
* [Formatters](#formatters)
* [Versioning](#versioning)
## Installation
To install a Geocoder there are two things you need to know:
1) What [Geocoder provider](https://packagist.org/providers/geocoder-php/provider-implementation) you want to use
2) What [HTTP client/adapter](https://packagist.org/providers/psr/http-client-implementation) you want to use.
### Geocoder providers
Since 4.0 we do not include providers by default. You need to select a *geocoder provider*. You will see a list of
providers [at Packagist](https://packagist.org/providers/geocoder-php/provider-implementation)
### HTTP Clients
In order to talk to geocoding APIs, you need HTTP adapters. While it was part of
the library in Geocoder before, Geocoder 4.x and upper now relies on [PSR-18](https://www.php-fig.org/psr/psr-18/)
which defines how HTTP message should be sent and received. You can use any library to send HTTP messages
that implements [psr/http-client-implementation](https://packagist.org/providers/psr/http-client-implementation).
Read more about PSR-18 in [this blog](https://www.php-fig.org/blog/2018/11/psr-18-the-php-standard-for-http-clients/).
### Summary (Just give me the command)
To install Google Maps geocoder with Guzzle 7 you may run the following command:
```cmd
composer require geocoder-php/google-maps-provider guzzlehttp/guzzle
```
Or using the curl client (you'll need to provide a PSR7 implementation such as `nyholm/psr7` if not using Guzzle)
```cmd
composer require geocoder-php/google-maps-provider php-http/curl-client nyholm/psr7
```
### Framework integration
If you are using a framework then you may be interested in our excellent framework integrations.
Framework | Package | Stats
:------------- |:--------- |:-------
[Laravel](https://github.com/geocoder-php/GeocoderLaravel) | `geocoder-php/GeocoderLaravel` | [](https://packagist.org/packages/toin0u/geocoder-laravel) [](https://packagist.org/packages/toin0u/geocoder-laravel)
[Symfony](https://github.com/geocoder-php/BazingaGeocoderBundle) | `geocoder-php/BazingaGeocoderBundle` | [](https://packagist.org/packages/willdurand/geocoder-bundle) [](https://packagist.org/packages/willdurand/geocoder-bundle)
## Cookbook
We have a small cookbook where you can find examples on common use cases:
* [Caching responses](/docs/cookbook/cache.md)
* [Configuring the HTTP client](/docs/cookbook/http-client.md)
* [Rate limiting API requests](/docs/cookbook/rate-limiting.md)
## Usage
In the code snippet below we use GoogleMaps and Guzzle 7.
```php
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;
$httpClient = new \GuzzleHttp\Client();
$provider = new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient, null, 'your-api-key');
$geocoder = new \Geocoder\StatefulGeocoder($provider, 'en');
$result = $geocoder->geocodeQuery(GeocodeQuery::create('Buckingham Palace, London'));
$result = $geocoder->reverseQuery(ReverseQuery::fromCoordinates(...));
```
The `Provider` interface has three methods:
* `geocodeQuery(GeocodeQuery $query):AddressCollection`
* `reverseQuery(ReverseQuery $query):AddressCollection`
* `getName():string`
The `Geocoder` interface extends the `Provider` interface and exposes two additional methods. They will
make migration from 3.x smoother.
* `geocode($streetOrIpAddress)`
* `reverse($latitude, $longitude)`
## Providers
Providers perform the geocoding black magic for you (talking to the APIs, fetching results, dealing with errors, etc.)
and are highly configurable.
### Special providers
Provider | Package | Features | Stats
:------------- |:------- |:-------- |:-------
[Cache](https://github.com/geocoder-php/cache-provider) | `geocoder-php/cache-provider` | Wraps a provider and cached the results | [](https://packagist.org/packages/geocoder-php/cache-provider)
[](https://packagist.org/packages/geocoder-php/cache-provider)
[Chain](https://github.com/geocoder-php/chain-provider) | `geocoder-php/chain-provider` | Iterates over multiple providers | [](https://packagist.org/packages/geocoder-php/chain-provider)
[](https://packagist.org/packages/geocoder-php/chain-provider)
### Address
#### World
Provider | Package | Features | Stats
:------------- |:------- |:-------- |:-------
[Algolia Places](https://github.com/geocoder-php/algolia-places-provider) | `geocoder-php/algolia-places-provider` | address
[Website](https://community.algolia.com/places/) | [](https://packagist.org/packages/geocoder-php/algolia-places-provider)
[](https://packagist.org/packages/geocoder-php/algolia-places-provider)
[ArcGIS Online](https://github.com/geocoder-php/arcgis-online-provider) | `geocoder-php/arcgis-online-provider` | address, reverse
[Website](https://developers.arcgis.com/en/features/geocoding/) | [](https://packagist.org/packages/geocoder-php/arcgis-online-provider)
[](https://packagist.org/packages/geocoder-php/arcgis-online-provider)
[Azure Maps](https://github.com/geocoder-php/azure-maps-provider) | `geocoder-php/azure-maps-provider` | address, reverse
[Website](https://docs.microsoft.com/en-us/azure/azure-maps/tutorial-search-location) | [](https://packagist.org/packages/geocoder-php/azure-maps-provider)
[](https://packagist.org/packages/geocoder-php/azure-maps-provider)
[Bing Maps](https://github.com/geocoder-php/bing-maps-provider) | `geocoder-php/bing-maps-provider` | address, reverse
[Website](http://msdn.microsoft.com/en-us/library/ff701713.aspx) | [](https://packagist.org/packages/geocoder-php/bing-maps-provider)
[](https://packagist.org/packages/geocoder-php/bing-maps-provider)
[Geocode Earth](https://github.com/geocoder-php/geocode-earth-provider) | `geocoder-php/geocode-earth-provider` | address, reverse
[Website](https://geocode.earth/) | [](https://packagist.org/packages/geocoder-php/geocode-earth-provider)
[](https://packagist.org/packages/geocoder-php/geocode-earth-provider)
[Geonames](https://github.com/geocoder-php/geonames-provider) | `geocoder-php/geonames-provider` | address, reverse
[Website](http://www.geonames.org/commercial-webservices.html) | [](https://packagist.org/packages/geocoder-php/geonames-provider)
[](https://packagist.org/packages/geocoder-php/geonames-provider)
[Google Maps](https://github.com/geocoder-php/google-maps-provider)
Google Maps for business | `geocoder-php/google-maps-provider` | address, reverse
[Website](https://developers.google.com/maps/documentation/geocoding/) | [](https://packagist.org/packages/geocoder-php/google-maps-provider)
[](https://packagist.org/packages/geocoder-php/google-maps-provider)
[Google Maps Places](https://github.com/geocoder-php/google-maps-places-provider) | `geocoder-php/google-maps-places-provider` | address, reverse
[Website](https://developers.google.com/places/web-service/) | [](https://packagist.org/packages/geocoder-php/google-maps-places-provider)
[](https://packagist.org/packages/geocoder-php/google-maps-places-provider)
[GraphHopper](https://github.com/geocoder-php/graphhopper-provider) | `geocoder-php/graphhopper-provider` | address, reverse
[Website](https://docs.graphhopper.com/#tag/Geocoding-API) | [](https://packagist.org/packages/geocoder-php/graphhopper-provider)
[](https://packagist.org/packages/geocoder-php/graphhopper-provider)
[Here](https://github.com/geocoder-php/here-provider) | `geocoder-php/here-provider` | address, reverse
[Website](https://developer.here.com/documentation/geocoder/topics/quick-start-geocode.html) | [](https://packagist.org/packages/geocoder-php/here-provider)
[](https://packagist.org/packages/geocoder-php/here-provider)
[LocationIQ](https://github.com/geocoder-php/locationiq-provider) | `geocoder-php/locationiq-provider` | address, reverse
[Website](https://locationiq.org/) | [](https://packagist.org/packages/geocoder-php/locationiq-provider)
[](https://packagist.org/packages/geocoder-php/locationiq-provider)
[Mapbox](https://github.com/geocoder-php/mapbox-provider) | `geocoder-php/mapbox-provider` | address, reverse
[Website](https://www.mapbox.com/geocoding/) | [](https://packagist.org/packages/geocoder-php/mapbox-provider)
[](https://packagist.org/packages/geocoder-php/mapbox-provider)
[MapQuest](https://github.com/geocoder-php/mapquest-provider) | `geocoder-php/mapquest-provider` | address, reverse
[Website](http://developer.mapquest.com/web/products/dev-services/geocoding-ws) | [](https://packagist.org/packages/geocoder-php/mapquest-provider)
[](https://packagist.org/packages/geocoder-php/mapquest-provider)
[MapTiler](https://github.com/geocoder-php/maptiler-provider) | `geocoder-php/maptiler-provider` | address, reverse
[Website](https://www.maptiler.com/cloud/geocoding/) | [](https://packagist.org/packages/geocoder-php/maptiler-provider)
[](https://packagist.org/packages/geocoder-php/maptiler-provider)
[Nominatim](https://github.com/geocoder-php/nominatim-provider)
(OpenStreetMap) | `geocoder-php/nominatim-provider` | address, reverse
[Website](http://wiki.openstreetmap.org/wiki/Nominatim) | [](https://packagist.org/packages/geocoder-php/nominatim-provider)
[](https://packagist.org/packages/geocoder-php/nominatim-provider)
[OpenCage](https://github.com/geocoder-php/open-cage-provider) | `geocoder-php/open-cage-provider` | address, reverse
[Website](https://opencagedata.com/) | [](https://packagist.org/packages/geocoder-php/open-cage-provider)
[](https://packagist.org/packages/geocoder-php/open-cage-provider)
[OpenRouteService](https://github.com/geocoder-php/openrouteservice-provider) | `geocoder-php/openrouteservice-provider` | address, reverse
[Website](https://openrouteservice.org/) | [](https://packagist.org/packages/geocoder-php/openrouteservice-provider)
[](https://packagist.org/packages/geocoder-php/openrouteservice-provider)
[Pelias](https://github.com/geocoder-php/pelias-provider) | `geocoder-php/pelias-provider` | address, reverse
[Website](https://pelias.io/) | [](https://packagist.org/packages/geocoder-php/pelias-provider)
[](https://packagist.org/packages/geocoder-php/pelias-provider)
[Photon](https://github.com/geocoder-php/photon-provider) | `geocoder-php/photon-provider` | address, reverse
[Website](https://photon.komoot.de/) | [](https://packagist.org/packages/geocoder-php/photon-provider)
[](https://packagist.org/packages/geocoder-php/photon-provider)
[PickPoint](https://github.com/geocoder-php/pickpoint-provider) | `geocoder-php/pickpoint-provider` | address, reverse
[Website](https://pickpoint.io/) | [](https://packagist.org/packages/geocoder-php/pickpoint-provider)
[](https://packagist.org/packages/geocoder-php/pickpoint-provider)
[TomTom](https://github.com/geocoder-php/tomtom-provider) | `geocoder-php/tomtom-provider` | address, reverse
[Website](https://geocoder.tomtom.com/app/view/index) | [](https://packagist.org/packages/geocoder-php/tomtom-provider)
[](https://packagist.org/packages/geocoder-php/tomtom-provider)
[Yandex](https://github.com/geocoder-php/yandex-provider) | `geocoder-php/yandex-provider` | address, reverse
[Website](http://api.yandex.com/maps/) | [](https://packagist.org/packages/geocoder-php/yandex-provider)
[](https://packagist.org/packages/geocoder-php/yandex-provider)
#### Local
Region | Provider | Package | Features | Stats
:------ |:------------- |:------- |:-------- |:-------
:belgium: | [bpost](https://github.com/geo6/geocoder-php-bpost-provider) (third-party package*) | `geo6/geocoder-php-bpost-provider` | address
[Website](https://www.bpost.be/site/en/webservice-address) | [](https://packagist.org/packages/geo6/geocoder-php-bpost-provider)
[](https://packagist.org/packages/geo6/geocoder-php-bpost-provider)
:belgium: | [GeoPunt](https://github.com/geo6/geocoder-php-geopunt-provider) (third-party package*) | `geo6/geocoder-php-geopunt-provider` | address, reverse
[Website](http://loc.geopunt.be/) | [](https://packagist.org/packages/geo6/geocoder-php-geopunt-provider)
[](https://packagist.org/packages/geo6/geocoder-php-geopunt-provider)
:belgium: | [Service Public de Wallonie](https://github.com/geo6/geocoder-php-spw-provider) (third-party package*) | `geo6/geocoder-php-spw-provider` | address, reverse
[Website](http://geoservices.wallonie.be/geolocalisation/doc/ws/index.xhtml) | [](https://packagist.org/packages/geo6/geocoder-php-spw-provider)
[](https://packagist.org/packages/geo6/geocoder-php-spw-provider)
:belgium: | [UrbIS](https://github.com/geo6/geocoder-php-urbis-provider) (third-party package*) | `geo6/geocoder-php-urbis-provider` | address, reverse
[Website](http://geoservices.irisnet.be/localization/) | [](https://packagist.org/packages/geo6/geocoder-php-urbis-provider)
[](https://packagist.org/packages/geo6/geocoder-php-urbis-provider)
:fr: | [Addok](https://github.com/geo6/geocoder-php-addok-provider) (third-party package*) | `geo6/geocoder-php-addok-provider` | address, reverse
[Website](https://adresse.data.gouv.fr/) | [](https://packagist.org/packages/geo6/geocoder-php-addok-provider)
[](https://packagist.org/packages/geo6/geocoder-php-addok-provider)
:luxembourg: | [Geoportail.lu](https://github.com/frantzmiccoli/geocoder-php-geoportail-lu) (third-party package*) | `frantzmicccoli/geocoder-php-geoportail-lu` | address, reverse
[Website](https://geoportail.lu/en/) | [](https://poser.pugx.org/frantzmicccoli/geocoder-php-geoportail-lu)
[](https://packagist.org/packages/frantzmicccoli/geocoder-php-geoportail-lu)
:netherlands: | [Nationaal Georegister](https://github.com/swisnl/geocoder-php-nationaal-georegister-provider) (third-party package*) | `swisnl/geocoder-php-nationaal-georegister-provider` | address, reverse
[Website](https://geodata.nationaalgeoregister.nl/) | [](https://packagist.org/packages/swisnl/geocoder-php-nationaal-georegister-provider)
[](https://packagist.org/packages/swisnl/geocoder-php-nationaal-georegister-provider)
:ru: | [Sputnik](https://github.com/demollc/sputnik-provider) (third-party package*) | `demollc/sputnik-provider` | address, reverse
[Website](http://api.sputnik.ru/maps/) | [](https://packagist.org/packages/demollc/sputnik-provider)
[](https://packagist.org/packages/demollc/sputnik-provider)
\* *Third-party package: Those providers are not official, i.e. not from the Geocoder core team.*
### IP
Provider | Package | Features | Stats
:------------- |:------- |:-------- |:-------
[FreeGeoIp](https://github.com/geocoder-php/free-geoip-provider) | `geocoder-php/free-geoip-provider` | IPv4, IPv6
[Website](https://freegeoip.app/) | [](https://packagist.org/packages/geocoder-php/free-geoip-provider)
[](https://packagist.org/packages/geocoder-php/free-geoip-provider)
[GeoIP2](https://github.com/geocoder-php/geoip2-provider) | `geocoder-php/geoip2-provider` | IPv4
[Website](https://www.maxmind.com/en/geoip2-databases) | [](https://packagist.org/packages/geocoder-php/geoip2-provider)
[](https://packagist.org/packages/geocoder-php/geoip2-provider)
[GeoPlugin](https://github.com/geocoder-php/geo-plugin-provider) | `geocoder-php/geo-plugin-provider` | IPv4, IPv6
[Website](http://www.geoplugin.com/) | [](https://packagist.org/packages/geocoder-php/geo-plugin-provider)
[](https://packagist.org/packages/geocoder-php/geo-plugin-provider)
[HostIp](https://github.com/geocoder-php/host-ip-provider) | `geocoder-php/host-ip-provider` | IPv4
[Website](http://www.hostip.info/use.html) | [](https://packagist.org/packages/geocoder-php/host-ip-provider)
[](https://packagist.org/packages/geocoder-php/host-ip-provider)
[IP2Location](https://github.com/geocoder-php/ip2location-provider) | `geocoder-php/ip2location-provider` | IPv4, IPv6
[Website](https://www.ip2location.com/) | [](https://packagist.org/packages/geocoder-php/ip2location-provider)
[](https://packagist.org/packages/geocoder-php/ip2location-provider)
[IP2Location Binary](https://github.com/geocoder-php/ip2location-binary-provider) | `geocoder-php/ip2location-binary-provider` | IPv4, IPv6
[Website](https://www.ip2location.com/) | [](https://packagist.org/packages/geocoder-php/ip2location-binary-provider)
[](https://packagist.org/packages/geocoder-php/ip2location-binary-provider)
[IpInfo](https://github.com/geocoder-php/ip-info-provider) | `geocoder-php/ip-info-provider` | IPv4, IPv6
[Website](https://ipinfo.io/) | [](https://packagist.org/packages/geocoder-php/ip-info-provider)
[](https://packagist.org/packages/geocoder-php/ip-info-provider)
[IpInfoDB](https://github.com/geocoder-php/ip-info-db-provider) | `geocoder-php/ip-info-db-provider` | IPv4
[Website](http://ipinfodb.com/) | [](https://packagist.org/packages/geocoder-php/ip-info-db-provider)
[](https://packagist.org/packages/geocoder-php/ip-info-db-provider)
[ipstack](https://github.com/geocoder-php/ipstack-provider) | `geocoder-php/ipstack-provider` | IPv4, IPv6
[Website](https://ipstack.com/) | [](https://packagist.org/packages/geocoder-php/ipstack-provider)
[](https://packagist.org/packages/geocoder-php/ipstack-provider)
[MaxMind](https://github.com/geocoder-php/maxmind-provider) | `geocoder-php/maxmind-provider` | IPv4, IPv6
[Website](https://www.maxmind.com/) | [](https://packagist.org/packages/geocoder-php/maxmind-provider)
[](https://packagist.org/packages/geocoder-php/maxmind-provider)
[MaxMind Binary](https://github.com/geocoder-php/maxmind-binary-provider) | `geocoder-php/maxmind-binary-provider` | IPv4, IPv6
[Website](https://www.maxmind.com/) | [](https://packagist.org/packages/geocoder-php/maxmind-binary-provider)
[](https://packagist.org/packages/geocoder-php/maxmind-binary-provider)
### Other packages
There are two "*abstract*" or "*base*" packages that most providers depend on.
Name | Package | Features | Stats
:--------- |:------- |:-------- |:-------
[PHP common](https://github.com/geocoder-php/php-common) | `willdurand/geocoder` | Models, interfaces, exceptions etc | [](https://packagist.org/packages/willdurand/geocoder)
[](https://packagist.org/packages/willdurand/geocoder)
[HTTP common](https://github.com/geocoder-php/php-common-http) | `geocoder-php/common-http` | `AbstractHttpProvider`, HTTPlug | [](https://packagist.org/packages/geocoder-php/common-http)
[](https://packagist.org/packages/geocoder-php/common-http)
[Plugin](https://github.com/geocoder-php/plugin) | `geocoder-php/plugin` | Plugin provider | [](https://packagist.org/packages/geocoder-php/plugin)
[](https://packagist.org/packages/geocoder-php/plugin)
## Special Geocoders and Providers
### The Chain Provider
The `Chain` provider is a special provider that takes a list of providers and
iterates over this list to get information. Note that it **stops** its iteration
when a provider returns a result. The result is returned by `GoogleMaps` because
`FreeGeoIp` and `HostIp` cannot geocode street addresses. `BingMaps` is ignored.
```php
use Geocoder\Query\GeocodeQuery;
$geocoder = new \Geocoder\ProviderAggregator();
$client = new \GuzzleHttp\Client();
$chain = new \Geocoder\Provider\Chain\Chain([
new \Geocoder\Provider\FreeGeoIp\FreeGeoIp($client),
new \Geocoder\Provider\HostIp\HostIp($client),
new \Geocoder\Provider\GoogleMaps\GoogleMaps($client, 'France'),
new \Geocoder\Provider\BingMaps\BingMaps($client, ''),
// ...
]);
$geocoder->registerProvider($chain);
$result = $geocoder->geocodeQuery(GeocodeQuery::create('10 rue Gambetta, Paris, France'));
var_export($result);
```
Everything is ok, enjoy!
### The ProviderAggregator
The `ProviderAggregator` is used to register several providers so that you can
decide which provider to use later on.
```php
use Geocoder\Query\GeocodeQuery;
use Geocoder\Query\ReverseQuery;
$client = new \GuzzleHttp\Client();
$geocoder = new \Geocoder\ProviderAggregator();
$geocoder->registerProviders([
new \Geocoder\Provider\GoogleMaps\GoogleMaps($client),
new \Geocoder\Provider\GoogleMaps\GoogleMapsBusiness($client, ''),
new \Geocoder\Provider\Yandex\Yandex($client),
new \Geocoder\Provider\MaxMind\MaxMind($client, ''),
new \Geocoder\Provider\ArcGISOnline\ArcGISOnline($client),
]);
$geocoder->registerProvider(new \Geocoder\Provider\Nominatim\Nominatim($adapter, 'https://your.nominatim.server'));
$geocoder
->using('google_maps')
->geocodeQuery(GeocodeQuery::create( ... ));
$geocoder
->limit(10)
->reverseQuery(ReverseQuery::fromCoordinates($lat, $lng));
```
The `ProviderAggregator`'s API is fluent, meaning you can write:
```php
use Geocoder\Query\GeocodeQuery;
$locations = $geocoder
->registerProvider(new \My\Provider\Custom($adapter))
->using('custom')
->limit(10)
->geocodeQuery(GeocodeQuery::create( ... ));
```
The `using()` method allows you to choose the `provider` to use by its name.
When you deal with multiple providers, you may want to choose one of them. The
default behavior is to use the first one but it can be annoying.
The `limit()` method allows you to configure the maximum number of results being
returned. Depending on the provider you may not get as many results as expected,
it is a maximum limit, not the expected number of results.
### TimedGeocoder
The `TimedGeocoder` class profiles each `geocode` and `reverse` call. So you can
easily figure out how many time/memory was spent for each geocoder/reverse call.
```php
use Geocoder\Query\GeocodeQuery;
// configure your provider
$provider = // ...
$stopwatch = new \Symfony\Component\Stopwatch\Stopwatch();
$geocoder = new \Geocoder\TimedGeocoder($provider, $stopwatch);
$geocoder->geocodeQuery(GeocodeQuery::create('Paris, France'));
// Now you can debug your application
```
We use the [symfony/stopwatch](http://symfony.com/doc/current/components/stopwatch.html)
component under the hood. Which means, if you use the Symfony framework the
geocoder calls will appear in your timeline section in the Web Profiler.
### StatefulGeocoder
The `StatefulGeocoder` class is great when you want your Geocoder to hold state. Say you want to configure locale,
limit or bounds in runtime. The `StatefulGeocoder` will append these values on each query.
```php
use Geocoder\Query\GeocodeQuery;
// configure your provider
$provider = // ...
$geocoder = new \Geocoder\StatefulGeocoder($provider);
$geocoder->setLocale('en');
$results = $geocoder->geocodeQuery(GeocodeQuery::create('London'));
echo $results->first()->getLocality(); // London
$geocoder->setLocale('es');
$results = $geocoder->geocodeQuery(GeocodeQuery::create('London'));
echo $results->first()->getLocality(); // Londres
```
## Dumpers
**Geocoder** provides dumpers that aim to transform a `Location` object in
standard formats.
### GPS eXchange Format (GPX)
The **GPS eXchange** format is designed to share geolocated data like point of
interests, tracks, ways, but also coordinates. **Geocoder** provides a dumper to
convert a `Location` object in an GPX compliant format.
Assuming we got a `$location` object as seen previously:
```php
$dumper = new \Geocoder\Dumper\Gpx();
$strGpx = $dumper->dump($location);
echo $strGpx;
```
It will display:
```xml
```
### GeoJSON
[GeoJSON](http://geojson.org/) is a format for encoding a variety of geographic
data structures.
### GeoArray
Simple PHP array format for using with your own encoders.
### Keyhole Markup Language (KML)
[Keyhole Markup Language](http://en.wikipedia.org/wiki/Keyhole_Markup_Language)
is an XML notation for expressing geographic annotation and visualization within
Internet-based, two-dimensional maps and three-dimensional Earth browsers.
### Well-Known Binary (WKB)
The Well-Known Binary (WKB) representation for geometric values is defined by
the OpenGIS specification.
### Well-Known Text (WKT)
Well-known text (WKT) is a text markup language for representing vector geometry
objects on a map, spatial reference systems of spatial objects and
transformations between spatial reference systems.
## Formatters
A common use case is to print geocoded data. Thanks to the `StringFormatter`
class, it's simple to format a `Location` object as a string:
```php
// $location is an instance of Location
$formatter = new \Geocoder\Formatter\StringFormatter();
$formatter->format($location, '%S %n, %z %L');
// 'Badenerstrasse 120, 8001 Zuerich'
$formatter->format($location, '
%S %n, %z %L
');
// 'Badenerstrasse 120, 8001 Zuerich
'
```
Here is the mapping:
* Street Number: `%n`
* Street Name: `%S`
* City (Locality): `%L`
* City District (Sub-Locality): `%D`
* Zipcode (Postal Code): `%z`
* Admin Level Name: `%A1`, `%A2`, `%A3`, `%A4`, `%A5`
* Admin Level Code: `%a1`, `%a2`, `%a3`, `%a4`, `%a5`
* Country: `%C`
* Country Code: `%c`
* Timezone: `%T`
## Versioning
Geocoder follows [Semantic Versioning](http://semver.org/).
### End Of Life
#### 1.x
As of December 2014, branch `1.7` is not officially supported anymore, meaning
major version `1` reached end of life. Last version is:
[1.7.1](https://github.com/geocoder-php/Geocoder/releases/tag/1.7.1).
#### 2.x
As of December 2014, version [2.x](https://github.com/geocoder-php/Geocoder/tree/2.x)
is in a **feature frozen** state. All new features should be contributed to version 3.0
and upper. Last version is:
[2.8.1](https://github.com/geocoder-php/Geocoder/releases/tag/2.8.1).
Major version `2` will reach **end of life on December 2015**.
#### 3.x
As of January 2017, version [3.x](https://github.com/geocoder-php/Geocoder/tree/3.x)
is in a **feature frozen** state. All new features should be contributed to version 4.0
and upper. Last version is:
[3.3.2](https://github.com/geocoder-php/php-common/releases/tag/v3.3.2).
Major version `3` will reach **end of life on October 2017**.
### Stable Version
Version `4.x` is the current major stable version of Geocoder.
### Next version
There is no new major version planned at this time.
## Contributing
See [`CONTRIBUTING`](https://github.com/geocoder-php/Geocoder/blob/master/CONTRIBUTING.md#contributing) file.
## Unit Tests
In order to run the test suite, install the development dependencies:
```cmd
composer install --dev
```
Then, run the following command:
```cmd
composer test
```
You'll obtain some _skipped_ unit tests due to the need of API keys.
Rename the `phpunit.xml.dist` file to `phpunit.xml`, then uncomment the
following lines and add your own API keys:
```xml
```
You're done.
## Credits
* William Durand
* Tobias Nyholm
* [All contributors](https://github.com/geocoder-php/Geocoder/contributors)
## License
Geocoder is released under the MIT License. See the bundled LICENSE file for details.