Changes between Initial Version and Version 1 of MapGuideRfc185

Timestamp:

Jul 7, 2022, 2:58:53 AM (22 months ago)

Author:

jng

Comment:

--

MapGuideRfc185

@@ +1 @@
+
+= !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 [wiki:MapGuideRfcs 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.
+
+=== 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 [wiki: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