GMap 2.3 Manual

Overview

GMap provides a PHP wrapper around the Google Maps Javascript API. Its purpose is to allow a web developer to easily add Google Maps and driving directions to web pages using PHP.

The GMap class is used to create and configure each map (and optional directions) on your page.

If you are creating a map without directions, you must add at least one GMarker object to the GMap. If you add more than one GMarker, the map will be automatically centered and zoomed to display all markers. The GMarker class is also used to set the marker info window contents. The GMap showLocation function will create a GMarker for you. This is useful if you only need one marker and do not need to customize it.

You can add GMarkers to a directions map. Markers will be displayed in addition to the start and end location markers. One or more markers may be added as waypoints to the directions.

The icon associated with each marker can be modified using the GIcon class. You can customize the icon for the entire map (all markers) or customize individual marker icons.

Geocoding is provided by the getLocation function and the GLocation class. These can be used to obtain the latitude and longuitude (as well as city, county, state, postal code, etc.) of any address that is recognized by Google.

System Requirements

• PHP 4.3+
• Google Maps API Key

Installation Instructions

1. Configure

   Edit the gmap_config.php file:

   Set GOOGLE_MAP_API_KEY to the Google Map API key to you obtained from Google.

2. Upload

   Upload everything to your site.

3. Test Installation

   Open examples/index.php in a browser and view the examples.

Maps

Any page that contains a map must contain the following:

• A div element for each map.
• PHP to create and configure a GMap object.

The div element

Specify the height and width of the map in pixels, either in the div tag itself or an external CSS file that is included in the head of the document. For example:

If you do not specify the width, the map will exand to fill its container.

If you have multiple maps on one page, each div id should be unique:

PHP Code

You need PHP code to include the gmap.php file and create a GMap object.

A location string can be passed to the showLocation function. This will display the map centered on the location with a marker for the location.

Alternately, an array of GMarker objects can be created and passed to the showMap function. This will display a map that is automatically zoomed and centered to include all locations/markers.

Marker Geocodes

In order for a marker to be displayed on a map, it's geocode (latitude/longitude) must be obtained. There is a daily limit on the number of geocode requests per day from any IP address. Exceeding this limit can result in having the IP address temporarily blocked. If the limits continue to be exceeded, the IP address may be blocked permanently.

There are three ways to obtain and set the marker's geocode:

1. Browser Geocodes

   This is the default setting. The browser (client) obtains the geocode for a marker's address using Javacsript. Each request is counted against the browser's IP address.

2. Server Geocodes

   You can have your server obtain the geocode for each address using PHP. Each request is counted againts the server's IP address.

   $gmap = new GMap();
   $gmap->server_geocodes = true;
   $gmap->showLocation('New York');

   NOTE: If your server obtains the geocodes, you run the risk of exceeding the daily limits and having your server's IP address blocked, either temporarily or permanently.

3. Hardcoded

   If you already know a marker's lat/lon (i.e., from a database), you can specify them:

   $markers[0] = new GMarker('','Statue of Liberty');
   $markers[0]->lat = 40.689201355;
   $markers[0]->lon = -74.0447998047;

   This method avoids a geocode request in order to display the marker.

Driving Directions

Any page that contains Google driving directions must have the following elements:

• A div element for the map.
• A div element for the directions.
• PHP to load the directions.

The div elements

One div element placeholder for the map and another for the driving directions.

PHP Code

PHP code to include the gmap.php script and create a GMap object. The map and directions are displayed by calling the showDirections function with start and end address strings as arguments.

You can add one or more markers to the driving directions by creating an array of indexes. Each index corresponds to a marker in the GMap's marker array. For example:

will add the first two markers as waypoints to the driving directions.

Locales

You can change the language of the directions by setting the locale. The following examples show how to set the locale for some selected languages:

$gmap->locale = 'fr';

$gmap->locale = 'de';

$gmap->locale = 'el';

$gmap->locale = 'es';

$gmap->locale = 'ru';

Controls

Google Bar

A Google Bar is a control that allows a user to perform a search for locations within the map. To add a Google Bar to a map:

$gmap = new GMap(); 
$gmap->enable_google_bar = true; 

By default, a user must click on the Google Bar to expand it and display a field for search input. To show the Google Bar as already expanded when it is displayed:

$gmap = new GMap(); 
$gmap->enable_google_bar = true; 
$gmap->show_bar_on_load = true; 

Map Overview

A map overview is small corner map showing a wider area. To display a map overview:

$gmap = new GMap(); 
$gmap->show_overview_map_control = true; 

Overlays

AdSense

Fetch and display ads to the map by creating a GAdsManager object with your publisher ID.

Traffic

You can display current road traffic information on your map for supported cities.

If you want a button to toggle the trafic overlay on/off, add the following to your page:

For a checkbox:

Polylines

To display a polyline on your map:

1. Create an array of GLatLng objects. For example:
   $pt[0] = new GLatLng(40.689172,-74.044608);
   $pt[1] = new GLatLng(40.826944,-73.928181);
   $pt[2] = new GLatLng(40.755675,-73.84815);

   GLatLng objects can be created using a latitude/longitude like above or an address string:

   $pt[0] = new GLatLng('New York');
2. Create a GPolyline object, passing in the GLatLng array and setting the line color and weight.
   $line = new GPolyline($pt,"#0000ff",20);
3. Add the GPolyline to the GMap object.
   $gmap->addPolyline($line);

Geodesic lines follow the curvature of the Earth and represent the shortest distance between two points on the surface of the Earth. They appear as curved lines on a flat map. If you want the lines to be displayed as geodesic lines:

Polygons

The creation of a polygon is similar to a polyline:

1. Create an array of GLatLng objects. For example:
   $pt[0] = new GLatLng(40.689172,-74.044608);
   $pt[1] = new GLatLng(40.826944,-73.928181);
   $pt[2] = new GLatLng(40.755675,-73.84815);
   $pt[3] = new GLatLng(40.689172,-74.044608);

   Note that the last point is the same as the first point in the array. This closes the polygon.

2. Create a GPolygon object, passing in the GLatLng array and setting the color.
   $polygon = new GPolygon($pt,"#0000ff");

   There are additional settings you can specify including different colors for the edge and fill area and the opacity of each as well. See the GPolygon constructor description for more infomration.

3. Add the GPolygon to the GMap object.
   $gmap->addPolygon($polygon);

Markers & Icons

Markers are used to indicate a location on a map. Each marker has a point (latitude and longitude) and an icon. When a user clicks on a marker icon, an info window is displayed.

You can customize the marker icons and info window contents.

Creating Markers

Create a new GMarker object, passing in an address string:

You can also pass in a latitude and longitude:

You add the markers to the GMap, by creating an array of one or more GMarkers and calling the showMap function:

$markers[0] = new GMarker('New York, NY'); 
$markers[1] = new GMarker('Boston, MA'); 
$markers[2] = new GMarker('New Haven, CT'); 

$gmap = new GMap(); 
$gmap->showMap($markers); 

Marker Info Window

By default, the marker's info window will display the address string. You can specify an additional title and URL:

$markers[0] = new GMarker('2800 East Observatory Road Los Angeles, CA 90027',
                          'Griffith Observatory',
                          'http://www.griffithobservatory.org/');

A hyperlink will be created using the title and URL, followed by the address string.

To specify the entire contents of the marker info window, create a string containing the HTML you want displayed. Be sure to use the addslashes function when setting the marker info:

$marker = new GMarker('New York, NY');

$html = '<p>This is some HTML</p>'.
        '<p>This is some more HTML</p>';

$marker->info = addslashes($html); 

Custom Icons

To change the default icon for all markers on the map, create a new GIcon object, specifying the URL to the image you want to use, along with its width and height in pixels, and pass it to the GMap object:

To change the default icon for a specific marker on the map, set the icon on the GMarker object, instead of the GMap:

Draggable Markers

You can make your markers draggable by the user. For example:

If you define a Javascript function called markerDragUpdate(marker, point), this function will be called as the marker is dragged, giving you access to the marker's current latitude and longitude. The marker argument is a Google Map API GMarker object and the point argument is a Google Maps API GLatLng object.

For example, the following function will update a form with the marker's title and current latitude and longitude:

<script language="javascript" type="text/javascript" defer>
<!--
function markerDragUpdate(marker, point) {
        document.myForm.title.value = marker.getTitle();
        document.myForm.lat.value = point.lat();
        document.myForm.lon.value = point.lng();
}
// -->
</script>

<form name="myForm"> 
Title <input type="text" name="title"> 
Lat <input type="text" name="lat"> 
Lon <input type="text" name="lon" value=""> 
</form>  

Marker Hyperlinks

You can create hyperlinks that will display a marker's info window using the markerLink function. For example:

This will create a hyperlink to marker zero's info window.

Geocoding

Use the getLocation() function to obtain geocode data for any address string recognized by Google as a valid address.

To geocode form input, create a form with an address field and hidden lat/lon fields:

<form method="post" action=""> 
Enter Address  
<input type="text" name="address" size="80" onKeyPress="return checkAddressEnter(this.form,event)"> 
<input type="hidden" name="lat"> 
<input type="hidden" name="lon"> 
<input type="submit" value="Submit" onClick="return geocodeForm(this.form);"> 
</form>

Include the necessary form-processing javascript by calling the code322_address_form_js() function.

When the user clicks submit, the Javascript will obtain the latitude and longitude of the entered address and set the hidden values of the form. It will then submit the form to the server.

Error Handling

By default, an alert window will be displayed if an occurs while attemping to display a map. You can ovveride this behavior and handle errors yourself, by turning off error handling and checking for errors in your code. Google Map API key errors will still be displayed in alert windows.

To turn off error handling:

$gmap->handle_errors = false;

Then check for errors after calling showLocation() or showMap():

if ($gmap->error) {
    foreach ($gmap->error_msg as $current) {
        echo $current;
    }
}

For directions, you can check each location using the getLocation() function before calling showDirections().

$fromLocation = getLocation($from);
if ($fromLocation->error) {
    echo 'Error: Code '.$fromLocation->code.' '.$fromLocation->status;
} 

Troubleshooting

Error: file_get_contents

Solution

Edit the gmap_config.php file and set:

Classes

Functions