MapGuide RFC 185 - Use vanilla SWIG to generate API bindings

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	7 Jul 2022
Last Modified	7 Jul 2022
Author	Jackie Ng
RFC Status	draft
Implementation Status	pending
Proposed Milestone	4.0
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes to adopt using the latest un-modified version of SWIG to generate our API bindings for .net, Java and PHP.

Motivation

For the longest time now, MapGuide has been shackled to PHP 5.6 which has been out of support for a long time. It is not a good look for us security-wise to ship new releases of MapGuide that bundle a long out-of-date version of PHP.

The reason we haven't upgraded our bundled copy of PHP is because PHP has changed the internal zend extension APIs for PHP 7+ in such a breaking manner that it is not possible to generate API bindings with our internal (heavily-modified) copy of SWIG that will work with the currently supported version of PHP (8.1.x)

The current version of SWIG (4.0) supports generating bindings for PHP 7 and the current git master supports generating bindings for PHP 7/8.

To finally be able to bundle the latest version of PHP with our MapGuide releases, we need to be able to generate functional MapGuide API bindings for PHP using the official version of SWIG instead of our ancient and heavily-modified internal copy in Oem/SwigEx. In the process, we might as well also be using official SWIG to try and generate functional MapGuide API bindings for .net and Java as well.

Proposed Solution

We will use the current git master of swig at ​https://github.com/swig/swig to generate MapGuide API bindings for .net, Java and PHP. The rest of this RFC will refer to this version of SWIG as "vanilla SWIG"

The PHP binding targets PHP 8.1, and we will be bundling PHP 8.1 with the MapGuide install packages.

A new top-level Bindings subdirectory and solution will house the various API binding projects and supporting tools/libraries.

The following projects in Oem will be removed:

• Oem/SwigEx
• Oem/SQLite

Vanilla SWIG is now a build requirement. On Windows, pre-compiled binaries of the expected version of SWIG will be provided for convenience.

Fusion and all existing web tier applications (eg. AJAX Viewer, Site Administrator) will be migrated across to work against these new API bindings.

The existing web tier test suite will also be migrated across to work against these new API bindings.

Impact summary of API changes

To support generating functional API bindings for .net/Java/PHP with vanilla SWIG, we had to make a few changes to our C++ API surface to facilitate/accommodate the code generation needs of vanilla SWIG. Such changes are detailed below.

General (all languages)

• The exception hierarchy has been flattened to just MgException. All existing sub-classes of MgException have been removed. A new GetExceptionCode() method is available to fetch the appropriate error classification. The available classifications are simply the names of all the removed sub-classes and whose names are now contained in a new MgExceptionCodes string constant class.
  • This was done to avoid having to deal with MgException polymorphism in a consistent manner across our 3 SWIG language targets.
  • Refer to the table below for how to migrate your exception handling code for your target language

[TODO: Insert before/after table]

• The constant members of the MgResourcePermission class are prefixed with Permission. For example MgResourcePermission::ReadOnly is now MgResourcePermission::PermissionReadOnly
  • This was done to prevent reserved name collisions in PHP where readonly is now a reserved keyword and cannot be used as a static member name.

[TODO: Cover various renamed methods in MgCoordinateSystem API]

PHP specific notes

• constants.php is no longer required! All constants of the MapGuide API are now baked into the PHP zend extension, eliminating the need for this file. When migrating, remove all include/require references to this file.
• The MgPlotSpecification constructor now requires you to specify all 4 margin parameters . If you don't need a margin, or need to set it later on (with the SetMargins() method), you can pass 0.0 for all 4 arguments.
• PHP 8 is more strict about data types and attempting to do things like assigning int to double and vice-versa and will generally error out in such cases.
  • This strictness may arise in calls to APIs like MgRenderingService::RenderMap where there is a mixture of int and double parameters in the method signature.
  • To ensure the correct data types are passed in, wrap expected int parameters with intval() and expected double parameters with doubleval()

Java specific notes

This wrapper is based on and replaces the previous MapGuideJavaApiEx variant of the official Java binding (first introduced in MapGuideRfc129) and is once again called MapGuideApi.jar

MapGuideApiEx.jar is no longer generated and bundled.

Java 8 or higher is required to create/run Java MapGuide applications.

.net specific notes

This wrapper is now provided as a set of NuGet packages targeting netstandard2.0

• OSGeo.MapGuide.Foundation
• OSGeo.MapGuide.Geometry
• OSGeo.MapGuide.PlatformBase
• OSGeo.MapGuide.MapGuideCommon
• OSGeo.MapGuide.Web

Being a netstandard2.0 package, you can use this in:

• Your existing (legacy) ASP.net WebForms/MVC application targeting (legacy) .net Framework 4.8
• A greenfield ASP.net application targeting .net Core/.net 5+

Ability to target [.net Core/.net 5+] on Linux TBD

Impact summary for deployments

The PHP binding is built for the Non-Thread-Safe (NTS) profile. This means that we no longer configure PHP support in Apache via mod_php. Instead PHP support in Apache is now configured via FastCGI through mod_fcgid. This allows us to bundle/ship one set of PHP NTS binaries that can correctly work in both IIS and Apache configurations on Windows. Previously, we did the incorrect thing of bundling the Thread-Safe (TS) PHP binaries and used it for both Apache (supported) and IIS (un-supported).

Test Plan

Ensure the migrated web tier test suites pass against the new bindings.

Ensure AJAX viewer for all 3 languages are functional with these new bindings.

Ensure Fusion is functional with these new bindings.

Ensure Site Administrator is functional.

Ensure Schema Report is functional.

Funding / Resources

Community