.. _php5.6: ***************************************************************************** PHP MapScript ***************************************************************************** :Author: Daniel Morissette :Contact: dmorissette at mapgears.com :Author: Yewondwossen Assefa :Contact: yassefa at dmsolutions.ca :Revision: $Revision$ :Date: $Date$ .. warning:: This is the old PHP MapScript documentation. It only applies to MapServer 5.6 and older. .. contents:: :depth: 3 :backlinks: top .. index:: pair: MapScript; PHP Introduction ------------ This is a PHP module to make MapServer's MapScript functionalities available in a PHP Dynamically Loadable Library. Versions Supported ------------------ PHP MapScript was originally developed for PHP-3.0.14 but after MapServer 3.5 support for PHP3 has been dropped and as of the last update of this document, PHP 4.1.2 or more recent was required. The module has been tested and used on Linux, Solaris, \*BSD, and WinNT. How to Get More Information on PHP MapScript -------------------------------------------- - For installation questions regarding the PHP MapScript module, see :ref:`php_install`. - The `MapServer Wiki`_ has information on this module, that was contributed by users. - New PHP MapScript users should read the :ref:`php_example` document. - The project's home is the `PHP/MapScript page`_ on MapTools.org. - Also, see the :ref:`mapscript`, and the :ref:`mapfile` sections of this site. - Refer to the main `PHP site`_ for their official documentation. .. _`MapServer Wiki`: http://trac.osgeo.org/mapserver/wiki/PHPMapScript .. _`PHP/MapScript page`: http://www.maptools.org/php_mapscript/ .. _`PHP site`: http://www.php.net Important note -------------- - Constant names and class member variable names are case-sensitive in PHP. - Several MapScript functions (all those that access files in the back end such as ms_newMapObj(), drawMap(), etc) will affect the value of the current working directory (CWD) in the PHP environment. This will be fixed eventually but in the meantime you should be careful about these side-effects. .. index:: pair: PHP; Constants Constants --------- The following MapServer constants are available: Boolean values MS_TRUE, MS_FALSE, MS_ON, MS_OFF, MS_YES, MS_NO Map units MS_INCHES, MS_FEET, MS_MILES, MS_METERS, MS_KILOMETERS, MS_DD, MS_PIXELS, MS_NAUTICALMILES Layer types MS_LAYER_POINT, MS_LAYER_LINE, MS_LAYER_POLYGON, MS_LAYER_RASTER, MS_LAYER_ANNOTATION, MS_LAYER_QUERY, MS_LAYER_CIRCLE, MS_LAYER_TILEINDEX, MS_LAYER_CHART Layer/Legend/Scalebar/Class Status MS_ON, MS_OFF, MS_DEFAULT, MS_EMBED, MS_DELETE Layer alpha transparency allows alpha transparent pixmaps to be used with RGB map images MS_GD_ALPHA Font types MS_TRUETYPE, MS_BITMAP Label positions MS_UL, MS_LR, MS_UR, MS_LL, MS_CR, MS_CL, MS_UC, MS_LC, MS_CC, MS_AUTO, MS_XY, MS_FOLLOW Bitmap font styles MS_TINY , MS_SMALL, MS_MEDIUM, MS_LARGE, MS_GIANT Shape types MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON, MS_SHAPE_NULL Shapefile types MS_SHP_POINT, MS_SHP_ARC, MS_SHP_POLYGON, MS_SHP_MULTIPOINT Query/join types MS_SINGLE, MS_MULTIPLE Querymap styles MS_NORMAL, MS_HILITE, MS_SELECTED Connection Types MS_INLINE, MS_SHAPEFILE, MS_TILED_SHAPEFILE, MS_SDE, MS_OGR, MS_TILED_OGR, MS_POSTGIS, MS_WMS, MS_ORACLESPATIAL, MS_WFS, MS_GRATICULE, MS_MYGIS, MS_RASTER, MS_PLUGIN Error codes MS_NOERR, MS_IOERR, MS_MEMERR, MS_TYPEERR, MS_SYMERR, MS_REGEXERR, MS_TTFERR, MS_DBFERR, MS_GDERR, MS_IDENTERR, MS_EOFERR, MS_PROJERR, MS_MISCERR, MS_CGIERR, MS_WEBERR, MS_IMGERR, MS_HASHERR, MS_JOINERR, MS_NOTFOUND, MS_SHPERR, MS_PARSEERR, MS_SDEERR, MS_OGRERR, MS_QUERYERR, MS_WMSERR, MS_WMSCONNERR, MS_ORACLESPATIALERR, MS_WFSERR, MS_WFSCONNERR, MS_MAPCONTEXTERR, MS_HTTPERR, MS_WCSERR Symbol types MS_SYMBOL_SIMPLE, MS_SYMBOL_VECTOR, MS_SYMBOL_ELLIPSE, MS_SYMBOL_PIXMAP, MS_SYMBOL_TRUETYPE, MS_SYMBOL_CARTOLINE Image Mode types (:ref:`outputFormatObj `) MS_IMAGEMODE_PC256, MS_IMAGEMODE_RGB, MS_IMAGEMODE_RGBA, MS_IMAGEMODE_INT16, MS_IMAGEMODE_FLOAT32, MS_IMAGEMODE_BYTE, MS_IMAGEMODE_NULL Style/Attribue binding MS_STYLE_BINDING_SIZE, MS_STYLE_BINDING_ANGLE, MS_STYLE_BINDING_COLOR, MS_STYLE_BINDING_OUTLINECOLOR, MS_STYLE_BINDING_SYMBOL Label/Attribute binding MS_LABEL_BINDING_SIZE, MS_LABEL_BINDING_ANGLE, MS_LABEL_BINDING_COLOR, MS_LABEL_BINDING_OUTLINECOLOR, MS_LABEL_BINDING_FONT, MS_LABEL_BINDING_PRIORITY Alignment MS_ALIGN_LEFT, MS_ALIGN_CENTER, MS_ALIGN_RIGHT OwsRequest MS_GET_REQUEST, MS_POST_REQUEST Functions ---------- string ms_GetVersion() Returns the MapServer version and options in a string. This string can be parsed to find out which modules were compiled in, etc. int ms_GetVersionInt() Returns the MapServer version number (x.y.z) as an integer (x*10000 + y*100 + z). (New in v5.0) e.g. V5.4.3 would return 50403. array ms_TokenizeMap(string map_file_name) Preparses a mapfile through the MapServer parser and return an array with one item for each token from the mapfile. Strings, logical expressions, regex expressions and comments are returned as individual tokens. void ms_ioinstallstdouttobuffer() Installs a mapserver IO handler directing future stdout output to a memory buffer. void ms_ioinstallstdinfrombuffer() Installs a mapserver IO handler directing future stdin reading (ie. post request capture) to come from a buffer. void ms_iogetstdoutbufferstring() Fetch the current stdout buffer contents as a string. This method does not clear the buffer. int ms_iogetStdoutBufferBytes() Writes the current buffer to stdout. The PHP header() function should be used to set the documents's content-type prior to calling the function. Returns the number of bytes written if output is sent to stdout. See :ref:`mapscript_ows` for more info. void ms_ioresethandlers() Resets the default stdin and stdout handlers in place of "buffer" based handlers. void ms_iostripstdoutbuffercontenttype() Strip the Content-type header off the stdout buffer if it has one, and if a content type is found it is return. Otherwise return false. Classes ------- The following class objects are available through PHP MapScript. classObj ^^^^^^^^ Constructor ............................................................................... Class Objects can be returned by the `layerObj`_ class, or can be created using: .. code-block:: php classObj ms_newClassObj(layerObj layer [, classObj class]) The second argument class is optional. If given, the new class created will be a copy of this class. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== string name string title int type int status (MS_ON, MS_OFF or MS_DELETE) double minscaledenom double maxscaledenom double minscale (Deprecated in v5.0, use minscaledenom instead) double maxscale (Deprecated in v5.0, use maxscaledenom instead) string template labelObj label int numstyles string keyimage string group hashTableObj metadata =============== ==================================================================== Methods ............................................................................... int updateFromString(string snippet) Update a class from a string snippet. Returns MS_SUCCESS/MS_FAILURE. .. code-block:: php $oClass->updateFromString('CLASS STYLE COLOR 255 0 255 END END'); /*set the color */ int set(string property_name, new_value) Set object property to a new value. Returns -1 on error. int setExpression(string expression) Set the :ref:`expression ` string for the class object. string getExpressionString() Returns the :ref:`expression ` string for the class object. string getExpression() Deprecated in v5.0. Use getExpressionString() instead. int settext(string text) Set the text string for the class object. string getTextString() Returns the text string for the class object. int drawLegendIcon(int width, int height, imageObj im, int dstX, int dstY) Draw the legend icon on im object at dstX, dstY. Returns MS_SUCCESS/MS_FAILURE. imageObj createLegendIcon(int width, int height) Draw the legend icon and return a new imageObj. styleObj getStyle(int index) Return the style object using an index. index >= 0 && index < class->numstyles. classObj clone() Returns a cloned copy of the class. int movestyleup(int index) The style specified by the style index will be moved up into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex class->movestyleup(1) will have the effect of moving style 1 up to position 0, and the style at position 0 will be moved to position 1. int movestyledown(int index) The style specified by the style index will be moved down into the array of classes. Returns MS_SUCCESS or MS_FAILURE. ex class->movestyledown(0) will have the effect of moving style 0 up to position 1, and the style at position 1 will be moved to position 0. int deletestyle(int index) Delete the style specified by the style index. If there are any style that follow the deleted style, their index will decrease by 1. .. note:: if you are using the numstyles parameter while using the deletestyle function on the class object you need to refetch a new class object. Example : .. code-block:: php //class has 2 styles $class = $oLayer->getclass(0); $class->deletestyle(1); echo $class->numstyles; : will echo 2 $class = $oLayer->getclass(0); echo $class->numstyles; : will echo 1 int getMetaData(string name) Fetch class metadata entry by name. Returns "" if no entry matches the name. Note that the search is case sensitive. .. note:: getMetaData's query is case sensitive. int setMetaData(string name, string value) Set a metadata entry for the class. Returns MS_SUCCESS/MS_FAILURE. int removeMetaData(string name) Remove a metadata entry for the class. Returns MS_SUCCESS/MS_FAILURE. colorObj ^^^^^^^^ Constructor ............................................................................... Instances of colorObj are always embedded inside other classes. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== int red int green int blue =============== ==================================================================== Methods ............................................................................... void setRGB(int red, int green, int blue) Set red, green, blue values. errorObj ^^^^^^^^ Instances of errorObj are created internally by MapServer as errors happen. Errors are managed as a chained list with the first item being the most recent error. The head of the list can be fetched using ms_GetErrorObj(), and the list can be cleared using ms_ResetErrorList() Functions ............................................................................... errorObj ms_GetErrorObj() Returns a reference to the head of the list of errorObj. void ms_ResetErrorList() Clear the current error list. Note that clearing the list invalidates any errorObj handles obtained via the $error->next() method. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== int code //See error code constants above string routine string message =============== ==================================================================== Method ............................................................................... errorObj next() Returns the next errorObj in the list, or NULL if we reached the end of the list. Example: This example draws a map and reports all errors generated during the draw() call, errors can potentially come from multiple layers. .. code-block:: php ms_ResetErrorList(); $img = $map->draw(); $error = ms_GetErrorObj(); while($error && $error->code != MS_NOERR) { printf("Error in %s: %s
\n", $error->routine, $error->message); $error = $error->next(); } gridObj ^^^^^^^ Constructor ............................................................................... The grid is always embedded inside a layer object defined as a grid (layer->connectiontype = MS_GRATICULE) (for more docs : http://trac.osgeo.org/mapserver/wiki/MapServerGrid) A layer can become a grid layer by adding a grid object to it using : ms_newGridObj(layerObj layer) .. code-block:: php $oLayer = ms_newlayerobj($oMap); $oLayer->set("name", "GRID"); ms_newgridobj($oLayer); $oLayer->grid->set("labelformat", "DDMMSS"); Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== double minsubdivide double maxsubdivide double minarcs double maxacrs double mininterval double maxinterval string labelformat =============== ==================================================================== Methods ............................................................................... int set(string property_name, new_value) Set object property to a new value. hashTableObj ^^^^^^^^^^^^ Constructor ............................................................................... Instance of hashTableObj is always embedded inside the `classObj`_, `layerObj`_, and `webObj`_. It is uses a read only. .. code-block:: php $hashTable = $oLayer->metadata; $key = null; while ($key = $hashTable->nextkey($key)) echo "Key: ".$key." value: ".$hashTable->get($key)."
"; Methods ............................................................................... string get(string key) Fetch class metadata entry by name. Returns "" if no entry matches the name. Note that the search is case sensitive. int set(string key, string value) Set a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE. int remove(string key) Remove a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE. void clear() Clear all items in the hashTable (To NULL). string nextkey(string previousKey) Return the next key or first key if previousKey = NULL. Return NULL if no item is in the hashTable or end of hashTable is reached imageObj ^^^^^^^^ Constructor ............................................................................... Instances of imageObj are always created by the `mapObj`_ class methods. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== int width (read-only) int height (read-only) string imagepath string imageurl =============== ==================================================================== Methods ............................................................................... void free() Destroys resources used by an image object. int saveImage(string filename, MapObj oMap) Writes image object to specified filename. Passing an empty filename sends output to stdout. In this case, the PHP header() function should be used to set the document's content-type prior to calling saveImage(). The output format is the one that is currently selected in the map file. The second argument oMap is not manadatory. It is usful when saving to formats like GTIFF that needs georeference informations contained in the map file. The function returns -1 on error. On success, it returns either 0 if writing to an external file, or the number of bytes written if output is sent to stdout. string saveWebImage() Writes image to temp directory. Returns image URL. The output format is the one that is currently selected in the map file. void pasteImage(imageObj srcImg, int transparentColorHex [[, int dstX, int dstY], int angle]) Copy srcImg on top of the current imageObj. transparentColorHex is the color (in 0xrrggbb format) from srcImg that should be considered transparent (i.e. those pixels won't be copied). Pass -1 if you don't want any transparent color. If optional dstx,dsty are provided then it defines the position where the image should be copied (dstx,dsty = top-left corner position). The optional angle is a value between 0 and 360 degrees to rotate the source image counterclockwise. Note that if an angle is specified (even if its value is zero) then the dstx and dsty coordinates specify the CENTER of the destination area. Note: this function works only with 8 bits GD images (PNG or GIF). labelcacheMemberObj ^^^^^^^^^^^^^^^^^^^ Accessible only through the `mapObj`_ (map->getLabel()). Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== int classindex (Read-Only) int featuresize (Read-Only) int layerindex (Read-Only) int numstyles (Read-Only) int shapeindex (Read-Only) int status (Read-Only) string text (Read-Only) int tileindex (Read-Only) =============== ==================================================================== Method ............................................................................... None labelcacheObj ^^^^^^^^^^^^^ Accessible only through the `mapObj`_ (map->labelcache). This object is only used to give the possiblity to free the label cache (map->labelcache->free()) Method ............................................................................... boolean free() Free the label cache. Returns true on success or false if an error occurs. Ex : (map->labelcache->free(); labelObj ^^^^^^^^ Constructor ............................................................................... labelObj are always embedded inside other classes. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== string font int type colorObj color colorObj outlinecolor int outlinewidth colorObj shadowcolor int shadowsizex int shadowsizey colorObj backgroundcolor colorObj backgroundshadowcolor int backgroundshadowsizex int backgroundshadowsizey int size int minsize int maxsize int position int offsetx int offsety double angle int autoangle int autofollow int buffer int antialias int wrap int minfeaturesize int autominfeaturesize int mindistance int repeatdistance int partials int force string encoding int align int maxlength int minlength int priority =============== ==================================================================== Methods ............................................................................... int updateFromString(string snippet) Update a label from a string snippet. Returns MS_SUCCESS/MS_FAILURE. int set(string property_name, new_value) Set object property to a new value. Returns -1 on error. int setBinding(const labelbinding, string value) Set the attribute binding for a specified label property. Returns true on success. Example: .. code-block:: php $oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR"); This would bind the color parameter with the data (ie will extract the value of the color from the field called "FIELD_NAME_COLOR" string getBinding(const labelbinding) Get the attribute binding for a specified label property. Returns null if there is no binding for this property. Example: .. code-block:: php $oLabel->setbinding(MS_LABEL_BINDING_COLOR, "FIELD_NAME_COLOR"); echo $oLabel->getbinding(MS_LABEL_BINDING_COLOR); // FIELD_NAME_COLOR int removeBinding(const labelbinding) Remove the attribute binding for a specfiled style property. Returns true on success. Example: .. code-block:: php $oStyle->removebinding(MS_LABEL_BINDING_COLOR); layerObj ^^^^^^^^ Constructor ............................................................................... Layer Objects can be returned by the `mapObj`_ class, or can be created using: .. code-block:: php layerObj ms_newLayerObj(MapObj map [, layerObj layer]) A second optional argument can be given to ms_newLayerObj() to create the new layer as a copy of an existing layer. If a layer is given as argument then all members of a this layer will be copied in the new layer created. Members ............................................................................... =============== ==================================================================== Type Name =============== ==================================================================== int numclasses (read-only) int index (read-only) int status (MS_ON, MS_OFF, MS_DEFAULT or MS_DELETE) int debug string classitem string classgroup string name string group string data int type int dump double tolerance int toleranceunits int sizeunits double symbolscaledenom double minscaledenom double maxscaledenom double labelminscaledenom double labelmaxscaledenom double symbolscale (Deprecated in v5.0, use symbolscaledenom instead) double minscale (Deprecated in v5.0, use minscaledenom instead) double maxscale (Deprecated in v5.0, use maxscaledenom instead) double labelminscale (Deprecated in v5.0, use labelminscaledenom instead) double labelmaxscale (Deprecated in v5.0, use labelmaxscaledenom instead) int maxfeatures colorObj offsite int annotate int transform int labelcache int postlabelcache string labelitem string labelsizeitem string labelangleitem string tileitem string tileindex string header string footer string connection int connectiontype (read-only, use setConnectionType() to set it) string filteritem string template int opacity int transparency (Deprecated in v5.0. Use opacity instead.) string styleitem gridObj grid //only available on a layer defined as grid (MS_GRATICULE) int num_processing string requires string labelrequires hashTableObj metadata projectionObj projection =============== ==================================================================== Methods ............................................................................... int updateFromString(string snippet) Update a layer from a string snippet. Returns MS_SUCCESS/MS_FAILURE. .. code-block:: php $oLayer->updateFromString('LAYER NAME land_fn2 END'); /*modify the name */ $oLayer->updateFromString('LAYER CLASS STYLE COLOR 255 255 0 END END END'); /*add a new class*/ int set(string property_name, new_value) Set object property to a new value. Returns -1 on error. int draw(imageObj image) Draw a single layer, add labels to cache if required. Returns -1 on error. int drawQuery(imageObj image) Draw query map for a single layer. classObj getClass(int classIndex) Returns a classObj from the layer given an index value (0=first class) int queryByPoint(pointObj point, int mode, double buffer) Query layer at point location specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Mode is MS_SINGLE or MS_MULTIPLE depending on number of results you want. Passing buffer -1 defaults to tolerances set in the map file (in pixels) but you can use a constant buffer (specified in ground units) instead. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the '@' control operator). int queryByRect(rectObj rect) Query layer using a rectangle specified in georeferenced map coordinates (i.e. not pixels). The query is performed on all the shapes that are part of a CLASS that contains a TEMPLATE value or that match any class in a layer that contains a LAYER TEMPLATE value. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the '@' control operator). int queryByShape(shapeObj shape) Query layer based on a single shape, the shape has to be a polygon at this point. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the '@' control operator). int queryByFeatures(int slayer) Perform a query set based on a previous set of results from another layer. At present the results MUST be based on a polygon layer. Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing was found or if some other error happened (note that the error message in case nothing was found can be avoided in PHP using the '@' control operator). int queryByAttributes(string qitem, string qstring, int mode) Query layer for shapes that intersect current map extents. qitem is the item (attribute) on which the query is performed, and qstring is the expression to match. The query is performed on all the shapes that are part of a :ref:`CLASS` that contains a :ref:`TEMPLATE