Add a Google map to your PHP site

With the GoogleMapAPI project, you can easily add a Google Map to your PHP Web site.

GoogleMapAPI is not packaged for Ubuntu, Fedora or openSUSE. For this article I'll use a 64-bit Fedora 9 machine with version 2.5 of GoogleMapAPI. The commands shown below install the main PHP file in a site-accessible directory, with the remainder of the distribution in /usr/local for reference.

To use Google Maps on your site you'll need your own Google Maps API key. The Web server that you install GoogleMapAPI onto will need access to the Internet to serve requests. This is mainly important if your Web server is firewalled from the Internet. A request made to port 80 on http://maps.google.com/maps/geo from the Web server must succeed in order for your maps to appear.

The below page shows how to get started putting a map on your site. There are two regions of boilerplate code here: The first block consists of the inclusion of the PHP class, creation of the gmaps object, and setting the Google Maps API key. The second block is the calls to the methods of the gmaps object to have it put the required HTML and JavaScript in the HTML page. The main section that is likely to be of interest is the call to addMarkerByAddress, which is likely to be the only part of the code that changes.

The GoogleMapAPI object has many other useful methods. With the setDSN method you can supply the connection information for a relational database used for caching geocoding information. You will need the PEAR::DB package installed to use a geocode cache. Google allows a fairly generous limit to the rate and total requests per day of geocoding queries -- though caching the results is always preferable if you are showing the same addresses over and over again.

You can also select another provider for your geocode lookups using setLookupService. Among the supported providers is Yahoo!. You can perform geocode lookups without affecting the map using getGeocode, which returns the longitude and latitude of the address if it can be determined. You can also insert your own geocode information into the database cache using putCache, or force a lookup to avoid the cache using geoGetCoords.

You can change the size of the Google Map using the setWidth and setHeight methods, and change the way the map is presented using disableMapControls disable the ability to move and zoom the map, disableTypeControls to remove the satellite and street map buttons, disableSidebar to remove the sidebar that shows the title for all of your markers, disableDirections to remove the directions area, and disableZoomEncompass to stop the map from being automatically zoomed to show all your markers. setMapType takes a string selecting which type of map (satellite, hybrid, or map) to use. There are also a number of other methods you can use to disable various elements of the Google Maps display so you can lock down what users can do with the map and how it will appear to them.

There are methods for setting the zoom level (setZoomLevel) and initial position (adjustCenterCoords) of the map. These positioning methods are mainly of interest if you are not adding any markers to the map. If you are, in addition to the addMarkerByAddress method shown in the above example, there is addMarkerByCoords, which lets you add a marker at a specific longitude and latitude. You can connect two addresses or longitude-latitude pairs with a line on the map using addPolyLineByAddress and addPolyLineByCoords respectively. You can change the image used for markers on the map either globally using setMarkerIcon or for each individual marker using addMarkerIcon.

For an example of some of these methods, add the following code where the original addMarkerByAddress block was in the above example. Note that adding a polyline between two addresses will show "as the crow flies," which is probably not what you want. To display a walkable route you have to manually create the path using a collection of polyline segments between latitude and longitude coordinates, as shown. The portion of the code below the ellipsis is the end of file, where a simple geocode lookup is performed and the result displayed to the browser. The screenshot follows the example.

One minor issue: if you are connecting two points with a manually constructed polyline, you have to specify each segment using addPolyLineByCoords. It would be nice to be able to pass in an array of latitude and longitude coordinates describing the entire trail rather than repeating the destination coordinate as the source coordinate in the next addPolyLineByCoords call.

GoogleMapAPI is licensed under the LGPL and free to use. It has good programmers' documentation and integrates with Smarty templates so you can keep your Web page design separate from your functionality.