Download the PHP package nolazybits/propel2-geocodable-behavior without Composer
On this page you can find all versions of the php package nolazybits/propel2-geocodable-behavior. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download nolazybits/propel2-geocodable-behavior
More information about nolazybits/propel2-geocodable-behavior
Files in nolazybits/propel2-geocodable-behavior
Package propel2-geocodable-behavior
Short Description 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.
License MIT
Informations about the package propel2-geocodable-behavior
GeocodableBehavior
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.
This behavior uses Geocoder, the Geocoder PHP 5.3 library and requires Propel 2.0-dev and above.
Installation
You need to add it to composer.
Propel will automatically add it to the list of available behavior
Usage
Just add the following XML tag in your schema.xml
file:
Basically, the behavior will add:
- two new columns to your model (
latitude
andlongitude
); - four new methods to the ActiveRecord API (
getDistanceTo()
,isGeocoded()
,getCoordinates()
, andsetCoordinates()
); - 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:
- a geocoded object;
- a measure unit (
KILOMETERS_UNIT
,MILES_UNIT
, orNAUTICAL_MILES_UNIT
defined in thePeer
class of the geocoded model).
isGeocoded()
returns a boolean value whether the object has been geocoded,
or not.
getCoordinates()
, setCoordinates()
allows to quickly set/get latitude,
and longitude values.
ActiveQuery API
withDistance()
takes three arguments:
- a latitude value;
- a longitude value;
- a measure unit (
KILOMETERS_UNIT
,MILES_UNIT
, orNAUTICAL_MILES_UNIT
defined in thePeer
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.
filterByDistanceFrom()
takes five arguments:
- a latitude value;
- a longitude value;
- a distance value;
- a measure unit (
KILOMETERS_UNIT
,MILES_UNIT
, orNAUTICAL_MILES_UNIT
defined in thePeer
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.
filterNear
takes three arguments:
- a model object;
- a distance value;
- a measure unit (
KILOMETERS_UNIT
,MILES_UNIT
, orNAUTICAL_MILES_UNIT
defined in thePeer
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 ?
Automatic geocoding to the rescue! There are two automatic ways to get geocoded information:
- 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.
This method returns a
ResultInterface
object, so you can override this method to fill in more fields depending on your
model:
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:
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.
By default, the default Geocoder provider
is YahooProvider
so you'll need to
fill in an API key.
If you want to use another provider, you'll need to set a new parameter:
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:
The behavior will now use the ip_address
value to populate the latitude
,and
longitude
columns thanks to Geocoder.
Address-Based Geocoding
To enable the Address-Based geocoding, add the following configuration:
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:
Read the Geocoder documentation to know more about providers.
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:
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:
Read the Geocoder documentation to know more about adapters.
Parameters
This is the default configuration.
Credits
William Durand [email protected]
Xavier Martin [email protected]