MapGuide RFC 138 - Upgrade Apache, Tomcat and PHP

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	2 Sep 2013
Last Modified	6 Sep 2013
Author	Jackie Ng
RFC Status	ready for review
Implementation Status	pending
Proposed Milestone	2.6
Assigned PSC guide(s)	(when determined)
Voting History	(vote date)
+1
+0
-0
-1
no vote

Overview

This RFC proposes to upgrade Apache, Tomcat and PHP to the latest versions:

• Apache: 2.4.6
• Tomcat: 7.0.42
• PHP: 5.5.3

Motivation

We are currently building against what is now very old versions of Apache and PHP, which is not a good thing from a security standpoint.

In addition, we should ideally move to a version of Apache and PHP that is built off of the same Visual Studio 2012 C++ compiler, since the MapGuide codebase has already migrated to this compiler.

Moving to Apache httpd 2.4.6 and PHP 5.5.3 solves both of these issues:

• Apache 2.4.6 is the latest stable version of Apache. ​http://www.apachelounge.com offers VC11 builds of Apache 2.4.x.
• PHP 5.5.3 is the latest stable version of PHP. VC11 is also the official windows compiler used to build the 5.5.x series of PHP

Proposed Solution

Upgrade Apache to 2.4.6 Upgrade Tomcat to 7.0.42 Upgrade PHP to 5.5.3

Update the PHP generation code in our custom build of SWIG to address any API changes caused by moving to PHP 5.5:

• function_entry has been changed to zend_function_entry
• The zend_rsrc_list_get_rsrc_type() function now returns const char* instead of char*

Update our zip distributions of Apache, PHP and Tomcat under Installer\Support to these new versions

• The 2.4.6 VC11 release of httpd from (​http://www.apachelounge.com/download/)
• The 5.5.3 VC11 thread-safe release of PHP from (​http://windows.php.net/download/)

For this upgrade, we will also streamline the build system and reduce the checkout footprint as follows:

• For Windows/Linux: Do not check in a full unpacked source distribution of PHP into Oem. Instead check in the PHP 5.5.3 tarball under Oem\LinuxApt
• For Windows: Also we only check-in 32-bit/64-bit php5ts.lib and any modified headers (for ACE compatibility) under Oem\php
• For Windows: Also check-in 32-bit/64-bit libs for httpd and any modified headers (for ACE compatibility) under Oem\httpd
• For Windows: Add a new prepare_webtier_components.bat to extract these tarballs (if necessary) and overlay our checked-in lib/header files on top.
• For Windows: Modify setenvironment.bat/setenvironment64.bat to define the following environment variables:
  • PHP_SRC - The path to do the extracted PHP source
  • PHP_LIB - The path to where php5ts.lib is located
  • HTTPD_SRC - The path to the extracted httpd source
  • HTTPD_LIB - The path to where the httpd lib files are located
• For Windows: Modify the include/linker paths of the following projects to point to these environment variables:
  • Oem
    • SQLitePhpApi
  • WebTier
    • ApacheAgent
    • PhpApi
    • PhpMapGuideApiEnvConfig
• For Linux: Check in tarballs of apr and apr-util under Oem\LinuxApt, which is now needed to build httpd 2.4 with the existing --with-included-apr option.
• For Linux: Modify the root configure.in to parameterize the httpd and php source directories (as $(httpd_src) and $(php_src) respectively). If desired, such paths can be overridden with --with-httpd=/path/to/httpd/source and --with-php=/path/to/php/source parameters to the main ./configure script.
• For Linux: Modify include/library paths in Makefile.am to use these new path variables
• For Linux: Oem\LinuxApt\build_apt.sh will be modified to:
  • Also build PHP from the checked-in tarball
  • Only start httpd and tomcat if the --start-httpd and --start-tomcat switches have been passed along to build_apt.sh. The reason being, this is normally built before Oem and MapGuide itself are built, so starting httpd and tomcat at this point in time is somewhat meaningless.

By using environment variables for Apache and PHP, it will make future Apache/PHP upgrades simpler and allows for Linux builds the opportunity to compile and link against the system installed versions of Apache and PHP if available (an important consideration should we ever want to re-introduce MapGuide into the OSGeo LiveDVD where disk space is a premium)

These environment variables must be set (manually or by setenvironment.bat/setenvironment64.bat) before any of the aforementioned projects can be built in the Visual Studio IDE. This is already the case with the JavaApi and JavaApiEx projects in the WebTier (which require JAVA_HOME to be set), so this should not be anything new.

With everything in the MapGuide stack (including FDO) now built under the same compiler, we should also now be able to stop bundling and requiring installation of the Visual C++ 2008 and 2010 runtime libraries as pre-requisite installations for smaller installer size. This will be done once FDO has completed its VS 2012 migration, ensuring everything is on the same compiler.

Moving to PHP 5.5.x introduces some subtle changes in behaviour of the PHP GD extension (used by QuickPlot in both AJAX and Fusion viewers):

• North arrow does not render in a QuickPlot if specified and will create an invalid image if composited on top of the map image (rotated or not)
• The final image has black borders

Such code will also be fixed to work as before with PHP 5.5

Implications

The MapGuide API itself will not change with this upgrade, but there are underlying changes in the Apache/PHP platform that users/developers should be aware of

Developers of MapGuide PHP applications that are using custom/external PHP 5.3 extensions (ie. Not included with the MapGuide installer) will need to look for PHP 5.5 supported equivalents.

PHP developers should be mindful about what has changed in the PHP platform itself and its extensions since 5.3 and make any changes in their application code. Migration guides for (5.3 to 5.4) and (5.4 to 5.5) are included below for reference:

• ​http://php.net/manual/en/migration54.php
• ​http://php.net/manual/en/migration55.php

Similarly, any custom configuration modifications to httpd.conf may need changes/migrations to ensure compatibility with httpd 2.4

• ​https://httpd.apache.org/docs/2.4/upgrading.html

The httpd.conf template that we bundle with the installer has already been updated to ensure there are no incompatible settings or directives.

Test Plan

Build and run on Windows and Linux. Ensure that components using PHP or Java function as before:

• The PHP AJAX Viewer
• The Java AJAX Viewer
• The PHP backend for Fusion trunk
• The MapGuide Site Administrator
• The Feature Source schema report.

Verify all tests pass with the existing MapGuide API PHP test runner.

Funding / Resources

Community