willdurand/propel-geocodable-behavior

The GeocodableBehavior helps you build geo-aware applications. It automatically geocodes your models when they are saved, giving you the ability to search by location and calculate distances between records.

Friday, August 1, 2014
by couac
Repository
4 Watchers
26 Stars
52,592 Installations

PHP
1 Dependents
0 Suggesters
18 Forks
5 Open issues
16 Versions
1 % Grown

The README.md

GeocodableBehavior

, _(*1)

The GeocodableBehavior helps you build geo-aware applications. It automatically geocodes your models when they are saved, giving you the ability to search by location and calculate distances between records., _(*2)

This behavior uses Geocoder, the Geocoder PHP 5.3 library and requires Propel 1.6.4-dev and above., _(*3)

Installation

Cherry-pick the GeocodableBehavior.php file is src/, put it somewhere, then add the following line to your propel.ini or build.properties configuration file:, _(*4)

``` ini propel.behavior.geocodable.class = path.to.GeocodableBehavior, _(*5)


Usage
-----

Just add the following XML tag in your `schema.xml` file:

``` xml
<behavior name="geocodable" />

Basically, the behavior will add:, _(*6)

two new columns to your model (latitude and longitude);
four new methods to the ActiveRecord API (getDistanceTo(), isGeocoded(), getCoordinates(), and setCoordinates());
three new methods to the ActiveQuery API (withDistance(), filterByDistanceFrom(), filterNear()).

ActiveRecord API

getDistanceTo() returns the distance between the current object and a given one. The method takes two arguments:, _(*7)

a geocoded object;
a measure unit (KILOMETERS_UNIT, MILES_UNIT, or NAUTICAL_MILES_UNIT defined in the Peer class of the geocoded model).

isGeocoded() returns a boolean value whether the object has been geocoded, or not., _(*8)

getCoordinates(), setCoordinates() allows to quickly set/get latitude, and longitude values., _(*9)

ActiveQuery API

withDistance() takes three arguments:, _(*10)

a latitude value;
a longitude value;
a measure unit (KILOMETERS_UNIT, MILES_UNIT, or NAUTICAL_MILES_UNIT defined in the Peer class of the geocoded model);

It will add a Distance column on your current query and returns itself for fluid interface. Example use: combine with orderByDistance() and limit() to return closest matches., _(*11)

filterByDistanceFrom() takes five arguments:, _(*12)

a latitude value;
a longitude value;
a distance value;
a measure unit (KILOMETERS_UNIT, MILES_UNIT, or NAUTICAL_MILES_UNIT defined in the Peer class of the geocoded model);
a comparison sign (Criteria::LESS_THAN is the default value).

It will add a filter by distance on your current query and returns itself for fluid interface., _(*13)

filterNear takes three arguments:, _(*14)

a model object;
a distance value;
a measure unit (KILOMETERS_UNIT, MILES_UNIT, or NAUTICAL_MILES_UNIT defined in the Peer class of the geocoded model).

Automatic Geocoding

At this step, you have to fill in the two columns (latitude and longitude) yourself. It's not really useful, right ?, _(*15)

Automatic geocoding to the rescue! There are two automatic ways to get geocoded information:, _(*16)

using IP addresses;
using street addresses.

It provides a geocode() method that autoupdate the location values. To prevent autofill when modified, just set auto_update attribute to false., _(*17)

This method returns a ResultInterface object, so you can override this method to fill in more fields depending on your model:, _(*18)

``` php <?php, _(*19)

class MyObject extends BaseMyObject { // ..., _(*20)

/**
 * {@inheritdoc}
 */
public function geocode()
{
    if (null !== $result = parent::geocode()) {
        if ($city = $result->getCity()) {
            $this->setCity($city);
        }
    }

    return $result;
}

}, _(*21)


Note: You can use both at the same time.

### IP-Based Geocoding ###

To enable the IP-Based geocoding, add the following configuration in your
`schema.xml` file:

``` xml
<behavior name="geocodable">
    <parameter name="geocode_ip" value="true" />
    <parameter name="geocoder_api_key" value="<API_KEY>" />
    <parameter name="geocoder_api_key_provider" value="<API_KEY_PROVIDER>" />
</behavior>

The geocoder_api_key_provider can be either a static method returning the api key. A class method in the format class()->method() or class()->method()->subMethod(), or a class implementing getGoogleMapsKey which must return the key., _(*22)

By default, the default Geocoder provider is YahooProvider so you'll need to fill in an API key., _(*23)

If you want to use another provider, you'll need to set a new parameter:, _(*24)

``` xml , _(*25)


Read the **Geocoder** documentation to know more about providers.

This configuration will add a new column to your model: `ip_address`.
You can change the name of this column using the following parameter:

``` xml
<parameter name="ip_column" value="ip" />

The behavior will now use the ip_address value to populate the latitude,and longitude columns thanks to Geocoder., _(*26)

Address-Based Geocoding

To enable the Address-Based geocoding, add the following configuration:, _(*27)

``` xml , _(*28)


By default, the default Geocoder `provider` is `YahooProvider` so you'll need to
fill in an API key but keep in mind it's an optional parameter depending on the
provider you choose.

If you want to use another provider, you'll need to set a new parameter:

``` xml
<parameter name="geocoder_provider" value="\Geocoder\Provider\GoogleMapsProvider" />

Read the Geocoder documentation to know more about providers., _(*29)

Basically, the behavior looks for attributes called street, locality, region, fpostal_code, and country. It tries to make a complete address with them. As usual, you can tweak this parameter to add your own list of attributes that represents a complete street address:, _(*30)

``` xml , _(*31)


These parameters will be concatenated and separated by a comma to make a street
address. This address will be used to get `latitude` and `longitude` values.

Now, each time you save your object, the two columns `latitude`, and `longitude`
are populated thanks to **Geocoder**.


HTTP Adapters
-------------

**Geocoder** provides HTTP adapters which can be configured through the behavior.
By default, this behavior uses the `CurlHttpAdapter`.

If you want to use another `adapter`, you'll need to use the following parameter:

``` xml
<parameter name="geocoder_adapter" value="\Geocoder\HttpAdapter\BuzzHttpAdapter" />

Read the Geocoder documentation to know more about adapters., _(*32)

Parameters

<behavior name="geocodable">
    <parameter name="auto_update" value="true" />

    <parameter name="latitude_column" value="latitude" />
    <parameter name="longitude_column" value="longitude" />
    <parameter name="type" value="DOUBLE" />
    <parameter name="size" value="10" />
    <parameter name="scale" value="8" />


    <!-- IP-Based Geocoding -->
    <parameter name="geocode_ip" value="false" />
    <parameter name="ip_column" value="ip_address" />

    <!-- Address-Based Geocoding -->
    <parameter name="geocode_address" value="false" />
    <parameter name="address_columns" value="street,locality,region,postal_code,country" />

    <!-- Geocoder -->
    <parameter name="geocoder_provider" value="\Geocoder\Provider\YahooProvider" />
    <parameter name="geocoder_adapter" value="\Geocoder\HttpAdapter\CurlHttpAdapter" />
    <parameter name="geocoder_api_key" value="false" />
    <parameter name="geocoder_api_key_provider" value="false" />
</behavior>

This is the default configuration., _(*33)

Credits

William Durand william.durand1@gmail.com, _(*34)

library propel-geocodable-behavior

The GeocodableBehavior helps you build geo-aware applications. It automatically geocodes your models when they are saved, giving you the ability to search by location and calculate distances between records.

willdurand/propel-geocodable-behavior

The README.md

GeocodableBehavior

Installation

ActiveRecord API

ActiveQuery API

Automatic Geocoding

Address-Based Geocoding

Parameters

Credits

Links

The Versions

dev-master

The Requires

by William Durand

1.2.1

The Requires

by William Durand

1.2.0

The Requires

by William Durand

1.1.0

The Requires

by William Durand

1.0.11

The Requires

The Development Requires

by William Durand

1.0.10

The Requires

The Development Requires

by William Durand

1.0.9

The Requires

The Development Requires

by William Durand

1.0.8

The Requires

The Development Requires

by William Durand

1.0.7

The Requires

The Development Requires

by William Durand

1.0.6

The Requires

The Development Requires

by William Durand

1.0.5

The Requires

The Development Requires

by William Durand

1.0.4

The Requires

The Development Requires

by William Durand

1.0.3

The Requires

The Development Requires

by William Durand

1.0.2

The Requires

The Development Requires

by William Durand

1.0.1

The Requires

The Development Requires

by William Durand

1.0.0

The Requires

The Development Requires

by William Durand