=====================================
MapServer 4.10 to 5.0 Migration Guide
=====================================

This page documents the changes that must be made to MapServer 
applications when migrating from version 4.10.x (or earlier versions) 
to 5.x (i.e. backwards incompatibilities), as well as information
on some of the new features.

----------------------------------------------------
Mapfile changes
----------------------------------------------------

Attribute Bindings: In an effort to stem the tide of keyword overload
and add functionality MapServer 5.0 supports a new method of binding 
feature attributes to STYLE and LABEL properties. In the past keywords
like ANGLEITEM or LABELSIZEITEM were used, now you denote the attribute
in the context of the property being bound. For example, to bind an 
attribute to a label size you'd do:

::

  LABEL
    ...
    SIZE [mySizeItem]
  END

The []'s denote a binding (as with logical expressions). The following
keywords are no longer supported and their presence will throw an error:

* Layer: LABELANGLEITEM, LABELSIZEITEM
* Style: ANGLEITEM, SIZEITEM

The following properties can accept bindings:

* Style: angle, color, outlinecolor, size, symbol
* Label: angle, color, outlinecolor, size, font, priority

Colors may be given as a hex value (e.g. #FFFFFF) or an RGB triplet 
(e.g. 255 255 255).


Layer Transparency: The values for the TRANSPARENCY parameter have always
been backwards and in an effort to resolve that the parameter has been
renamed OPACITY. TRANSPARENCY is still recognized by the mapfile parser
but is depricated and should be avoided. 

Scale Parameters: MapServer's handling of scale has long been a source
for confusion. The values use in a layer MINSCALE are really the denominators
from a representative fraction (e.g. 1:24000). To help clarify this all
scale parameters are now end with DENOM. So MINSCALE => MINSCALEDENOM,
SYMBOLSCALE => SYMBOLSCALEDENOM, and so on. The mapfile parser still
recognizes the older keywords but they are depricated and should be avoided. 

----------------------
Symbol file changes
----------------------

Symbol Style: STYLEs are used within a symbol definition to store dash
patterns for line symbolization. However, there is potential confusion
with the style object that is used within class definitions. To resolve
that confusion the symbol STYLE parameter has been renamed PATTERN. The
symbol file parser will still recognize the STYLE keyword but it is 
depricated and should be avoided.

----------------------------------------------------
Styling/Symbolgy changes
----------------------------------------------------
Prior to MapsServer 5.0, if a pixmap symbol was used in style on a Line
Layer, the symbol was used as a brush to draw the line. In MapServer 5.0, 
it is possible to draw the pixmap symbol along the line (Note that this 
was available using a true type symbol). To achieve  this, the user needs 
to use the parameter GAP with it's pixmap symbol definition in the symbol
file. The GAP represents the distance between the symbols. If the GAP is not
given, the pixmap symbol will be used as a brush.

----------------------------------------------------
AGG rendering changes   
----------------------------------------------------
see `the AGG rendering specifics`_ for the changes relating to the addition
of the `Antigrain Geometry`_ rendering engine.

.. _`the AGG rendering specifics`: http://mapserver.gis.umn.edu/docs/howto/agg-rendering-specifics
.. _`Antigrain Geometry`: http://www.antigrain.com

---------------------------------------------------
URL configuration changes
---------------------------------------------------

Previous versions of the MapServer CGI program allowed certain parameters
to be changed via a URL using a cumbersome syntax such as 
map_layer_0_class_0_color=255+0+0 which changes the color in one classObj.
Not only was this cumbersome for users but also from a code maintenance
perspective since we had to maintain seperate loaders for URL-based config
and file-based config. RFC-31 attempts to streamline both by migrating to
a single object loading function that can be used with strings (either in
MapScript or via URL) or with files.

So, in the past you have to change parameters one-at-a-time. Now you can
pass chunks of mapfiles (with security restrictions) to the CGI interface.
The map_object notation is still necessary to identify which object you
want to modify but you can change multiple properties at one time. Note 
that you can use either a '_' or a '.' to seperate identifiers.

Example 1, changing a scalebar object:

::

  ...&map.scalebar=UNITS+MILES+COLOR+121+121+121+SIZE+300+2&...

Example 2, changing a presentation style:

::

 ...&map.layer[lakes].class[0].style[0]=SYMBOL+crosshatch+COLOR+151+51+151+SIZE+15&...

Example 3, creating a new feature

::

  ...&map_layer[3]=FEATURE+POINTS+500000+1000000+END+TEXT+'A+test+point'+END&...

The variable identifies an object uniquely (by name or index in the case of
layerObj's and classObj's). The value is a snippet of a mapfile. You
cannot create new objects other than inline features at this point.

-------------------------------------------------
Validation patterns for mapserv attribute queries
-------------------------------------------------

Attribute queries (qstring) done via the mapserv CGI could theoretically 
be used for SQL injection.

No exploit has been reported, but in order to mitigate the risk, a new
validation pattern mechanism has been added in 5.0.

In the case of qstring attribute queries, the qstring_validation_pattern
layer-level metadata is required for qstring queries to work. The metadata
value is a regular expression that the qstring value must match otherwise
mapserv produces a fatal error. A fatal error is also produced if qstring
is used but qstring_validation_pattern is not provided.

Note that similar validation pattern mechanism has been available for 
%variable% substitutions since version 4.10, but in this case it is optional. 
The  pattern for %myvar% is provided via a metadata called 
myvar_validation_pattern.

----------------------------------------------------
SWIG MapScript (Python, Perl, CSharp, Java) changes
----------------------------------------------------

Layer Transparency: The layerObj transparency parameter is now called
opacity. Scripts setting that value in code must be updated.

Symbol Style: the symbolObj style parameter is now called pattern. MapScript
does not allow direct modification of that parameter. In Swig-based languages
the symbolObj method setStyle is now called setPattern. In PHP/MapScript, the
methods setStyle and getStyle are now called setPattern and getPattern.

A new msGetVersionInt() function returning the current MapServer version in
integer format has been added to facilitate version checks in the future.
Given version x.y.z, it returns (x*0x10000 + y*0x100 + z). For instance, for
v5.0.0 it will return 0x050000 (note the hexadecimal notation).

-----------------------
CSharp related changes
-----------------------

The MapScript C# classes are now placed into the OSGeo.MapServer namespace
The scripts should use the fully qualified names of the classes or apply 
the 

::

  using OSGeo.MapServer;
  
or the corresponding language equivalent. 

----------------------------------------------------
PHP/MapScript changes
----------------------------------------------------

Layer Transparency: The layerObj transparency parameter is now called
opacity. The old "transparency" name is deprecated and will be removed in
a future release. Scripts getting/setting that value in code must be updated.

All occurences of scale, minscale, maxscale, etc... parameters have been
deprecated and renamed with a "denom" suffix (e.g. minscale becomes 
minscaledenom, etc.). The deprecated parameters will be removed in a
future release. Scripts getting/setting them must be updated.

SymbolObj style has been renamed pattern. The old "stylelength" parameter
and setStyle() and getStyleArray() methods have been deprecated and 
"patternlength", setPattern() and getPatternArray() should be used 
instead. They will be removed in a future release.

layer.getShape(int tileindex, int shapeindex)) has been deprecated and 
renamed to layer.getFeature(int shapeindex [, int tileindex = -1]) to
match the SWIG MapScript equivalent. Note that the order of the arguments
is reversed since tileindex is optional in getFeature().

class.getExpression() and layer.getFilter() have been deprecated and 
renamed to class.getExpressionString() and layer.getFilterString() to 
match what we have in SWIG MapScript. The String suffix in the function
name also more clearly indicates that the return value is not an object
but a string representation of it.

A new ms_GetVersionInt() function returning the current MapServer version in
integer format has been added to facilitate version checks in the future.
Given version x.y.z, it returns (x*0x10000 + y*0x100 + z). For instance, for
v5.0.0 it will return 0x050000 (note the hexadecimal notation).

----------------------------------------------------
OGC Web Map Service (WMS)
----------------------------------------------------

Required Parameters for GetMap and GetFeatureInfo: previously, MapServer
did not check for the following parameters when responding to an OGC:WMS
GetMap or GetFeatureInfo request:

 - SRS
 - FORMAT
 - WIDTH
 - HEIGHT
 - STYLES or SLD / SLD_BODY
 - BBOX

That is, a GetMap request would process without error if these were not 
passed by the WMS client.

A compliant OGC:WMS 1.1.0 and 1.1.1 REQUIRES these parameters.  This may
affect OGC:WMS client requests who were not passing these values. Ticket
1088 fully documents this issue.  In addition to WMS compliance, this was also 
decided that by adding this constraint, if an OGC client request (as described
earlier) breaks something, people should fix their client anyway since
if they change WMS vendor, they will have problems as well.

----------------------------------------------------
OGC Web Feature Service (WFS)
----------------------------------------------------

----------------------------------------------------
Build Changes
----------------------------------------------------

MapServer's main include file has been renamed from "map.h" to "mapserver.h".

A new mapserver-config script has been created with the following options:

::

  Usage: mapserver-config [OPTIONS]
  Options:
   [--libs]
   [--dep-libs]
   [--cflags]
   [--defines]
   [--includes]
   [--version]

The shared and static link libraries for MapSserver have been renamed
libmapserver.x.y.so and libmapserver.a respectively.


The --enable-coverage configure option has been renamed to --enable-gcov
since the former name led users to think it might be related to enabling 
support for WCS or Arc/Info coverages:

::

  --enable-gcov           Enable source code coverage testing using gcov
  
  
-----------------------------------------------------
Features Heading for Deprecation
-----------------------------------------------------

Some features present in MapServer are likely to be removed in a future
release. Features might be headed for deprecation because:

 - they have been replaced by a superior or more capable solution
 - they have stopped being maintained

Users of these features should be prepared for these upcoming changes
and start adapting their mapfiles in consequence. If you have strong 
and motivated objections as to the removal of one or more of these
features please open a discussion in the usual Mapserver communication
channels. 
 
Cartoline symbols: these were a hack to overcome GD weaknesses, and their
functionality is now supported by the AGG renderer. They have become poorly
supported in current MapServer versions. Keywords allowing for setting the
style of line joins and caps will be moved to the STYLE block.

RGB/RGBA output with GD: support for RGB and RGBA image types will likely not
be maintained anymore. PC256 will continue to be supported with GD, while RGB
and RGBA will liekly only be supported with AGG