.. _phpmapscriptapi:

*****************************************************************************
 PHP MapScript API
*****************************************************************************

:Author: Daniel Morissette
:Contact: dmorissette at mapgears.com
:Author: Yewondwossen Assefa
:Contact: yassefa at dmsolutions.ca
:Author: Alan Boudreault
:Contact: aboudreault at mapgears.com
:Author: Jeff McKenna
:Contact: jmckenna at gatewaygeomatics.com

 .. note::
   If you are using MapServer 5.6 and older, please refer 
   to the :ref:`PHP MapScript 5.6 documentation <php5.6>` instead.
   
 .. tip::

    PHP 7 native support is included as of the MapServer 7.4.0 release.
    Also, as of the 7.4.0 release PHP 7 is available through
    MapServer's :ref:`SWIG <swig>` API.
 
.. contents::
   :depth: 3
   :backlinks: top

Important Note
--------------

- Constant names and class member variable names are case-sensitive in
  PHP.

.. index::
   triple: MapScript; 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 (deprecated since 6.2), 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

Label positions
    MS_UL, MS_LR, MS_UR, MS_LL, MS_CR, MS_CL, MS_UC, MS_LC,
    MS_CC, MS_XY, MS_AUTO, MS_AUTO2, MS_FOLLOW, MS_NONE

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_RASTER, MS_PLUGIN, MS_UNION

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

Image Mode types (:ref:`outputFormatObj <outputformat>`)
    MS_IMAGEMODE_PC256, MS_IMAGEMODE_RGB, MS_IMAGEMODE_RGBA, 
    MS_IMAGEMODE_INT16, MS_IMAGEMODE_FLOAT32, MS_IMAGEMODE_BYTE, 
    MS_IMAGEMODE_FEATURE, 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, MS_STYLE_BINDING_WIDTH

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,
    MS_LABEL_BINDING_POSITION, MS_LABEL_BINDING_SHADOWSIZEX,
    MS_LABEL_BINDING_SHADOWSIZEY

Alignment
    MS_ALIGN_LEFT, MS_ALIGN_CENTER, MS_ALIGN_RIGHT

OwsRequest
    MS_GET_REQUEST, MS_POST_REQUEST
     
.. index::
   triple: MapScript; PHP; Functions

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.

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_iogetstdoutbufferstring()
    Fetch the current stdout buffer contents as a string.  This method 
    does not clear the buffer.

void ms_ioinstallstdinfrombuffer()
    Installs a mapserver IO handler directing future stdin reading 
    (ie. post request capture) to come from a buffer. 

void ms_ioinstallstdouttobuffer()
    Installs a mapserver IO handler directing future stdout output 
    to a memory buffer. 

void ms_ioresethandlers()   
    Resets the default stdin and stdout handlers in place of "buffer"
    based handlers.
 
string 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.

void ms_iostripstdoutbuffercontentheaders()
    Strip all the Content-* headers off the stdout buffer if it has
    some.

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.

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.

.. index::
   triple: MapScript; PHP; Classes

Classes
-------

The following class objects are available through PHP MapScript.

.. index::
   triple: MapScript; PHP; classObj

classObj
^^^^^^^^

Constructor
...............................................................................

Class Objects can be returned by the `layerObj`_ class, or can be
created using:

.. code-block:: php

   new classObj(layerObj layer [, classObj class])

or using the old constructor

.. 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         Note
=============== ================ ===============================================
string          group
string          keyimage   
labelObj        label            Removed (6.2) - use addLabel, getLabel, ...
double          maxscaledenom
hashTableObj    metadata
double          minscaledenom
string          name
int             numlabels        read-only (since 6.2)
int             numstyles        read-only
int             status           MS_ON, MS_OFF or MS_DELETE
string          template
string          title
int             type
=============== ================ ===============================================

Methods
...............................................................................

int addLabel( labelObj label)
    Add a labelObj to the classObj and return its index in the labels
    array.

    .. versionadded:: 6.2

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

imageObj createLegendIcon(int width, int height)
    Draw the legend icon and return a new imageObj.
 
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.

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.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

string getExpressionString()
    Returns the :ref:`expression <expressions>` string for the class
    object.
        
labelObj getLabel(int index)
    Return a reference to the labelObj at *index* in the labels array.

    See the labelObj_ section for more details on multiple class
    labels.

    .. versionadded:: 6.2

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.
    
styleObj getStyle(int index)
    Return the style object using an index. index >= 0 &&
    index < class->numstyles.

string getTextString()
    Returns the text string for the class object.
        
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 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.

labelObj removeLabel(int index)
    Remove the labelObj at *index* from the labels array and return a
    reference to the labelObj.  numlabels is decremented, and the
    array is updated.

    .. versionadded:: 6.2

int removeMetaData(string name)
    Remove a metadata entry for the class.  Returns MS_SUCCESS/MS_FAILURE.

int set(string property_name, new_value)
    Set object property to a new value.

int setExpression(string expression)
    Set the :ref:`expression <expressions>` string for the class
    object.

int setMetaData(string name, string value)
    Set a metadata entry for the class.  Returns MS_SUCCESS/MS_FAILURE.

int settext(string text)
    Set the text string for the class object.

int updateFromString(string snippet)
    Update a class from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

    .. code-block:: php

      /*set the color */
      $oClass->updateFromString('CLASS STYLE COLOR 255 0 255 END END');

.. index::
   triple: MapScript; PHP; clusterObj

clusterObj
^^^^^^^^^^^^

Constructor
...............................................................................

Instance of clusterObj is always embedded inside the `layerObj`_.

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
double          buffer
double          maxdistance
string          region
=============== ================================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

string getFilterString()
    Returns the :ref:`expression <expressions>` for this cluster
    filter or NULL on error.

string getGroupString()
    Returns the :ref:`expression <expressions>` for this cluster group
    or NULL on error.

int setFilter(string expression)
    Set layer filter :ref:`expression <expressions>`.

int setGroup(string expression)
    Set layer group :ref:`expression <expressions>`.

.. index::
   triple: MapScript; PHP; colorObj

colorObj
^^^^^^^^

Constructor
...............................................................................

Instances of colorObj are always embedded inside other classes.

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
int             red
int             green
int             blue
int             alpha
=============== ================================================================

Methods
...............................................................................

int setRGB(int red, int green, int blue, int alpha = 255)
    Set red, green, blue and alpha values. Returns MS_SUCCESS.

string toHex()
    Get the color as a hex string "#rrggbb" or (if alpha is not 255)
    "#rrggbbaa".

int setHex(string hex)
    Set red, green, blue and alpha values. The hex string should have the form
    "#rrggbb" (alpha will be set to 255) or "#rrggbbaa". Returns MS_SUCCESS.

    
.. index::
   triple: MapScript; PHP; errorObj

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()

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
int             code      //See error code constants above
string          message
string          routine
=============== ================================================================

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<br>\n", $error->routine, $error->message);
     $error = $error->next();
   }

.. index::
   triple: MapScript; PHP; gridObj

gridObj
^^^^^^^

Constructor
...............................................................................

The grid is always embedded inside a layer object defined as
a grid (layer->connectiontype = MS_GRATICULE)
(for more docs : https://github.com/mapserver/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
=============== ================================================================
string          labelformat
double          maxacrs
double          maxinterval
double          maxsubdivide
double          minarcs
double          mininterval
double          minsubdivide
=============== ================================================================


Methods
...............................................................................

int set(string property_name, new_value)
    Set object property to a new value.
    
.. index::
   triple: MapScript; PHP; hashTableObj

hashTableObj
^^^^^^^^^^^^

Constructor
...............................................................................

Instance of hashTableObj is always embedded inside the `classObj`_,
`layerObj`_, `mapObj`_ 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)."<br/>";

Methods
...............................................................................

void clear()
    Clear all items in the hashTable (To NULL).

string get(string key)
    Fetch class metadata entry by name.  Returns "" if no entry 
    matches the name.  Note that the search is case sensitive.

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

int remove(string key)
    Remove a metadata entry in the hashTable.  Returns MS_SUCCESS/MS_FAILURE.

int set(string key, string value)
    Set a metadata entry in the hashTable. Returns MS_SUCCESS/MS_FAILURE.
     
.. index::
   triple: MapScript; PHP; imageObj

imageObj
^^^^^^^^

Constructor
...............................................................................

Instances of imageObj are always created by the `mapObj`_ class methods.

Members
...............................................................................

=============== =================== ============================================
Type                Name            Note
=============== =================== ============================================
int             width               read-only
int             height              read-only
int             resolution          read-only
int             resolutionfactor    read-only
string          imagepath
string          imageurl
=============== =================== ============================================

Methods
...............................................................................

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).

int saveImage([string filename, MapObj oMap])
    Writes image object to specified filename. 
    Passing no filename or 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 information contained in
    the map file. On success, it returns either MS_SUCCESS 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.
   

.. index::
   triple: MapScript; PHP; labelcacheMemberObj

labelcacheMemberObj
^^^^^^^^^^^^^^^^^^^

Accessible only through the `mapObj`_ (map->getLabel()).

Members
...............................................................................

=============== ============== =================================================
Type                Name       Note
=============== ============== =================================================
int             classindex     read-only
int             featuresize    read-only
int             layerindex     read-only
int             markerid       read-only
int             numstyles      read-only
int             shapeindex     read-only
int             status         read-only
string          text           read-only
int             tileindex      read-only
=============== ============== =================================================

Method
...............................................................................

None

.. index::
   triple: MapScript; PHP; labelcacheObj

labelcacheObj
^^^^^^^^^^^^^

Accessible only through the `mapObj`_ (map->labelcache). This object
is only used to give the possibility to free the label cache 
(map->labelcache->freeCache())


Methods
...............................................................................

boolean freeCache()
    Free the label cache. Always returns MS_SUCCESS.
    Ex : map->labelcache->freeCache();

.. index::
   triple: MapScript; PHP; labelObj

labelObj
^^^^^^^^

Constructor
...............................................................................

labelObj are always embedded inside other classes.

.. code-block:: php

    new labelObj()

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
int             align
double          angle
int             anglemode
int             antialias
int             autominfeaturesize
colorObj        backgroundcolor (deprecated since 6.0)
colorObj        backgroundshadowcolor (deprecated since 6.0)
int             backgroundshadowsizex (deprecated since 6.0)
int             backgroundshadowsizey (deprecated since 6.0)
int             buffer
colorObj        color
string          encoding
string          font
int             force
int             maxlength
int             maxsize
int             mindistance
int             minfeaturesize
int             minlength
int             minsize
int             numstyles
int             offsetx
int             offsety
colorObj        outlinecolor
int             outlinewidth
int             partials
int             position
int             priority
int             repeatdistance
colorObj        shadowcolor
int             shadowsizex
int             shadowsizey
int             size
int             wrap
=============== ================================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

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.

void free()
    Free the object properties and break the internal references. 
    Note that you have to unset the php variable to free totally the
    resources.

string getBinding(mixed 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

string getExpressionString()
    Returns the label expression string. 

styleObj getStyle(int index)
    Return the style object using an index. index >= 0 &&
    index < label->numstyles.

string getTextString()
    Returns the label text string.

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 label->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 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 label->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 removeBinding(mixed labelbinding)
    Remove the attribute binding for a specfiled style property.  
    
    Example:
    
    .. code-block:: php
    
        $oStyle->removebinding(MS_LABEL_BINDING_COLOR);

int set(string property_name, new_value)
    Set object property to a new value.

int setBinding(mixed labelbinding, string value)
    Set the attribute binding for a specified label property.

    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"

int setExpression( string expression )
    Set the label expression.

int setText( string text )
    Set the label text.

int updateFromString(string snippet)
    Update a label from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; layerObj

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            Note
=============== =================== ============================================
int             annotate
hashTableObj    bindvals
string          classgroup
string          classitem
clusterObj      cluster
string          connection
int             connectiontype      read-only, use setConnectionType() to set it
string          data
int             debug
int             dump                deprecated since 6.0
string          filteritem
string          footer
gridObj         grid                only available on a layer defined as grid (MS_GRATICULE)
string          group
string          header
int             index               read-only
int             labelcache
string          labelitem
double          labelmaxscaledenom
double          labelminscaledenom
string          labelrequires
string          mask
int             maxfeatures
double          maxscaledenom
hashTableObj    metadata
double          minscaledenom
string          name
int             num_processing
int             numclasses          read-only
colorObj        offsite
int             opacity
projectionObj   projection
int             postlabelcache
string          requires
int             sizeunits
int             startindex
int             status              MS_ON, MS_OFF, MS_DEFAULT or MS_DELETE
string          styleitem
double          symbolscaledenom
string          template
string          tileindex
string          tileitem
double          tolerance
int             toleranceunits
int             transform
int             type
=============== =================== ============================================


Methods
...............................................................................

int addFeature(shapeObj shape)
    Add a new feature in a layer. Returns MS_SUCCESS or MS_FAILURE on
    error.

int applySLD(string sldxml, string namedlayer)
    Apply the :ref:`SLD <sld>` document to the layer object. 
    The matching between the sld document and the layer will be done 
    using the layer's name.
    If a namedlayer argument is passed (argument is optional), 
    the NamedLayer in the sld that matchs it will be used to style 
    the layer.
    See :ref:`SLD HowTo <sld>` for more information on the SLD support.

int applySLDURL(string sldurl, string namedlayer)
    Apply the :ref:`SLD <sld>` document pointed by the URL to the
    layer object. The matching between the sld document and the layer
    will be done using the layer's name.  If a namedlayer argument is
    passed (argument is optional), the NamedLayer in the sld that
    matchs it will be used to style the layer.  See :ref:`SLD HowTo
    <sld>` for more information on the SLD support.

void clearProcessing()
    Clears all the processing strings.

void close()
    Close layer previously opened with open().

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

int draw(imageObj image)
    Draw a single layer, add labels to cache if required. 
    Returns MS_SUCCESS or MS_FAILURE on error.

int drawQuery(imageObj image)
    Draw query map for a single layer.

string   executeWFSGetfeature()
    Executes a GetFeature request on a WFS layer and returns the
    name of the temporary GML file created. Returns an empty
    string on error.

void free()
    Free the object properties and break the internal references. 
    Note that you have to unset the php variable to free totally the
    resources.

string generateSLD()
    Returns an SLD XML string based on all the classes found in the
    layer (the layer must have `STATUS` `on`).

classObj getClass(int classIndex)
    Returns a classObj from the layer given an index value (0=first class)

int getClassIndex(shape [, classgroup,  numclasses])
    Get the class index of a shape for a given scale. Returns -1 if no
    class matches. classgroup is an array of class ids to check
    (Optional). numclasses is the number of classes that the classgroup
    array contains. By default, all the layer classes will be checked.

rectObj getExtent()
    Returns the layer's data extents or NULL on error.
    If the layer's EXTENT member is set then this value is used, 
    otherwise this call opens/closes the layer to read the 
    extents. This is quick on shapefiles, but can be
    an expensive operation on some file formats or data sources.
    This function is safe to use on both opened or closed layers: it
    is not necessary to call open()/close() before/after calling it.

string getFilterString()
    Returns the :ref:`expression <expressions>` for this layer or NULL
    on error.

array getGridIntersectionCoordinates()
    Returns an array containing the grid intersection coordinates. If
    there are no coordinates, it returns an empty array.

array getItems()
    Returns an array containing the items. Must call open function first.
    If there are no items, it returns an empty array.

int getMetaData(string name)
    Fetch layer 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 getNumResults()
    Returns the number of results in the last query.

array getProcessing()
    Returns an array containing the processing strings.
    If there are no processing strings, it returns an empty array.

string getProjection()
    Returns a string representation of the :ref:`projection <projection>`. 
    Returns NULL on error or if no projection is set.

resultObj getResult(int index)
    Returns a resultObj by index from a layer object with 
    index in the range 0 to numresults-1.  
    Returns a valid object or FALSE(0) if index is invalid.

rectObj getResultsBounds()
    Returns the bounding box of the latest result.

shapeObj getShape(resultObj result])
    If the resultObj passed has a valid resultindex, retrieve shapeObj from
    a layer's resultset. (You get it from the resultObj returned by
    getResult() for instance). Otherwise, it will do a single query on
    the layer to fetch the shapeindex

    .. code-block:: php

      $map = new mapObj("gmap75.map");
      $l = $map->getLayerByName("popplace");
      $l->queryByRect($map->extent);
      for ($i=0; $i<$l->getNumResults();$i++){
        $s = $l->getShape($l->getResult($i));
        echo $s->getValue($l,"Name");
        echo "\n";
      }

string getWMSFeatureInfoURL(int clickX, int clickY, int featureCount, string infoFormat)
    Returns a WMS GetFeatureInfo URL (works only for WMS layers)
    clickX, clickY is the location of to query in pixel coordinates
    with (0,0) at the top left of the image.
    featureCount is the number of results to return.
    infoFormat is the format the format in which the result should be
    requested.  Depends on remote server's capabilities.  MapServer
    WMS servers support only "MIME" (and should support "GML.1" soon).
    Returns "" and outputs a warning if layer is not a WMS layer 
    or if it is not queriable.
    
boolean isVisible()
    Returns MS_TRUE/MS_FALSE depending on whether the layer is 
    currently visible in the map (i.e. turned on, in scale, etc.). 

int moveclassdown(int index)
    The class specified by the class index will be moved down into
    the array of layers. Returns MS_SUCCESS or MS_FAILURE.
    ex layer->moveclassdown(0) will have the effect of moving class 0
    up to position 1, and the class at position 1 will be moved
    to position 0.

int moveclassup(int index)
    The class specified by the class index will be moved up into
    the array of layers. Returns MS_SUCCESS or MS_FAILURE.
    ex layer->moveclassup(1) will have the effect of moving class 1
    up to position 0, and the class at position 0 will be moved
    to position 1.

int open()
    Open the layer for use with getShape().  
    Returns MS_SUCCESS/MS_FAILURE.

shapeObj nextShape()
    Called after msWhichShapes has been called to actually retrieve
    shapes within a given area. Returns a shape object or NULL on
    error.

    .. code-block:: php

      $map = ms_newmapobj("d:/msapps/gmap-ms40/htdocs/gmap75.map");
      $layer = $map->getLayerByName('road');
      $status = $layer->open();
      $status = $layer->whichShapes($map->extent);
      while ($shape = $layer->nextShape())
      {
        echo $shape->index ."<br>\n";
      }
      $layer->close();

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 <template>` value or that match any class in a
    layer that contains a :ref:`LAYER` :ref:`TEMPLATE <template>`
    value.  Note that the layer's FILTER/FILTERITEM are ignored by
    this function.  Mode is MS_SINGLE or MS_MULTIPLE depending on
    number of results you want.  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 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).

classObj removeClass(int index)
    Removes the class indicated and returns a copy, or NULL in the case
    of a failure.  Note that subsequent classes will be renumbered by
    this operation. The numclasses field contains the number of classes
    available.

int removeMetaData(string name)
    Remove a metadata entry for the layer.  Returns MS_SUCCESS/MS_FAILURE.

int set(string property_name, new_value)
    Set object property to a new value.

int setConnectionType(int connectiontype [,string plugin_library])
    Changes the connectiontype of the layer and recreates the vtable
    according to the new connection type. This method should be used
    instead of setting the connectiontype parameter directly.
    In the case when the layer.connectiontype = MS_PLUGIN the plugin_library
    parameter should also be specified so as to select the library to
    load by MapServer. For the other connection types this parameter
    is not used.

int setFilter(string expression)
    Set layer filter :ref:`expression <expressions>`.

int setMetaData(string name, string value)
    Set a metadata entry for the layer.  Returns MS_SUCCESS/MS_FAILURE.

int setProcessing(string)
    Add the string to the processing string list for the layer.
    The layer->num_processing is incremented by 1.
    Returns MS_SUCCESS or MS_FAILURE on error.

    .. code-block:: php

      $oLayer->setprocessing("SCALE_1=AUTO");
      $oLayer->setprocessing("SCALE_2=AUTO");

int setProjection(string proj_params)
    Set layer :ref:`projection <projection>` and coordinate system.
    Parameters are given as a single string of comma-delimited PROJ.4
    parameters. Returns MS_SUCCESS or MS_FAILURE on error.

int setWKTProjection(string proj_params)
    Same as setProjection(), but takes an OGC WKT projection
    definition string as input.

    .. note::
      setWKTProjection requires GDAL support

int updateFromString(string snippet)
    Update a layer from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

    .. code-block:: php

      /*modify the name */
      $oLayer->updateFromString('LAYER NAME land_fn2 END');
      /*add a new class*/
      $oLayer->updateFromString('LAYER CLASS STYLE COLOR 255 255 0 END END END');

int whichshapes(rectobj)
    Performs a spatial, and optionally an attribute based feature
    search.  The function basically prepares things so that candidate
    features can be accessed by query or drawing functions (eg using
    nextshape function).  Returns MS_SUCCESS, MS_FAILURE or MS_DONE.
    MS_DONE is returned if the layer extent does not overlap the
    rectObj.

.. index::
   triple: MapScript; PHP; legendObj

legendObj
^^^^^^^^^

Constructor
...............................................................................

Instances of legendObj are always are always embedded inside the `mapObj`_.

Members
...............................................................................

=============== =============== ================================================
Type                Name        Note
=============== =============== ================================================
int             height
colorObj        imagecolor
int             keysizex
int             keysizey
int             keyspacingx
int             keyspacingy
labelObj        label
colorObj        outlinecolor    Color of outline of box, -1 for no outline
int             position        for embedded legends, MS_UL, MS_UC, ...
int             postlabelcache  MS_TRUE, MS_FALSE
int             status          MS_ON, MS_OFF, MS_EMBED
string          template
int             width
=============== =============== ================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

int set(string property_name, new_value)
    Set object property to a new value.

int updateFromString(string snippet)
    Update a legend from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; lineObj

lineObj
^^^^^^^

Constructor
...............................................................................

.. code-block:: php

    new lineObj()

or using the old constructor

.. code-block:: php

    LineObj ms_newLineObj()

Members
...............................................................................

=============== ============ ===================================================
Type                Name     Note
=============== ============ ===================================================
int             numpoints    read-only
=============== ============ ===================================================

Methods
...............................................................................

int add(pointObj point)
    Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE.

int addXY(double x, double y [, double m])
    Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE.

    .. note::
      the 3rd parameter m is used for measured shape files only.
      It is not mandatory.

int addXYZ(double x, double y, double z [, double m])
    Add a point to the end of line. Returns MS_SUCCESS/MS_FAILURE.

    .. note::
      the 4th parameter m is used for measured shape files only.
      It is not mandatory.

PointObj point(int i)
    Returns a reference to point number i.

int project(projectionObj in, projectionObj out)
    Project the line from "in" projection (1st argument) to "out"
    projection (2nd argument).  Returns MS_SUCCESS/MS_FAILURE.


.. index::
   triple: MapScript; PHP; mapObj

mapObj
^^^^^^

Constructor
...............................................................................

.. code-block:: php

    new mapObj(string map_file_name [, string new_map_path])

or using the old constructors

mapObj ms_newMapObj(string map_file_name [, string new_map_path])
    Returns a new object to deal with a MapServer map file.

mapObj ms_newMapObjFromString(string map_file_string [, string new_map_path])
    Construct a new mapObj from a mapfile string. Returns a new object to deal
    with a MapServer map file.

.. note::
    By default, the SYMBOLSET, FONTSET, and other paths in the mapfile
    are relative to the mapfile location.  If new_map_path is provided
    then this directory will be used as the base path for all the
    rewlative paths inside the mapfile.

Members
...............................................................................

=============== ================== =============================================
Type                Name           Note
=============== ================== =============================================
double          cellsize
int             debug
double          defresolution      pixels per inch, defaults to 72
rectObj         extent;
string          fontsetfilename    read-only, set by setFontSet()
int             height             see setSize()
colorObj        imagecolor
int             keysizex
int             keysizey
int             keyspacingx
int             keyspacingy
labelcacheObj   labelcache         no members. Used only to free the
                                   label cache (map->labelcache->free()
legendObj       legend
string          mappath
int             maxsize
hashTableObj    metadata
string          name
int             numlayers          read-only
outputformatObj outputformat
int             numoutputformats   read-only
projectionObj   projection
querymapObj     querymap
referenceMapObj reference
double          resolution         pixels per inch, defaults to 72
scalebarObj     scalebar
double          scaledenom         read-only, set by drawMap()
string          shapepath
int             status
string          symbolsetfilename  read-only, set by setSymbolSet()
int             units              map units type
webObj          web
int             width              see setSize()
=============== ================== =============================================

Methods
...............................................................................

int applyconfigoptions()
    Applies the config options set in the map file. For example
    setting the PROJ_LIB using the setconfigoption only modifies
    the value in the map object. applyconfigoptions will actually
    change the PROJ_LIB value that will be used when dealing with
    projection.

int applySLD(string sldxml)
    Apply the :ref:`SLD` document to the map file. The matching between the
    sld document and the map file will be done using the layer's name.
    See :ref:`SLD HowTo <sld>` for more information on the SLD support.

int applySLDURL(string sldurl)
    Apply the SLD document pointed by the URL to the map file. The
    matching between the sld document and the map file will be done
    using the layer's name.
    See :ref:`SLD HowTo <sld>` for more information on the SLD support.

string convertToString()
    Saves the object to a string.

    .. note::
      The inverse method updateFromString does not exist for the mapObj

    .. versionadded:: 6.4

imageObj draw()
    Render map and return an image object or NULL on error.

int drawLabelCache(imageObj image)
    Renders the labels for a map. Returns MS_SUCCESS or MS_FAILURE on error.

imageObj drawLegend()
    Render legend and return an image object.

imageObj drawQuery()
    Render a query map and return an image object or NULL on error.

imageObj drawReferenceMap()
    Render reference map and return an image object.

imageObj drawScaleBar()
    Render scale bar and return an image object.

int embedLegend(imageObj image)
    embeds a legend. Actually the legend is just added to the label
    cache so you must invoke drawLabelCache() to actually do the
    rendering (unless postlabelcache is set in which case it is
    drawn right away). Returns MS_SUCCESS or MS_FAILURE on error.

int embedScalebar(imageObj image)
    embeds a scalebar. Actually the scalebar is just added to the label
    cache so you must invoke drawLabelCache() to actually do the rendering
    (unless postlabelcache is set in which case it is drawn right away).
    Returns MS_SUCCESS or MS_FAILURE on error.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

void freeQuery(layerindex)
    Frees the query result on a specified layer. If the layerindex is -1,
    all queries on layers will be freed.

string generateSLD()
    Returns an SLD XML string based on all the classes found in all
    the layers that have `STATUS` `on`.

array getAllGroupNames()
    Return an array containing all the group names used in the
    layers. If there are no groups, it returns an empty array.

array getAllLayerNames()
    Return an array containing all the layer names.
    If there are no layers, it returns an empty array.

colorObj getColorbyIndex(int iCloIndex)
    Returns a colorObj corresponding to the color index in the
    palette.

string getConfigOption(string key)
    Returns the config value associated with the key.
    Returns an empty sting if key not found.

labelcacheMemberObj getLabel(int index)
    Returns a labelcacheMemberObj from the map given an index value
    (0=first label).  Labelcache has to be enabled.

    .. code-block:: php

      while ($oLabelCacheMember = $oMap->getLabel($i)) {
        /* do something with the labelcachemember */
        ++$i;
      }

layerObj getLayer(int index)
    Returns a layerObj from the map given an index value (0=first layer)

layerObj getLayerByName(string layer_name)
    Returns a layerObj from the map given a layer name.
    Returns NULL if layer doesn't exist.

array getLayersDrawingOrder()
    Return an array containing layer's index in the order which they
    are drawn. If there are no layers, it returns an empty array.

array getLayersIndexByGroup(string groupname)
    Return an array containing all the layer's indexes given
    a group name. If there are no layers, it returns an empty array.

int getMetaData(string name)
    Fetch metadata entry by name (stored in the :ref:`WEB` object in
    the map file).  Returns "" if no entry matches the name.

    .. note::
      getMetaData's query is case sensitive.

int getNumSymbols()
    Return the number of symbols in map.

string getProjection()
    Returns a string representation of the projection.
    Returns NULL on error or if no projection is set.

int getSymbolByName(string symbol_name)
    Returns the symbol index using the name.

symbolObj getSymbolObjectById(int symbolid)
    Returns the symbol object using a symbol id. Refer to
    the symbol object reference section for more details.

int insertLayer( layerObj layer [, int nIndex=-1 ] )
    Insert a copy of *layer* into the Map at index *nIndex*.  The
    default value of *nIndex* is -1, which means the last possible
    index.  Returns the index of the new Layer, or -1 in the case of a
    failure.

int loadMapContext(string filename [, boolean unique_layer_name])
    Available only if WMS support is enabled.  Load a :ref:`WMS Map
    Context <map_context>` XML file into the current mapObj.  If the
    map already contains some layers then the layers defined in the
    WMS Map context document are added to the current map.  The 2nd
    argument unique_layer_name is optional and if set to MS_TRUE
    layers created will have a unique name (unique prefix added to the
    name). If set to MS_FALSE the layer name will be the the same name
    as in the context. The default value is MS_FALSE.  Returns
    MS_SUCCESS/MS_FAILURE.

int loadOWSParameters(OwsrequestObj request, string version)
    Load OWS request parameters (BBOX, LAYERS, &c.) into map.  Returns
    MS_SUCCESS or MS_FAILURE.  2nd argument version is not mandatory.
    If not given, the version will be set to 1.1.1

int loadQuery(filename)
    Loads a query from a file. Returns MS_SUCCESS or MS_FAILURE.
    To be used with savequery.

int moveLayerDown(int layerindex)
    Move layer down in the hierarchy of drawing.
    Returns MS_SUCCESS or MS_FAILURE on error.

int moveLayerUp(int layerindex)
    Move layer up in the hierarchy of drawing.
    Returns MS_SUCCESS or MS_FAILURE on error.

int offsetExtent(double x, double y)
    Offset the map extent based on the given distances in map coordinates.
    Returns MS_SUCCESS or MS_FAILURE.

int owsDispatch(OwsrequestObj request)
    Processes and executes the passed OpenGIS Web Services request on
    the map.  Returns MS_DONE (2) if there is no valid OWS request in
    the req object, MS_SUCCESS (0) if an OWS request was successfully
    processed and MS_FAILURE (1) if an OWS request was not
    successfully processed.  OWS requests include :ref:`WMS
    <wms_server>`, :ref:`WFS <wfs_server>`, :ref:`WCS <wcs_server>`
    and :ref:`SOS <sos_server>` requests supported by MapServer.
    Results of a dispatched request are written to stdout and can be
    captured using the msIO services (ie. ms_ioinstallstdouttobuffer()
    and ms_iogetstdoutbufferstring())

imageObj prepareImage()
    Return a blank image object.

void prepareQuery()
    Calculate the scale of the map and set map->scaledenom.

string processLegendTemplate(array params)
    Process legend template files and return the result in a buffer.

    .. seealso::

      :ref:`processtemplate <processtemplate>`

string processQueryTemplate(array params, boolean generateimages)
    Process query template files and return the result in a buffer.
    Second argument generateimages is not mandatory. If not given
    it will be set to TRUE.

    .. seealso::

      :ref:`processtemplate <processtemplate>`

.. _processtemplate:

string processTemplate(array params, boolean generateimages)
    Process the template file specified in the web object and return the
    result in a buffer. The processing consists of opening the template
    file and replace all the tags found in it. Only tags that have an
    equivalent element in the map object are replaced (ex [scaledenom]).
    The are two exceptions to the previous statement :

    - [img], [scalebar], [ref], [legend] would be replaced with the
      appropriate url if the parameter generateimages is set to
      MS_TRUE. (Note :  the images corresponding to the different objects
      are generated if the object is set to MS_ON in the map file)
    - the user can use the params parameter to specify tags and
      their values. For example if the user have a specific tag call
      [my_tag] and would like it to be replaced by "value_of_my_tag"
      he would do

    .. code-block:: php

      $tmparray["my_tag"] = "value_of_my_tag";
      $map->processtemplate($tmparray, MS_FALSE);

int queryByFeatures(int slayer)
    Perform a query based on a previous set of results from
    a 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 queryByIndex(layerindex, tileindex, shapeindex[, addtoquery])
    Add a specific shape on a given layer to the query result.
    If addtoquery (which is a non mandatory argument) is set to MS_TRUE,
    the shape will be added to the existing query list. Default behavior
    is to free the existing query list and add only the new shape.

int queryByPoint(pointObj point, int mode, double buffer)
    Query all selected layers in map 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 :ref:`CLASS`
    that contains a :ref:`TEMPLATE` value or that match any class in a
    layer that contains a :ref:`LAYER` :ref:`TEMPLATE <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 all selected layers in map 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 :ref:`CLASS` that
    contains a :ref:`TEMPLATE` value or that match any class in a
    layer that contains a :ref:`LAYER` :ref:`TEMPLATE <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 all selected layers in map 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).

layerObj removeLayer( int nIndex )
    Remove a layer from the mapObj. The argument is the index of the
    layer to be removed. Returns the removed layerObj on success, else
    null.

int removeMetaData(string name)
    Remove a metadata entry for the map (stored in the WEB object in the map
    file).  Returns MS_SUCCESS/MS_FAILURE.

int save(string filename)
    Save current map object state to a file. Returns -1 on error.
    Use absolute path. If a relative path is used, then it will be
    relative to the mapfile location.

int saveMapContext(string filename)
    Available only if WMS support is enabled.  Save current map object
    state in :ref:`WMS Map Context <map_context>` format.  Only WMS
    layers are saved in the WMS Map Context XML file.  Returns
    MS_SUCCESS/MS_FAILURE.

int saveQuery(string filename[, int results])
    Save the current query in a file. Results determines the save format -
    MS_TRUE (or 1/true) saves the query results (tile index and shape index),
    MS_FALSE (or 0/false) the query parameters (and the query will be re-run
    in loadquery). Returns MS_SUCCESS or MS_FAILURE. Either save format can be
    used with loadquery. See RFC 65 and ticket #3647 for details of different
    save formats.

int scaleExtent(double zoomfactor, double minscaledenom, double maxscaledenom)
    Scale the map extent using the zoomfactor and ensure the extent
    within the minscaledenom and maxscaledenom domain.  If
    minscaledenom and/or maxscaledenom is 0 then the parameter is not
    taken into account.  Returns MS_SUCCESS or MS_FAILURE.

int selectOutputFormat(string type)
    Selects the output format to be used in the map.
    Returns MS_SUCCESS/MS_FAILURE.

    .. note::
      the type used should correspond to one of the output formats
      declared in the map file.  The type argument passed is compared
      with the mimetype parameter in the output format structure and
      then to the name parameter in the structure.

int appendOutputFormat(outputFormatObj outputFormat)
    Appends outputformat object in the map object.
    Returns the new numoutputformats value.

int removeOutputFormat(string name)
    Remove outputformat from the map.
    Returns MS_SUCCESS/MS_FAILURE.

outputFormatObj getOutputFormat(int index)
    Returns the outputformat at index position.

int set(string property_name, new_value)
    Set map object property to new value.

int setCenter(pointObj center)
    Set the map center to the given map point.
    Returns MS_SUCCESS or MS_FAILURE.

int setConfigOption(string key, string value)
    Sets a config parameter using the key and the value passed

void setExtent(double minx, double miny, double maxx, double maxy)
    Set the map extents using the georef extents passed in argument.
    Returns MS_SUCCESS or MS_FAILURE on error.

int setFontSet(string fileName)
    Load and set a new :ref:`fontset`.

boolean  setLayersDrawingOrder(array layeryindex)
    Set the layer's order array. The argument passed must be a valid
    array with all the layer's index.
    Returns MS_SUCCESS or MS_FAILURE on error.

int setMetaData(string name, string value)
    Set a metadata entry for the map (stored in the WEB object in the map
    file).  Returns MS_SUCCESS/MS_FAILURE.

int setProjection(string proj_params, boolean bSetUnitsAndExtents)
    Set map projection and coordinate system. Returns MS_SUCCESS or
    MS_FAILURE on error.

    Parameters are given as a single string of comma-delimited PROJ.4
    parameters.  The argument : bSetUnitsAndExtents is used to
    automatically update the map units and extents based on the new
    projection. Possible values are MS_TRUE and MS_FALSE. By default it is
    set at MS_FALSE.

int setRotation(double rotation_angle)
    Set map rotation angle. The map view rectangle (specified in
    EXTENTS) will be rotated by the indicated angle in the counter-
    clockwise direction. Note that this implies the rendered map
    will be rotated by the angle in the clockwise direction.
    Returns MS_SUCCESS or MS_FAILURE.

int setSize(int width, int height)
    Set the map width and height. This method updates the internal
    geotransform and other data structures required for map rotation
    so it should be used instead of setting the width and height members
    directly.
    Returns MS_SUCCESS or MS_FAILURE.

int setSymbolSet(string fileName)
    Load and set a symbol file dynamically.

int setWKTProjection(string proj_params, boolean bSetUnitsAndExtents)
    Same as setProjection(), but takes an OGC WKT projection
    definition string as input. Returns MS_SUCCESS or MS_FAILURE on error.

    .. note::
      setWKTProjection requires GDAL support

int zoomPoint(int nZoomFactor, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt)
    Zoom to a given XY position. Returns MS_SUCCESS or MS_FAILURE on error.

    Parameters are

    - Zoom factor : positive values do zoom in, negative values
      zoom out. Factor of 1 will recenter.
    - Pixel position (pointObj) : x, y coordinates of the click,
      with (0,0) at the top-left
    - Width : width in pixel of the current image.
    - Height : Height in pixel of the current image.
    - Georef extent (rectObj) : current georef extents.
    - MaxGeoref extent (rectObj) : (optional) maximum georef extents.
      If provided then it will be impossible to zoom/pan outside of
      those extents.

int zoomRectangle(rectObj oPixelExt, int nImageWidth, int nImageHeight, rectObj oGeorefExt)
    Set the map extents to a given extents. Returns MS_SUCCESS or
    MS_FAILURE on error.

    Parameters are :

    - oPixelExt (rect object) : Pixel Extents
    - Width : width in pixel of the current image.
    - Height : Height in pixel of the current image.
    - Georef extent (rectObj) : current georef extents.

int zoomScale(double nScaleDenom, pointObj oPixelPos, int nImageWidth, int nImageHeight, rectObj oGeorefExt [, rectObj oMaxGeorefExt])
    Zoom in or out to a given XY position so that the map is
    displayed at specified scale. Returns MS_SUCCESS or MS_FAILURE on error.

    Parameters are :

    - ScaleDenom : Scale denominator of the scale at which the map
      should be displayed.
    - Pixel position (pointObj) : x, y coordinates of the click,
      with (0,0) at the top-left
    - Width : width in pixel of the current image.
    - Height : Height in pixel of the current image.
    - Georef extent (rectObj) : current georef extents.
    - MaxGeoref extent (rectObj) : (optional) maximum georef extents.
      If provided then it will be impossible to zoom/pan outside of
      those extents.


.. index::
   triple: MapScript; PHP; outputformatObj

outputformatObj
^^^^^^^^^^^^^^^

Constructor
...............................................................................

Instance of outputformatObj is always embedded inside the `mapObj`_.
It is uses a read only.

No constructor available (coming soon, see ticket 979)

Members
...............................................................................

=============== =============== ================================================
Type                Name        Note
=============== =============== ================================================
string          driver
string          extension
int             imagemode       MS_IMAGEMODE_* value.
string          mimetype
string          name
int             renderer
int             transparent
=============== =============== ================================================

Methods
...............................................................................

string getOption(string property_name)
    Returns the associated value for the format option property passed
    as argument. Returns an empty string if property not found.

int set(string property_name, new_value)
    Set object property to a new value.

void setOption(string property_name, string new_value)
    Add or Modify the format option list. return true on success.

    .. code-block:: php

       $oMap->outputformat->setOption("OUTPUT_TYPE", "RASTER");

int validate()
   Checks some internal consistency issues, Returns MS_SUCCESS or
   MS_FAILURE. Some problems are fixed up internally. May produce debug
   output if issues encountered.

.. index::
   triple: MapScript; PHP; OwsrequestObj

OwsrequestObj
^^^^^^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

    new OWSRequestObj()

or using the old constructor

.. code-block:: php

    request = ms_newOwsrequestObj();

Create a new ows request object.

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
int             numparams (read-only)
int             type (read-only): MS_GET_REQUEST or MS_POST_REQUEST
=============== ================================================================

Methods
...............................................................................

int addParameter(string name, string value)
    Add a request parameter, even if the parameter key was previousely set.
    This is useful when multiple parameters with the same key are required.
    For example :

    .. code-block:: php

        $request->addparameter('SIZE', 'x(100)');
        $request->addparameter('SIZE', 'y(100)');

string getName(int index)
    Return the name of the parameter at *index* in the request's array
    of parameter names.

string getValue(int index)
    Return the value of the parameter at *index* in the request's array
    of parameter values.

string getValueByName(string name)
    Return the value associated with the parameter *name*.

int loadParams()
    Initializes the OWSRequest object from the cgi environment variables
    REQUEST_METHOD, QUERY_STRING and HTTP_COOKIE.  Returns the number of
    name/value pairs collected.

int setParameter(string name, string value)
    Set a request parameter.  For example :

    .. code-block:: php

       $request->setparameter('REQUEST', 'GetMap');

.. index::
   triple: MapScript; PHP; pointObj

pointObj
^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new pointObj()

or using the old constructor

.. code-block:: php

   PointObj ms_newPointObj()

Members
...............................................................................

=============== ========= ======================================================
Type             Name     Note
=============== ========= ======================================================
double          x
double          y
double          z         used for 3d shape files. set to 0 for other types
double          m         used only for measured shape files - set to 0 for other types
=============== ========= ======================================================

Methods
...............................................................................

double distanceToLine(pointObj p1, pointObj p2)
    Calculates distance between a point ad a lined defined by the
    two points passed in argument.

double distanceToPoint(pointObj poPoint)
   Calculates distance between two points.

double distanceToShape(shapeObj shape)
    Calculates the minimum distance between a point and a shape.

int draw(mapObj map, layerObj layer, imageObj img, int class_index [, string text])
    Draws the individual point using layer.  The class_index is used
    to classify the point based on the classes defined for the layer.
    The text string is used to annotate the point. (Optional)
    Returns MS_SUCCESS/MS_FAILURE.

int project(projectionObj in, projectionObj out)
    Project the point from "in" projection (1st argument) to "out"
    projection (2nd argument).  Returns MS_SUCCESS/MS_FAILURE.

int setXY(double x, double y [, double m])
    Set X,Y coordinate values.

    .. note::
      the 3rd parameter m is used for measured shape files only.
      It is not mandatory.

int setXYZ(double x, double y, double z [, double m])
    Set X,Y,Z coordinate values.

    .. note::
      the 4th parameter m is used for measured shape files only.
      It is not mandatory.

.. index::
   triple: MapScript; PHP; projectionObj

projectionObj
^^^^^^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new projectionObj(string projectionString)

or using the old constructor

.. code-block:: php

   ProjectionObj ms_newProjectionObj(string projectionString)

Creates a projection object based on the projection string passed
as argument.

.. code-block:: php

   $projInObj = ms_newprojectionobj("proj=latlong")

will create a geographic projection class.

The following example will convert a lat/long point to an LCC
projection:

.. code-block:: php

   $projInObj = ms_newprojectionobj("proj=latlong");
   $projOutObj = ms_newprojectionobj("proj=lcc,ellps=GRS80,lat_0=49,".
                                     "lon_0=-95,lat_1=49,lat_2=77");
   $poPoint = ms_newpointobj();
   $poPoint->setXY(-92.0, 62.0);
   $poPoint->project($projInObj, $projOutObj);

Methods
...............................................................................

int getUnits()
    Returns the units of a projection object. Returns -1 on error.

.. index::
   triple: MapScript; PHP; querymapObj

querymapObj
^^^^^^^^^^^

Constructor
...............................................................................

Instances of querymapObj are always are always embedded inside the
`mapObj`_.

Members
...............................................................................

=============== =========== ====================================================
Type                Name    Note
=============== =========== ====================================================
colorObj        color
int             height
int             width
int             style       MS_NORMAL, MS_HILITE, MS_SELECTED
=============== =========== ====================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the resources.

int set(string property_name, new_value)
    Set object property to a new value.

int updateFromString(string snippet)
    Update a queryMap object from a string snippet. Returns
    MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; rectObj

rectObj
^^^^^^^

Constructor
...............................................................................

rectObj are sometimes embedded inside other objects.  New ones can
also be created with:

.. code-block:: php

   new rectObj()

or using the old constructor

.. code-block:: php

   RectObj ms_newRectObj()

.. note:: the members (minx, miny, maxx ,maxy) are initialized to -1;

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
double          minx
double          miny
double          maxx
double          maxy
=============== ================================================================

Methods
...............................................................................

int draw(mapObj map, layerObj layer, imageObj img, int class_index [, string text])
    Draws the individual rectangle using layer.  The class_index is used
    to classify the rectangle based on the classes defined for the layer.
    The text string is used to annotate the rectangle. (Optional)
    Returns MS_SUCCESS/MS_FAILURE.

double fit(int width, int height)
    Adjust extents of the rectangle to fit the width/height specified.

int project(projectionObj in, projectionObj out)
    Project the rectangle from "in" projection (1st argument) to "out"
    projection (2nd argument).  Returns MS_SUCCESS/MS_FAILURE.

int set(string property_name, new_value)
    Set object property to a new value.

void setextent(double minx, double miny, double maxx, double maxy)
    Set the rectangle extents.

.. index::
   triple: MapScript; PHP; referenceMapObj

referenceMapObj
^^^^^^^^^^^^^^^

Constructor
...............................................................................

Instances of referenceMapObj are always embedded inside the `mapObj`_.

Members
...............................................................................

=============== ================================================================
Type                Name
=============== ================================================================
ColorObj        color
int             height
rectObj         extent
string          image
int             marker
string          markername
int             markersize
int             maxboxsize
int             minboxsize
ColorObj        outlinecolor
int             status
int             width
=============== ================================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

int set(string property_name, new_value)
    Set object property to a new value.

int updateFromString(string snippet)
    Update a referenceMap object from a string snippet.
    Returns MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; resultObj

resultObj
^^^^^^^^^^^^^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new resultObj(int shapeindex)

or using the `layerObj`_'s getResult() method.

Members
...............................................................................

=============== ============= ==================================================
Type                Name      Note
=============== ============= ==================================================
int             classindex    read-only
int             resultindex   read-only
int             shapeindex    read-only
int             tileindex     read-only
=============== ============= ==================================================

Method
...............................................................................

None

.. index::
   triple: MapScript; PHP; scalebarObj

scalebarObj
^^^^^^^^^^^

Constructor
...............................................................................

Instances of scalebarObj are always embedded inside the `mapObj`_.

Members
...............................................................................

=============== ================= ==============================================
Type                Name          Note
=============== ================= ==============================================
int             align
colorObj        backgroundcolor
colorObj        color
int             height
colorObj        imagecolor
int             intervals
labelObj        label
colorObj        outlinecolor
int             position          for embedded scalebars, MS_UL, MS_UC, ...
int             postlabelcache
int             status            MS_ON, MS_OFF, MS_EMBED
int             style
int             units
int             width
=============== ================= ==============================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

int set(string property_name, new_value)
    Set object property to a new value.

int setImageColor(int red, int green, int blue)
    Sets the imagecolor property (baclground) of the object.
    Returns MS_SUCCESS or MS_FAILURE on error.

int updateFromString(string snippet)
    Update a scalebar from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; shapefileObj

shapefileObj
^^^^^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new shapeFileObj(string filename, int type)

or using the old constructor

.. code-block:: php

   shapefileObj ms_newShapefileObj(string filename, int type)

Opens a shapefile and returns a new object to deal with it. Filename
should be passed with no extension.  To create a new file (or
overwrite an existing one), type should be one of MS_SHP_POINT,
MS_SHP_ARC, MS_SHP_POLYGON or MS_SHP_MULTIPOINT. Pass type as -1 to
open an existing file for read-only access, and type=-2 to open an
existing file for update (append).

Members
...............................................................................

=============== ========== =====================================================
Type                Name   Note
=============== ========== =====================================================
rectObj         bounds     read-only
int             numshapes  read-only
string          source     read-only
int             type       read-only
=============== ========== =====================================================

Methods
...............................................................................

int addPoint(pointObj point)
    Appends a point to an open shapefile.

int addShape(shapeObj shape)
    Appends a shape to an open shapefile.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

    .. note::
      The shape file is closed (and changes committed) when
      the object is destroyed. You can explicitly close and save
      the changes by calling $shapefile->free();
      unset($shapefile), which will also free the php object.

rectObj getExtent(int i)
    Retrieve a shape's bounding box by index.

shapeObj getPoint(int i)
    Retrieve point by index.

shapeObj getShape(int i)
    Retrieve shape by index.

shapeObj getTransformed(mapObj map, int i)
    Retrieve shape by index.

.. index::
   triple: MapScript; PHP; shapeObj

shapeObj
^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new shapeObj(int type)

or using the old constructor

.. code-block:: php

   ShapeObj ms_newShapeObj(int type)

'type' is one of MS_SHAPE_POINT, MS_SHAPE_LINE, MS_SHAPE_POLYGON or
MS_SHAPE_NULL

.. code-block:: php

   ShapeObj ms_shapeObjFromWkt(string wkt)

Creates new shape object from WKT string.

Members
...............................................................................

=============== =========== ====================================================
Type                Name    Note
=============== =========== ====================================================
rectObj         bounds      read-only
int             classindex
int             index
int             numlines    read-only
int             numvalues   read-only
int             tileindex   read-only
string          text
int             type        read-only
array           values      read-only
=============== =========== ====================================================

The values array is an associative array with the attribute values for
this shape.  It is set only on shapes obtained from layer->getShape().
The key to the values in the array is the attribute name, e.g.

.. code-block:: php

   $population = $shape->values["Population"];

Methods
...............................................................................

int add(lineObj line)
    Add a line (i.e. a part) to the shape.

shapeObj boundary()
    Returns the boundary of the shape.
    Only available if php/mapscript is built with GEOS library.

shapeObj buffer(width)
    Returns a new buffered shapeObj based on the supplied distance (given
    in the coordinates of the existing shapeObj).
    Only available if php/mapscript is built with GEOS library.

int containsShape(shapeObj shape2)
    Returns true if shape2 passed as argument is entirely within the shape.
    Else return false.
    Only available if php/mapscript is built with GEOS
    library.

shapeObj convexhull()
    Returns a shape object representing the convex hull of shape.
    Only available if php/mapscript is built with GEOS
    library.

boolean contains(pointObj point)
    Returns MS_TRUE if the point is inside the shape, MS_FALSE otherwise.

int crosses(shapeObj shape)
    Returns true if the shape passed as argument crosses the shape.
    Else return false.
    Only available if php/mapscript is built with GEOS library.

shapeObj difference(shapeObj shape)
    Returns a shape object representing the difference of the
    shape object with the one passed as parameter.
    Only available if php/mapscript is built with GEOS library.

int disjoint(shapeObj shape)
    Returns true if the shape passed as argument is disjoint to the
    shape. Else return false.
    Only available if php/mapscript is built with GEOS library.

int draw(mapObj map, layerObj layer, imageObj img)
    Draws the individual shape using layer.
    Returns MS_SUCCESS/MS_FAILURE.

int equals(shapeObj shape)
    Returns true if the shape passed as argument is equal to the
    shape (geometry only). Else return false.
    Only available if php/mapscript is built with GEOS library.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the resources.

double getArea()
    Returns the area of the shape (if applicable).
    Only available if php/mapscript is built with GEOS library.

pointObj getCentroid()
    Returns a point object representing the centroid of the shape.
    Only available if php/mapscript is built with GEOS library.

pointObj getLabelPoint()
    Returns a point object with coordinates suitable for labelling
    the shape.

double getLength()
    Returns the length (or perimeter) of the shape.
    Only available if php/mapscript is built with GEOS library.

pointObj  getMeasureUsingPoint(pointObj point)
   Apply only on Measured shape files. Given an XY Location, find the
   nearest point on the shape object. Return a point object
   of this point with the m value set.

pointObj getPointUsingMeasure(double m)
    Apply only on Measured shape files. Given a measure m, retun the
    corresponding XY location on the shapeobject.

string getValue(layerObj layer, string filedname)
    Returns the value for a given field name.

shapeObj intersection(shapeObj shape)
    Returns a shape object representing the intersection of the shape
    object with the one passed as parameter.
    Only available if php/mapscript is built with GEOS library.

boolean intersects(shapeObj shape)
    Returns MS_TRUE if the two shapes intersect, MS_FALSE otherwise.

LineObj line(int i)
    Returns a reference to line number i.

int overlaps(shapeObj shape)
    Returns true if the shape passed as argument overlaps the shape.
    Else returns false.
    Only available if php/mapscript is built with GEOS library.

int project(projectionObj in, projectionObj out)
    Project the shape from "in" projection (1st argument) to "out"
    projection (2nd argument).  Returns MS_SUCCESS/MS_FAILURE.

int set(string property_name, new_value)
    Set object property to a new value.

int setBounds()
    Updates the bounds property of the shape.
    Must be called to calculate new bounding box after new parts have been
    added.

shapeObj simplify(double tolerance)
    Given a tolerance, returns a simplified shape object or NULL on
    error.  Only available if php/mapscript is built with GEOS library
    (>=3.0).

shapeObj symdifference(shapeObj shape)
    Returns the computed symmetric difference of the supplied and
    existing shape.
    Only available if php/mapscript is built with GEOS library.

shapeObj topologyPreservingSimplify(double tolerance)
    Given a tolerance, returns a simplified shape object or NULL on
    error.  Only available if php/mapscript is built with GEOS library
    (>=3.0).

int touches(shapeObj shape)
    Returns true if the shape passed as argument touches the shape.
    Else return false.
    Only available if php/mapscript is built with GEOS library.

string toWkt()
    Returns WKT representation of the shape's geometry.

shapeObj union(shapeObj shape)
    Returns a shape object representing the union of the shape object
    with the one passed as parameter.
    Only available if php/mapscript is built with GEOS
    library

int within(shapeObj shape2)
    Returns true if the shape is entirely within the shape2 passed as
    argument.
    Else returns false. 
    Only available if php/mapscript is built with GEOS library.

.. index::
   triple: MapScript; PHP; styleObj

styleObj
^^^^^^^^

Constructor
...............................................................................

Instances of styleObj are always embedded inside a `classObj`_ or `labelObj`_.

.. code-block:: php

   new styleObj(classObj class [, styleObj style])
   // or
   new styleObj(labelObj label [, styleObj style])

or using the old constructor (do not support a labelObj at first argument)

.. code-block:: php
    
   styleObj ms_newStyleObj(classObj class [, styleObj style])

The second argument 'style' is optional. If given, the new style
created will be a copy of the style passed as argument.
    
Members
...............................................................................

=============== ==================== ===========================================
Type                Name             Note
=============== ==================== ===========================================
double          angle
int             antialias
colorObj        backgroundcolor
colorObj        color
double          maxsize 
double          maxvalue
double          maxwidth
double          minsize 
double          minvalue
double          minwidth
int             offsetx
int             offsety
int             opacity              only supported for the AGG driver
colorObj        outlinecolor
string          rangeitem
double          size
int             symbol
string          symbolname
double          width
=============== ==================== ===========================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references.
    Note that you have to unset the php variable to free totally the
    resources.

string getBinding(mixed stylebinding)
    Get the attribute binding for a specfiled style property. Returns
    NULL if there is no binding for this property.

    .. code-block:: php
    
       $oStyle->setbinding(MS_STYLE_BINDING_COLOR, "FIELD_NAME_COLOR");
       echo $oStyle->getbinding(MS_STYLE_BINDING_COLOR); // FIELD_NAME_COLOR

string getGeomTransform()

int removeBinding(mixed stylebinding)
    Remove the attribute binding for a specfiled style property.
    Added in MapServer 5.0.
    
    .. code-block:: php
        
       $oStyle->removebinding(MS_STYLE_BINDING_COLOR);

int set(string property_name, new_value)
    Set object property to a new value.

int setBinding(mixed stylebinding, string value)
    Set the attribute binding for a specfiled style property.
    Added in MapServer 5.0.
   
    .. code-block:: php

       $oStyle->setbinding(MS_STYLE_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"

int setGeomTransform(string value)

int updateFromString(string snippet)
    Update a style from a string snippet. Returns MS_SUCCESS/MS_FAILURE.

.. index::
   triple: MapScript; PHP; symbolObj

symbolObj
^^^^^^^^^^^

Constructor
...............................................................................

.. code-block:: php

   new symbolObj(mapObj map, string symbolname)

or using the old constructor
  
.. code-block:: php

   int ms_newSymbolObj(mapObj map, string symbolname)
    
Creates a new symbol with default values in the symbolist. 

.. note::
   Using the new constructor, the symbol is automatically returned. The
   old constructor returns the id of the new symbol.

If a symbol with the same name exists, it (or its id) will be returned.
To get a symbol object using the old constructor, you need to use a method on the map object:

.. code-block:: php

   $nId = ms_newSymbolObj($map, "symbol-test");
   $oSymbol = $map->getSymbolObjectById($nId);

Members
...............................................................................

=============== ================= ==============================================
Type                Name          Note
=============== ================= ==============================================
int             antialias 
string          character 
int             filled
string          font 
string          imagepath         read-only
int             inmapfile         If set to TRUE, the symbol will be saved
                                  inside the mapfile.
int             patternlength     read-only
int             position
string          name
int             numpoints         read-only
double          sizex
double          sizey
int             transparent 
int             transparentcolor 
=============== ================= ==============================================

Methods
...............................................................................

void free()
    Free the object properties and break the internal references. 
    Note that you have to unset the php variable to free totally the
    resources.

array getPatternArray()  
    Returns an array containing the pattern. If there is no pattern, it
    returns an empty array.
        
array getPointsArray()
    Returns an array containing the points of the symbol. Refer to
    setpoints to see how the array should be interpreted. If there are no
    points, it returns an empty array.

int set(string property_name, new_value)
    Set object property to a new value.

int setImagePath(string filename)
    Loads a pixmap symbol specified by the filename. 
    The file should be of either  Gif or Png format.

int setPattern(array int)
    Set the pattern of the symbol (used for dash patterns). 
    Returns MS_SUCCESS/MS_FAILURE.

int setPoints(array double)
    Set the points of the symbol. Note that the values passed is an
    array containing the x and y values of the points. Returns
    MS_SUCCESS/MS_FAILURE.
    Example:

    .. code-block:: php

      $array[0] = 1 # x value of the first point
      $array[1] = 0 # y values of the first point
      $array[2] = 1 # x value of the 2nd point
      ....

Example of usage
..................

1) create a symbol to be used as a dash line

  .. code-block:: php

    $nId = ms_newsymbolobj($gpoMap, "mydash");
    $oSymbol = $gpoMap->getsymbolobjectbyid($nId);
    $oSymbol->set("filled", MS_TRUE);
    $oSymbol->set("sizex", 1);
    $oSymbol->set("sizey", 1);
    $oSymbol->set("inmapfile", MS_TRUE);

    $aPoints[0] = 1;
    $aPoints[1] = 1;
    $oSymbol->setpoints($aPoints);

    $aPattern[0] = 10;
    $aPattern[1] = 5;
    $aPattern[2] = 5;
    $aPattern[3] = 10;
    $oSymbol->setpattern($aPattern);

    $style->set("symbolname", "mydash");

2) Create a TrueType symbol 

  .. code-block:: php
    
    $nId = ms_newSymbolObj($gpoMap, "ttfSymbol"); 
	$oSymbol = $gpoMap->getSymbolObjectById($nId); 
	$oSymbol->set("type", MS_SYMBOL_TRUETYPE); 
	$oSymbol->set("filled", true); 
	$oSymbol->set("character", "&#68;"); 
    $oSymbol->set("font", "ttfFontName"); 

.. index::
   triple: MapScript; PHP; webObj

webObj
^^^^^^

Constructor
...............................................................................

Instances of webObj are always are always embedded inside the `mapObj`_.

Members
...............................................................................

=============== =============== ================================================
Type                Name        Note
=============== =============== ================================================
string          browseformat
string          empty           read-only
string          error           read-only
rectObj         extent          read-only
string          footer
string          header
string          imagepath
string          imageurl
string          legendformat
string          log
double          maxscaledenom
string          maxtemplate
hashTableObj    metadata
double          minscaledenom
string          mintemplate
string          queryformat
string          template      
string          temppath
=============== =============== ================================================

Methods
...............................................................................

string convertToString()
    Saves the object to a string.  Provides the inverse option for
    updateFromString.

void free()
    Free the object properties and break the internal references. 
    Note that you have to unset the php variable to free totally the
    resources.

int set(string property_name, new_value)
    Set object property to a new value.

int updateFromString(string snippet)
    Update a web object from a string snippet. Returns
    MS_SUCCESS/MS_FAILURE.

.. _phpclusterobj:
