GRASS and PHP
Running Grass modules through an Webserver
For some reasons, you may want to call Grass modules within a html page instead of using the command line or a GUI. One way - among others - is to execute them out of a php script.
In the following, a few notes how to procceed for writing your own code:
Check your php installation
Save this code snipped in your server directory under the filename "doihavephp.php" and call it with a web browser:
<?php phpinfo(); ?>
There you will see detailed informations upon your server's php installation. If you see nothing, please check http://www.php.net for details how to get and install php on your machine.
Define the environment settings
By default, there are only a few variables set in the server environment. Save the following snippet under "env.php" and see what is set as default values for your server.
<?php //enable all error messages error_reporting(E_ALL); //print a line of text as a header for the following output echo "<hr>env:<br>"; //execute the env command and redirect the output $handle = popen('"env" 2>&1', 'r'); //wait a while for the results. this is not clean, but works for the first attempt sleep("1"); //collect the response $read = fread($handle, 4096); //print the response - if response is incomplete, increment the sleep delay echo $read; //don't forget to close the handle pclose($handle); echo "<br>done.<hr>"; ?>
Note: %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/warning.gif Please be careful when modifying environment variables permanent in files like /etc/bash.bashrc. You may cause by accident security leaks. Please check with your IT manager how to grant security when your machine is visible to the internet.
The environment variables are set by using the *<verbatim>putenv("VARIABLE")</verbatim>* command. They are only valid during the runtime of the actual script, so you have to send the full set for each request.
<?php error_reporting(E_ALL); putenv("GRASS_WIDTH=900"); echo "<hr>env:<br>"; $handle = popen('"env" 2>&1', 'r'); sleep("1"); $read = fread($handle, 4096); echo $read; pclose($handle); echo "<br>done.<hr>"; ?>
The list shows some environment variables used by Grass modules. Please note, that the content has to be adapted to meet your system's specific setup and that it may be incomplete or partially false in some combinations.
|*Variable*|*Value*|*Note*| |GISBASE|/usr/local/grass-6.1.cvs| "...where the happy little creatures hide..." (Bob Ross)| |LD_LIBRARY_PATH|/usr/lib:/usr/local/grass-6.1.cvs/lib:/usr..|path to ALL required libraries| |GISRC|/gd/.grassrc6_php|Grass resource file -please see related paragraph below| |HOME|/tmp|| |GRASS_PERL|/usr/bin/perl|| |GIS_LOCK|$$||
Glynn clarified regarding GRASS_LD_LIBRARY_PATH:
You need to set LD_LIBRARY_PATH. GRASS_LD_LIBRARY_PATH is merely a saved copy so that the value can be restored if LD_LIBRARY_PATH is reset due to running a setuid/setgid executable (e.g. xterm). LD_LIBRARY_PATH is what the Linux loader actually uses to locate shared libraries.
Redirecting STDOUT and STDERR
When calling a function, you may either collect the output in a handle as shown in the example before or redirect it in a text file. The syntax for redirection is:
system("g.version > version.txt 2> version_err.txt");
Deleting prior output files
Remove output files immediately after use or before rewriting them to ensure that you will not work with old stuff in case of troubles.
system("rm -f version.txt");
system("rm -f version_err.txt");
The Grass Resource File
You may copy your .grassrc6 file to your script directory and e.g. name it .grassrc6_php. It contains the follwing lines and has to be adapted to fit into your setup:
GISDBASE: /gd GRASS_GUI: tcltk MAPSET: etopo5 LOCATION_NAME: smallworld MONITOR=PNG
I can't get outside a shell access to a mapset even when calling in advance g.access with grant for both user and group. When chowning the entire location directory to user www-data, it works, but then there is no longer access from the grass shell.
Glynn wrote: You can't select a mapset as the current mapset unless you actually own it. Having write permission isn't sufficient.
This check is implemented in G__mapset_permissions() and G__mapset_permissions2() in lib/gis/mapset_msc.c. You will have to modify those functions to disable the check if you want to be able to modify mapsets which you don't own.
If your web application only reads the data, you can create a single mapset directory owned by the account under which the PHP script runs, then either use g.mapsets or explicit map@mapset references to access maps in other mapsets.
Resources and examples
A Grass Map on the fly: http://grass.itc.it/spearfish/php_grassmap.php
Earthquake epicenters dynamically inserted: http://grass.itc.it/spearfish/php_grass_earthquakes.php
Many thanks to Glynn Clements, Markus Neteler and Sharyn Namnath for code and help!