4.8. LayerObj Class

Next: LegendObj Class Previous: LabelObj Class  

• Constant names and class member variable names are case-sensitive in PHP.
• Several MapScript functions (all those that access files in the back end such as ms_newMapObj(), drawMap(), etc.) will affect the value of the current working directory (CWD) in the PHP environment. This will be fixed eventually but in the meantime you should be careful about these side-effects.

Constructor:
  Layer Objects can be returned by the MapObj class, or can be created
  using:

  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:
  int    numclasses  (read-only)
  int    index       (read-only)
  int    status      (MS_ON, MS_OFF, MS_DEFAULT or MS_DELETE)
  int    debug
  string classitem
  string classgroup
  string name
  string group
  string data
  int    type
  int    dump
  double tolerance
  int    toleranceunits
  int    sizeunits
  double symbolscaledenom
  double minscaledenom
  double maxscaledenom
  double labelminscaledenom
  double labelmaxscaledenom
  double symbolscale   (Deprecated in v5.0, use symbolscaledenom instead)
  double minscale      (Deprecated in v5.0, use minscaledenom instead)
  double maxscale      (Deprecated in v5.0, use maxscaledenom instead)
  double labelminscale (Deprecated in v5.0, use labelminscaledenom instead)
  double labelmaxscale (Deprecated in v5.0, use labelmaxscaledenom instead)
  int    maxfeatures
  colorObj    offsite
  int    annotate
  int    transform
  int    labelcache
  int    postlabelcache
  string labelitem
  string labelsizeitem
  string labelangleitem
  string tileitem
  string tileindex
  string header
  string footer
  string connection
  int    connectiontype
  string filteritem
  string template
  int    opacity
  int    transparency (Deprecated in v5.0. Use opacity instead.)
  string styleitem
  gridObj grid //only available on a layer defined as grid (MS_GRATICULE)
  int num_processing
  string requires
  string labelrequires

Methods:

  int set(string property_name, new_value)
       Set object property to a new value. Returns -1 on error.

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

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

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

  int queryByPoint(pointObj point, int mode, double buffer)
       Query layer at point location specified in georeferenced map 
       coordinates (i.e. not pixels).  
       The query is performed on all the shapes that are part of a CLASS 
       that contains a TEMPLATE value or that match any class in a
       layer that contains a LAYER TEMPLATE value.
       Mode is MS_SINGLE or MS_MULTIPLE depending on number of results
       you want. 
       Passing buffer -1 defaults to tolerances set in the map file 
       (in pixels) but you can use a constant buffer (specified in 
       ground units) instead.
       Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
       was found or if some other error happened (note that the error 
       message in case nothing was found can be avoided in PHP using 
       the '@' control operator).

  int queryByRect(rectObj rect)
       Query layer using a rectangle specified in georeferenced map 
       coordinates (i.e. not pixels).
       The query is performed on all the shapes that are part of a CLASS 
       that contains a TEMPLATE value or that match any class in a
       layer that contains a LAYER TEMPLATE value.
       Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
       was found or if some other error happened (note that the error 
       message in case nothing was found can be avoided in PHP using 
       the '@' control operator).

  int queryByShape(shapeObj shape)
       Query layer based on a single shape, the shape has to be a polygon
       at this point.
       Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
       was found or if some other error happened (note that the error 
       message in case nothing was found can be avoided in PHP using 
       the '@' control operator).

  int queryByFeatures(int slayer) 
       Perform a query set based on a previous set of results from
       another layer. At present the results MUST be based on a polygon
       layer.
       Returns MS_SUCCESS if shapes were found or MS_FAILURE if nothing
       was found or if some other error happened (note that the error 
       message in case nothing was found can be avoided in PHP using 
       the '@' control operator).

  int queryByAttributes(string qitem, string qstring, int mode)
       Query layer for shapes that intersect current map extents.
       qitem is the item (attribute) on which the query is performed, 
       and qstring is the expression to match.
       The query is performed on all the shapes that are part of a CLASS 
       that contains a TEMPLATE value or that match any class in a
       layer that contains a LAYER 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 setFilter(string expression)
       Set layer filter expression.

  string getFilterString()
       Returns the expression for this layer.

  string getFilter()
       Deprecated in v5.0, use getFilterString() instead.

  string getProjection()
       Returns a string represenation of the projection. If no 
       projection is set, MS_FALSE is returned.

  int setProjection(string proj_params)
       Set layer projection and coordinate system.  Parameters are given as 
       a single string of comma-delimited PROJ.4 parameters.

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

  int getNumResults()
       Returns the number of results from this layer in the last query.

  resultCacheMemberObj getResult(int index)
       Returns a resultCacheMemberObj 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.

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

  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 or MS_FAILURE.

  shapeobj nextShape()
      Called after msWhichShapes has been called to actually retrieve shapes 
      within a given area           
      returns a shape object or MS_FALSE

       example of usage :

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


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

  shapeObj getFeature(int shapeindex [, int tileindex = -1])
       Retrieve shapeObj from a layer by index.
       Tileindex is optional and is used only for tiled shapefiles 
       (you get it from the resultCacheMemberObj returned by getResult()
       for instance). 
       Simply omit or pass tileindex = -1 for other data sources.

  shapeObj getShape(int tileindex, int shapeindex)
       Deprecated in v5.0, use getFeature() instead (note that the order
       of the arguments is reversed since tileindex is optional in 
       getFeature())

  rectObj getExtent()
       Returns the layer's data extents. 
       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.

  int addFeature(shapeObj shape)
       Add a new feature in a layer.  Returns -1 on error.

  int getMetaData(string name)
       Fetch layer metadata entry by name.  Returns "" if no entry 
       matches the name.  Note that the search is case sensitive.

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

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

  string getWMSFeatureInfoURL(int clickX, int clickY, int featureCount, 
                              string infoFormat)
       Return 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.
       
  aString getItems()
       return a list of items. Must call open function first.

  boolean setProcessing(string)
       Add the string to the processing string list for the layer.
       The layer->num_processing is incremented by 1.
       Ex : $oLayer->setprocessing("SCALE_1=AUTO");
            $oLayer->setprocessing("SCALE_2=AUTO");       

  aString getProcessing()
       Returns an array containing the processing strings

  boolean clearProcessing()
       Clears all the processing strings

  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.

  int applySLD(string sldxml, string namedlayer)
       Apply the 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 SLD How to for more information on the SLD support.

 int applySLDURL(string sldurl, string namedlayer)
       Apply the 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 SLD How to for more information on the SLD support.

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

 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 postion 0, and the class at position 0 will be moved
          to position 1.

 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 postion 1, and the class at position 1 will be moved
          to position 0.

 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.

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

Next: LegendObj Class Previous: LabelObj Class