MapManager PHP Package

1.0

MapManager is a package that enhances the MapScript PHP extension by extending the API to provide facilties which ease the development of interactive maps.

Description

The MapManager class is the primary class in the package and represents a map. It provides for the serialisation of an instance which enables the state of a map to be easily maintained. Typical instantiation and map production would be as follows:

<?php

// the package definitions
require_once('mapmanager/mapmanager.php');

// define a mapfile
$mapfile = 'mapfile.map';

// create a MapManager using the mapfile
$map_manager = new MapManager($mapfile);

// do something with the MapManager, like zooming...

// render the map to an imageObj
$imageObj = $map_manager->draw();

// save the image to the web directory
print $imageObj->saveWebImage();

// serialise the MapManager
$string = serialize($map_manager);

// do something with the string, like save it between web requests...

// unserialise a MapManager
$new_map_manager = unserialize($string);

?>

The two main areas where the MapScript API has been enhanced involve zooming in a map and customising the drawing of layers with PHP code.

Zooming

In order to make the zooming easier to use, the concept of a 'click point' has been used in the implementation. A click point is the point, in map coordinates, that a user has clicked on. In zoom terms this provides the location to zoom in to or out of, or to pan to. This is demonstrated in the following code:

<?php

// create a click point representing a click on an image created from
// the map. This click point is in pixel coordinates
$image_click_point = ms_newPointObj();
$image_click_point->setXY(31, 43);

// the click point should be in map coordinates, so convert it
$map_click_point = $map_manager->imagePointToMapPoint($image_click_point);

// set the point as being the click point for MapManager's main map
$map_manager->setMapClick($map_click_point, MM_CLICK_MAIN);

// set the zoom type to zoom in
$map_manager->setZoomType(MM_ZOOM_IN);

// set the zoom factor
$map_manager->setZoomLevel(4);

// perform the zoom operation
$map_manager->zoom();

// draw the map etc...

?>

Layer Rendering

Basic PHP MapScript does not provide for drawing (rendering) specific layers using custom code, and yet this is a common requirement of mapping applications. It would be useful, for example, to have a plugin-architecture that allows rendering callbacks (renderers) to be assigned to certain layers. Renderers would then be called automatically when the map is drawn. MapManager provides this architecture. Typical usage is as follows.

<?php

// layer rendering callback function. Must receive imageObj as
// argument.
function special_layer_renderer($imageObj) {
    // get a layerObj
    $layerObj = ms_newLayerObj($GLOBALS['mapObj']);

    // add whatever features are required to the layer using the
    // standard MapScript API. The data for these features could come,
    // for example, from a database.

    // draw the layer on the image...
    $layerObj->draw($imageObj);
}

// the name of the layer we want to specify a renderer for...
$layer_name = 'special_layer';

// ensure the layer exists
if (!$map_manager->layerExists($layer_name)) {
    trigger_error(sprintf('The layer %s does not exist!', $layer_name), E_USER_ERROR);
}

// add the layer renderer to the MapManager
$map_manager->setLayerRenderer($layer_name, 'special_layer_renderer');

// ensure the status of the layer is on, otherwise it won't be drawn
if (!$map_manager->layerIsOn($layer_name)) {
    $map_manager->turnLayerOn($layer_name);
}

// draw the map, returning an $imageObj with our custom layer rendered
$imageObj = $map_manager->draw();

?>

The callback function used as a renderer can also be a method of an object. Commonly the MapManager object itself would be subclassed so that all the required map properties are available:

<?php

// get the MapManager definition
require_once('mapmanager/MapManager.php');

class MyMapManager extends MapManager {

    function MyMapManager($map_file) {
        $this->MapManager($map_file);

        // register the layer renderer
        $this->setLayerRenderer('special_layer', array(&$this, 'specialLayerRenderer'));
    }

    // the layer renderer
    function specialLayerRenderer($imageObj) {
        // get a layerObj
        $layerObj = $this->getLayerByName('special_layer');

        // add whatever features are required to the layer using the
        // standard MapScript API. The data for these features could come,
        // for example, from a database.

        // draw the layer on the image...
        $layerObj->draw($imageObj);        
    }
}

?>

A MyMapManager object can now be used in exactly the same way as any other MapManager.

---