Skip to content

Latest commit

 

History

History
287 lines (221 loc) · 7.52 KB

index.md

File metadata and controls

287 lines (221 loc) · 7.52 KB

BazingaGeocoderBundle

Integration of the Geocoder library into Symfony.

Installation

To install this bundle you need to know how to install the geocoder and providers and then you may just install the bundle like normal:

composer require willdurand/geocoder-bundle:^5.0

Register the bundle in app/AppKernel.php:

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Bazinga\GeocoderBundle\BazingaGeocoderBundle(),
    );
}

Usage

The bundle helps you register your providers and to enable profiling support. To configure a provider you must use a ProviderFactory. See the following example using Google Maps.

bazinga_geocoder:
  providers:
    acme:
      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory

This will create a service named bazinga_geocoder.provider.acme which is a GoogleMapsProvider.

You can also configure all ProviderFactories to adjust the behavior of the provider.

bazinga_geocoder:
  providers:
    acme:
      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
      cache: 'any.psr16.service'
      cache_lifetime: 3600
      aliases: 
        - my_geocoer

This will create a service named my_geocoder that caches the responses for one hour.

Most ProviderFactories do also take an array with options. This is usually parameters to the constructor of the provider. In the example of Google Maps:

bazinga_geocoder:
  providers:
    acme:
      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
      options: 
        httplug_client: 'httplug.client' # When using HTTPlugBundle
        region: 'Sweden'
        api_key: 'xxyy'

Fake local ip

You can fake the REMOTE_ADDR HTTP parameter through this bundle in order to get information in your development environment, for instance:

/**
 * @Template()
 */
public function indexAction(Request $request)
{
    // Retrieve information from the current user (by its IP address)
    $result = $this->container
        ->get('bazinga_geocoder.provider.acme')
        ->geocodeQuery(GeocodeQuery::create($request->server->get('REMOTE_ADDR')));

    // Find the 5 nearest objects (15km) from the current user.
    $coords = $result->first()->getCoordinates();;
    $objects = ObjectQuery::create()
        ->filterByDistanceFrom($coords->getLatitude(), $coords->getLongitude(), 15)
        ->limit(5)
        ->find();

    return array(
        'geocoded'        => $result,
        'nearest_objects' => $objects
    );
}

In the example above, we'll retrieve information from the user's IP address, and 5 objects nears him. But it won't work on your local environment, that's why this bundle provides an easy way to fake this behavior by using a fake_ip configuration.

# app/config/config_dev.yml
bazinga_geocoder:
    fake_ip:    123.123.123.123

If set, the parameter will replace all instances of "127.0.0.1" in your queries and replace them with the given one.

Registering Your Own Providers

If you want to use your own provider in your application, create a service, and tag it as bazinga_geocoder.provider:

<service id="acme_demo.geocoder.my_provider" class="Acme\Demo\Geocoder\Provider\MyProvider">
    <tag name="bazinga_geocoder.provider" />
</service>

The bundle will automatically register your provider into the Geocoder\ProviderAggregator service and you provider will show up in the profiler.

Dumpers

If you need to dump your geocoded data to a specific format, you can use the Dumper component. The following dumper's are supported:

  • Geojson
  • GPX
  • KMP
  • WKB
  • WKT

Here is an example:

<?php

public function geocodeAction(Request $request)
{
    $result = $this->container
        ->get('bazinga_geocoder.provider.acme')
        ->geocodeQuery(GeocodeQuery::create($request->server->get('REMOTE_ADDR')));

    $body = $this->container
        ->get('Geocoder\Dumper\GeoJson')
        ->dump($result);

    $response = new Response();
    $response->setContent($body);

    return $response;
}

To register a new dumper, you must tag it with bazinga_geocoder.dumper.

<service id="some.dumper" class="%some.dumper.class">
    <tag name="bazinga_geocoder.dumper" alias="custom" />
</service>

Cache Results

Sometimes you have to cache the results from a provider. For this case the bundle provides simple configuration. You only need to provide a service name for you SimpleCache (PSR-16) service and you are good to go.

bazinga_geocoder:
  providers:
    acme:
      factory: Bazinga\GeocoderBundle\ProviderFactory\GoogleMapsFactory
      cache: 'any.psr16.service'
      cache_lifetime: 3600

Custom HTTP Client

The HTTP geocoder providers integrates with HTTPlug. It will give you all the power of the HTTP client. You have to select which one you want to use and how you want to configure it.

Read their usage page, you may also be interested in checking out the HTTPlugBundle.

An example, if you want to use Guzzle6.

composer require php-http/guzzle6-adapter php-http/message

Reference Configuration

You'll find the reference configuration below:

# app/config/config.yml
bazinga_geocoder:
    profiling: 
        enabled: ~                # Default is same as kernel.debug
    fake_ip:
        enabled:              true
        ip:                   null
    providers:
        # ... 
        acme:
            factory:  ~           # Required
            cache: ~
            cache_lifetime: ~
            aliases: 
                - acme
                - acme_geocoder
            options:
                foo: bar
                biz: baz

Backwards compatibility

The BazingaGeocoderBundle is just a Symfony integration for Geocoder-PHP and it does not have any classes which falls under the BC promise. The backwards compatibility of the bundle is only the configuration and its values (and of course the behavior of those values).

The public service names (excluding the ones related to profiling/DataCollector) falls under the backwards compatibility promise.

Bottom line is, that you can trust that your configuration will not break and that the services you use will still be working.

Testing

Setup the test suite using Composer:

composer update
composer test

Doctrine test

There is also a test that tests the doctrine integration. It runs automatically on Traivs but if you want to run it locally you must do the following.

composer require phpunit/phpunit:^5.7 --no-update
composer update --prefer-source
wget https://phar.phpunit.de/phpunit-5.7.phar
php phpunit-5.7.phar --testsuit doctrine

Important: this command must be run with --prefer-source, otherwise the Doctrine\Tests\OrmTestCase class won't be found.