Blog: The Behavior Tour: Meet The Geocodable Behavior
Propel comes with a large set of behaviors but most of them are already well-known. However, we noticed that a lot of people didn't know about the awesome user contributions we have in the Propel community. In this series, we will introduce a new user contributed Propel behavior each week.
The GeocodableBehavior helps you build geo-aware applications by providing geocoding features to your ActiveRecord objects. It's also a wrapper for the powerful Geocoder library designed to solve geocoding problematics in PHP.
The GeocodableBehavior provides new methods to both the ActiveRecord and the ActiveQuery APIs, and it works fine without Geocoder. Basically, adding this behavior to your XML schema will:
- add two new columns to your model:
latitudeandlongitude; - add four new methods to the ActiveRecord API:
getDistanceTo(),isGeocoded(),getCoordinates(), andsetCoordinates(); - add two new methods to the ActiveQuery API:
filterByDistanceFrom(),filterNear().
The getDistanceTo() method returns the distance between the current object and a given one. You can specify the measure unit: KILOMETERS_UNIT,MILES_UNIT, or NAUTICAL_MILES_UNIT.
The filterByDistanceFrom() method adds a filter by distance on your current query and returns itself for fluid interface. This method is useful when you want to get results around a given position. The filterNear() is pretty much the same but takes a geocoded object instead of a position.
Then again, you get these methods for free, you just have to install the behavior and that's it. But this behavior is also a wrapper for the Geocoder library, so it does a lot more like automatic geocoding. There are two strategies: IP-address based, or Street-address based. The behavior guesses useful columns in your table in order to perform geocoding requests. Basically, the behavior looks for attributes called street, locality, region, postal code/zip code, and country. It tries to make a complete address with them. As usual, you can add your own list of attributes that represents a complete street address thanks to the address_columns parameter.
By using Geocoder and the automatic geocoding feature, a new method will be available in the ActiveRecord API: geocode(). This method will be triggered on save or update, but you can disable the autofill on update thanks to the auto_update parameter. For more information, read the documentation about automatic geocoding and this blog post about Geocoder.
This behavior is highly configurable and here is the reference configuration:
As you can see, you can configure Geocoder to fit your needs without any effort. This behavior is really flexible, and works with Propel 1.6.4 or higher. It is fully unit tested, and hosted on GitHub: willdurand/GeocodableBehavior. The Geocoder library is also hosted on GitHub: willdurand/Geocoder.