| Author: | Jeff McKenna |
|---|---|
| Contact: | jmckenna at gatewaygeomatics.com |
| Revision: | $Revision: 8459 $ |
| Date: | $Date: 2009-01-27 10:13:56 -0800 (Tue, 27 Jan 2009) $ |
Table of Contents
The PHP/MapScript module is a PHP dynamically loadable module that makes MapServer’s MapScript functions and classes available in a PHP environment.
The original version of MapScript (in Perl) uses SWIG, but since SWIG does not support the PHP language, the module has to be maintained separately and may not always be in sync with the Perl version.
The PHP module was developed by DM Solutions Group and is currently maintained by Mapgears.
This document assumes that you are already familiar with certain aspects of your operating system:
PHP MapScript was originally developed for PHP-3.0.14 but after MapServer 3.5 support for PHP3 has been dropped and as of the last update of this document, PHP 4.3.11 or more recent was required (PHP5 is well supported).
The best combinations of MapScript and PHP versions are:
Unix
Windows
Note
When setting up PHP on Windows, make sure that PHP is configured as a CGI and not as an Apache module because php_mapscript.dll is not thread-safe and does not work as an Apache module (See the Example Steps of a Full Windows Installation section of this document).
Building on a Linux Box
NOTE: For UNIX users, see the README.CONFIGURE file in the MapServer source, or see the Compiling on Unix HowTo.
Building on Windows
Simply copy the file php4_mapscript.dll to your PHP4 extensions directory (pathto/php/extensions)
Using phpinfo()
To verify that PHP and PHP/MapScript were installed properly, create a ‘.php’ file containing the following code and try to access it through your web server:
<HTML>
<BODY>
<?php
if (PHP_OS == "WINNT" || PHP_OS == "WIN32")
{
dl("php_mapscript.dll");
}
else
{
dl("php_mapscript.so");
}
phpinfo();
?>
</BODY>
</HTML>
If PHP and PHP/MapScript were installed properly, several tables should be displayed on your page, and ‘MapScript’ should be listed in the ‘Extensions’ table.
Using MS4W (MapServer for Windows)
Manual Installation Using Apache Server
Download the Apache Web Server and extract it to the root of a directory (eg. D:/Apache).
Download PHP4 and extract it to your Apache folder (eg. D:/Apache/PHP4).
Create a temp directory to store MapServer created GIFs. NOTE: This directory is specified in the IMAGEPATH parameter of the WEB Object in the Mapfile reference. For this example we will call the temp directory “ms_tmp” (eg. E:/tmp/ms_tmp).
Locate the file httpd.conf in the conf directory of Apache, and open it in a text viewer (eg. TextPad, Emacs, Notepad).
In the Alias section of this file, add aliases to the ms_tmp folder and any other folder you require (for this example we will use the msapps folder):
Alias /ms_tmp/ "path/to/ms_tmp/"
Alias /msapps/ "path/to/msapps/"
In the ScriptAlias section of this file, add an alias for the PHP4 folder.
ScriptAlias /cgi-php4/ "pathto/apache/php4/"
In the AddType section of this file, add a type for php4 files.
AddType application/x-httpd-php4 .php
In the Action section of this file, add an action for the php.exe file.
Action application/x-httpd-php4 "/cgi-php4/php.exe"
Copy the file php4.ini-dist located in your Apache/php4 directory and paste it into your WindowsNT folder (eg. c:/winnt), and then rename this file to php.ini in your WindowsNT folder.
If you want specific extensions loaded by default, open the php.ini file in a text viewer and uncomment the appropriate extension.
Place the file php_mapscript.dll into your Apache/php4/extensions folder.
Installation Using Microsoft’s IIS
(please see the IIS Setup for MapServer document for uptodate steps)
Install IIS if required (see the IIS 4.0 installation procedure).
Install PHP and PHP/MapScript (see above).
Open the Internet Service Manager (eg. C/WINNT/system32/inetsrv/inetmgr.exe).
Select the Default web site and create a virtual directory (right click, select New/Virtual directory). For this example we will call the directory msapps.
In the Alias field enter msapps and click Next.
Enter the path to the root of your application (eg. “c:/msapps”) and click Next.
Set the directory permissions and click Finish.
Select the msapps virtual directory previously created and open the directory property sheets (by right clicking and selecting properties) and then click on the Virtual directory tab.
Click on the Configuration button and then click the App Mapping tab.
Click Add and in the Executable box type: path/to/php4/php.exe %s %s. You MUST have the %s %s on the end, PHP will not function properly if you fail to do this. In the Extension box, type the file name extension to be associated with your PHP scripts. Usual extensions needed to be associated are phtml and php. You must repeat this step for each extension.
Create a temp directory in Explorer to store MapServer created GIFs.
Note
This directory is specified in the IMAGEPATH parameter of the WEB Object in the Mapfile. For this example we will call the temp directory ms_tmp (eg. C:/tmp/ms_tmp).
Open the Internet Service Manager again.
Select the Default web site and create a virtual directory called ms_tmp (right click, select New/Virtual directory). Set the path to the ms_tmp directory (eg. C:/tmp/ms_tmp) . The directory permissions should at least be set to Read/Write Access.
| Q: | Is there any documentation available? |
|---|---|
| A: | The main reference document is the PHP MapScript reference, which describes all of the current classes, properties and methods associated with the PHP/MapScript module. To get a more complete description of each class and the meaning of their member variables, see the MapScript reference and the MapFile reference. The MapServer Wiki also has PHP/MapScript build and installation notes and some php code snippets. |
| Q: | Where can I find sample scripts? |
|---|---|
| A: | Some examples are included in directory mapserver/mapscript/php3/examples/ in the MapServer source distribution. A good one to get started is test_draw_map.phtml: it’s a very simple script that just draws a map, legend and scalebar in an HTML page. A good intermediate example is the PHP MapScript By Example guide (note that this document was created for an earlier MapServer version but the code might be still useful). The next example is the GMap demo. You can download the whole source and data files from the MapTools.org download page. |
| Q: | How can I tell that the module is properly installed on my server? |
|---|---|
| A: | Create a file called phpinfo.phtml with the following contents: <?php dl("php_mapscript.so");
phpinfo();
?>
Make sure you replace the php_mapscript.so with the name under which you installed it, it could be php_mapscript_46.so on Unix, or php_mapscript_46.dll on Windows You can then try the second test page mapserver/mapscript/php3/examples/test_draw_map.phtml. This page simply opens a MapServer .map file and inserts its map, legend, and scalebar in an HTML page. Modify the page to access one of your own MapServer .map files, and if you get the expected result, then everything is probably working fine. |
| Q: | I try to display my .phtml or .php page in my browser but the page is shown as it would it Notepad. |
|---|---|
| A: | The problem is that your PHP installation does not recognize “.phtml” as a PHP file extension. Assuming you’re using PHP4 under Apache then you need to add the following line with the other PHP-related AddType lines in the httpd.conf: AddType application/x-httpd-php .phtml
For a more detailed explanation, see the Example Steps of a Full Windows Installation section of this document. |
| Q: | I installed the PROJ.4, GDAL, or one of the support libraries on my system, it is recognized by MapServer’s “configure” as a system lib but at runtime I get an error: “libproj.so.0: No such file or directory”. |
|---|---|
| A: | You are probably running a RedHat Linux system if this happened to you. This happens because the libraries install themselves under /usr/local/lib but this directory is not part of the runtime library path by default on your system. (I’m still surprised that “configure” picked proj.4 as a system lib since it’s not in the system’s lib path...probably something magic in autoconf that we’ll have to look into) There are a couple of possible solutions:
I (Daniel Morissette) personally prefer option #2 because it is permanent and applies to everything running on your system. |
| Q: | Does PHP/MapScript have to be setup as a CGI? If so, why? |
|---|---|
| A: | Yes, please see the PHP/MapScript CGI page in the MapServer Wiki for details. |
| Q: | I have compiled PHP as a CGI and when PHP tries to load the php_mapscript.so, I get an “undefined symbol: _register_list_destructors” error. What’s wrong? |
|---|---|
| A: | Your PHP CGI executable is probably not linked to support loading shared libraries. The MapServer configure script must have given you a message about a flag to add to the PHP Makefile to enable shared libs. Edit the main PHP Makefile and add “-rdynamic” to the LDFLAGS at the top of the Makefile, then relink your PHP executable. Note: The actual parameter to add to LDFLAGS may vary depending on the system you’re running on. On Linux it is “-rdynamic”, and on *BSD it is “-export-dynamic”. |
| Q: | What are the best combinations of MapScript and PHP versions? |
|---|---|
| A: | The best combinations are:
|
| Q: | I am dynamically loading gd.so and php_mapscript.so and running into problems, why? |
|---|---|
| A: | The source of the problems could be a mismatch of GD versions. The PHP GD module compiles its own version of libgd, and if the GD library is loaded before the mapscript library, mapscript will use the php-specific version. Wherever possible you should use a gd.so built with the same GD as PHPMapScript. A workaround is to load the php_mapscript module before the GD module. |