Unification of PHP and SWIG mapscript APIs

[sgillies@…]

Goal: Bring the SWIG and PHP mapscript APIs near enough to where it's useful
to merge the documentation.

Here are some differences that need to be worked out:

Class Names
-----------

SWIG mapscript has classes which are named after the structs in map.h like
'pointObj', etc.  The PHP README contains classes like 'PointObj', 'pointObj',
'pointObject'.  I don't know whether PHP is case insensitive or not, but the
SWIG modules are, and we'll need to settle on unified class names.

While we are at it, what about renaming the classes to remove the superfluous
'Obj' suffix and capitalize the names?  In most OO languages the convention
is that classes have capitalized names.   Instead of mapscript.layerObj we
would have mapscript.Layer which is better.

(another aside: we should really rename a merged API to 'mapserver' instead of
'mapscript')

Function/Method Names
---------------------

I've been following the original SWIG mapscript style which is camel case.
The PHP README has some camel case, some completely lower case function names.

Function Arguments
------------------

I am currently refactoring many constructors to take optional arguments.  You
can see this with colorObj and rectObj.  Is this feasible with PHP?  Yes, I
have assumed.

Any other issues that you see?

[sdlime]

My vote would be to leave the name alone.

[sgillies@…]

Yeah, changing the name of the module breaks everything.

It is more descriptive, tho: the 'script' is unnecessary, and 'mapscript'
doesn't say enough about the relationship with MapServer.

Was just a thought.

[dmorissette]

(I seem to be unable to submit a large comment... let's try to split it in 2 parts)

- In PHP we don't use the class names, so we *should* go back to using the same
nanme as the C structs and as SWIG.  The cases where the name differs are errors
in the part of the person who wrote the docs.

- In PHP class method names are NOT case-sensitive.  They are actually
registered all lowercase internally, and the PHP interpreter maps mixed cases to
lowercase at runtime (yup, there is a performance hit there).  So using the same
cases as SWIG will work.

[dmorissette]

(... and here comes the rest...)

- Optional arguments are supported in PHP, so the constructors could use them. 
Note that we don't use the 'new' operator in PHP, but instead we've beem using
functions called ms_newWhateverObj() to instanciate a new object.  This is one
difference that will have to remain for now.  Someday we should look at the
possibility of using PHP class names and the new operator, but that will likely
require some work.

- About renaming the classes to remove the Obj suffix, I'm with Steve and I
think we should leave the names alone.

- About renaming mapscript to mapserver: I like the name mapscript... it clearly
refers to a component of the mapserver product.

[dmorissette]

Oh, another one: in PHP extensions, class member variables are case sensitive
(contrary to method names) and are stored in lowercase internally.  So we've
been using all lowercase for class member variables in the docs and hopefully we
can continue that route.

[sgillies@…]

OK, I am with y'all on the names.

[sgillies@…]

... and I also think that lowercase attribute names are best.

[sgillies@…]

Daniel, re the new operator and constructors:

every language supported by the SWIG mapscript has its own style of
constructor

   $m = new mapObj               # Perl
   m = mapObj()                  # Python
   m = MapObj.new()              # Ruby

(Hey, SWIGRUBY forces capitalization of class names.  Cool!)

It seemed to me to be the most lang-neutral thing to write 'new mapObj'
in the unified documentation.  Maybe 'new' all by itself would be better?

[dmorissette]

I guess "new mapObj(arg1, arg2,...)" (with the args too) would be what makes the
most sense, and should include a note somewhere that explains the exact syntax
to use for each scripting language.

[sgillies@…]

Daniel, Steve,

Here is an argument _against_ using SWIG for PHP-mapscript that has occurred
to me while documenting the SWIG mapscript.

The PHP mapscript has some niceties like being able to
access the attributes of a shapeObj through the associative
array named values.

This will be a pain in the butt to do with SWIG.  What would the typemap
look like?  Who knows?  I've never seen an example of SWIG typemapping
an array into an associative array.

[sdlime]

That's why I've avoided typemaps in the past. You have to write one for every 
language. It is doable though and I've seen examples. Actually should be a very 
common problem- turn 2 arrays into an associative array. There may even be a 
standard type map for such a beast.

Steve

[assefa]

I guess this is still work in progress. Nothing sspecific to be done for 4.4 
release. Setting it to FUTURE.

[sgillies@…]

won't fix.