This is an interface to a PHP interpreter engine and environment for the WASD OpenVMS Web server. It is designed to be able to be used in standard CGI and CGIplus/RTE persistent scripting modes. The persistent modes provide a ~7x (yes, an approximately seven times) improvement in script activation times and reduced load on server and system. PHPWASD cannot be used interactively or at the command line, it is only for scripting use. Note that this package does not contain the PHP engine, that has to be obtained and installed separately.
PHPWASD is linked against the CSWS (OpenVMS Apache) PHP interpreter
shareable image. It is anticipated that as bugfixed and improved (or at least
later) versions of these OpenVMS PHP engines become available the PHPWASD
interface will only require a relink to update (that's the plan anyway :^).
CSWS PHP v1.2
CSWS PHP is not supported on VAX . The release notes state a minimum requirement of VMS V7.2-2.
VMS Version Minimum C RTL ECO Version V7.2-2 ACRTL-V0400 V7.3 ACRTL-V0600 V7.3-1 ACRTL-V0300 V7.3-2 (none)
An incompatible C RTL can easily be diagnosed:
$ MCR HT_ROOT:[PHP.BIN]PHP.EXE -v %IMGACT-F-SYMVECMIS, shareable image's symbol vector table mismatch -IMGACT-F-FIXUPERR, error when PHPSHR referenced DECC$SHR
PHPWASD has been developed and tested on VMS V7.3-2 using an ODS-5
dependent PHP source kit privately made available (with thanks) and dated
6-NOV-2003.
PHPWASD v1.2
For those who have used PHPWASD v1.0 but not PHPWASD v1.1, please note that this kit has a significantly different structure in line with changes introduced with WASD v8.1. This effectively decouples the source and executable components of the kits.
Directory Purpose HT_ROOT:[SRC.PHP] Source code for PHPWASD. Contains nothing from the CSWS PHP kit. HT_ROOT:[PHP] Location of PHP_ROOT logical name. Executable components of the scripting environment (e.g. PHPSHR.EXE, extension shareable images). The [.SCRIPTS] directory could be used for .PHP files with appropropriate mappings. HT_ROOT:[CGI-BIN] Contains the .PHP script files. This may be changed (to [PHP.SCRIPTS] for example) via mappings. HT_ROOT:[AXP-BIN] PHP interface; PHPWASD.EXE image.
CSWS (OpenVMS Apache)
Currently (CSWS PHP V1.2) based on PHP 4.3.2. The procedure INSTALL.COM will use the PCSI kit as a source of required files, extracting and installing them in a HT_ROOT:[PHP] directory tree (that parallels the CSWS tree). The following files are extracted from the CSWS PHP kit and placed into the WASD directory structure. Of course there is no reason why this tree cannot be relocated (with appropriate startup procedure changes).
CSWS_PHP WASD [APACHE.PHP.BIN]PHP.EXE HT_ROOT:[PHP.BIN] [APACHE.PHP.BIN]PHPSHR.EXE HT_ROOT:[PHP.BIN] [APACHE.PHP.EXTENSIONS]*.EXE HT_ROOT:[PHP.EXTENSIONS] [APACHE.PHP.SCRIPTS]*.PHP HT_ROOT:[PHP.SCRIPTS]
The CSWS PHP 1.2 kit contains a significant number of PHP extensions:
BCMATH BZ2 CALENDAR CTYPE DBA EXIF FTP ICONV LDAP MHASH MYSQL* OCI8 ODBC OPENSSL OPENVMS* ORACLE PCRE POSIX SESSION SOCKETS XML ZIP ZLIB
*new with v1.2
Installation
$ RENAME HT_ROOT:[SRC]PHP.DIR HT_ROOT:[SRC]PHP112.DIR
http://wasd.vsm.com.au/wasd/and install it as per the kit instructions.
http://h71000.www7.hp.com/openvms/products/ips/apache/csws.html
$ @HT_ROOT:[SRC.PHP]INSTALL kit:[location]Note that this performs a link-only build - full build instructions.
With the default configuration PHP script files will need to be placed into [CGI-BIN] (examples from [SRC.PHP]WEBSERVERSPY.PHP and [PHP.SCRIPTS]*.PHP).
$ @HT_ROOT:[SRC.PHP]PHP_STARTUP.COM(or the equivalent) to your system/Web startup procedures
Configure WASD
For VMS V7.3 and later the v1.2.3 (and later) PHPWASD.EXE can internally enable the required DECC RTL features for suitably handling Extended File System (EFS) specifications for PHP processing (e.g. a.file.name.with.multiple.periods.php, in escaped format as a^.file^.name^.with^.multiple^.periods.php).
VMS (or CRTL) versions earlier than V7.3 requires the use of the PHPWASD.COM procedure rather than the PHPWASD.EXE image. If the PHP interpreter is required to process Extended File System (EFS) files specifications this procedure will define the required DECC RTL environment supporting this capability before activating the PHP engine. Direct use of the PHPWASD.EXE image is still supported so no changes are required to existing sites unless EFS functionality is required.
Server global configuration (HTTPD$CONFIG) is used to indicate which file types should activate the PHP interpreter and how perform non-script access.
# HTTPD$CONFIG [DclScriptRunTime] .PHP @CGI-BIN:[000000]PHPWASD.COM [AddType] .INI text/plain initialization file .PHP text/plain PHP source .PHPS text/plain PHP source .PHTML text/plain PHP source
There are various ways to employ the WASD PHP interpreter. It can be used in vanilla CGI mode, or in persistent CGIplus/RTE mode. Benchmarking indicates the CGIplus/RTE use reduces activation time to 15% of CGI (yes, that's correct, by a factor 7). There are subtle differences in the way CGIplus and RTE parse and provide the PATH_INFO data. See the "WASD Scripting Overview" for more detail. The following rules require the PHP script files to be located in the site administrator controlled /cgi-bin/ path. This may be changed using appropriate rules.
# HTTPD$MAP for CGI, CGIplus or RTE usage (perhaps for comparison) exec /php-bin/* (@cgi-bin:[000000]phpwasd.com)/cgi-bin/* script=query=relaxed .. exec /cgi-bin/* /cgi-bin/* exec+ /cgiplus-bin/* /cgi-bin/*
or, to automatically map scripts ending in ".php" to the RTE engine
# HTTPD$MAP for automatic RTE usage map /cgi-bin/*.php* /php-bin/*.php* exec /php-bin/* (@cgi-bin:[000000]phpwasd.com)/cgi-bin/* script=query=relaxed .. exec /cgi-bin/* /cgi-bin/* exec+ /cgiplus-bin/* /cgi-bin/*
The following rules allow .PHP type files anywhere in the mapped directory structure to be executed. This means that any document author can script using PHP. This may be what is desired but can be dangerous. PHP provides for this type of usage. Please familiarise yourself with it's requirements and controls. As an additional safeguard it is suggested that PHP scripts be executed under a non-server account. This is the default configuration for WASD v8.1 and later. If not using the default setup it can also be done using the WASD PERSONA capabilities (see the "Technical Overview" if unfamiliar with this functionality and configuration).
exec /web/*.php* /web/*.php* script=as=OTHER-ACCOUNT
By default WASD validates query strings in it's own inimitable fashion (correctly in the author's HO). This validation interferes with the requesting of the internally generated PHP and Zend logos (as are included by the php_info.php script). To disable query string validation by WASD include the following HTTPD$MAP rule at an appropriate location before mapping of PHP scripts.
set /**.php* script=query=relaxed
For scripts requiring extended file specification (and located on ODS-5 volumes) the script path needs to be mapped as ODS-5.
# HTTPD$MAP for RTE usage for extended file specification exec /php-bin/* (@cgi-bin:[000000]phpwasd.com)/cgi-bin/* script=query=relaxed ods=5
The PHPWASD engine will by default chdir() to the Unix-style syntax equivalent of the directory containing the PHP script file. It also does a setenv() against the environment variable PATH to this same string. This location may be explicitly provided using the value of CGI variable SCRIPT_DEFAULT and set on a per-script or general basis using the mapping rule set script=default=<string> (minimum WASD v8.4.3). It will accept either VMS and Unix specifications depending on the requirements of the script itself.
set /php-bin/mumble.php* script=default="/mumble_device/000000" set /php-bin/mumble.php* script=default="mumble_device:[000000]"
If the PHP script prefers or requires it's PATH_TRANSLATED and SCRIPT_NAME to be provided in Unix-style syntax (perhaps to allow relative directory manipulations) use the set script=syntax=unix mapping rule (minimum WASD v9.0.0).
set /php-bin/mumble.php* script=syntax=unix
By default these CGI variables are presented by php_info.php as:
_SERVER["REQUEST_URI"] /php-bin/php_info.php/ht_root/src/php/ _SERVER["PATH_INFO"] /ht_root/src/php/ _SERVER["PATH_TRANSLATED"] HT_ROOT:[SRC.PHP] _SERVER["SCRIPT_NAME"] /php-bin/php_info.php _SERVER["SCRIPT_FILENAME"] PHP-BIN:[000000]PHP_INFO.PHP
After mapping with script=syntax=unix they are provided as:
_SERVER["REQUEST_URI"] /php-bin/php_info.php/ht_root/src/php/ _SERVER["PATH_INFO"] /ht_root/src/php/ _SERVER["PATH_TRANSLATED"] /HT_ROOT/SRC/PHP/ _SERVER["SCRIPT_NAME"] /php-bin/php_info.php _SERVER["SCRIPT_FILENAME"] /PHP-BIN/000000/PHP_INFO.PHP
Configure PHP
The author of PHPWASD is only a PHP novice, so anything in this section should be taken with a large pinch of salt. Any scripting environment should be approached with due caution and diligence. Please ensure you are familiar with PHP and it's security requirements in particular before betting the company on anything in this section.
The PHP engine has a set of default configuration parameters and so can be used without specific configuration. To change the specifics a configuration file name PHP.INI may be provided. The default location of this for CSWS and WASD is
PHP_ROOT:[000000]PHP.INIA default version is provided in
HT_ROOT:[SRC.PHP]PHP.INIand may be copied to the above location.
Example Scripts
After configuration the following scripts may be used to confirm the environment is functioning.
Performance
The performance of PHPWASD is quite respectable. This table shows some v1.1 results on the author's development system, a Digital AlphaStation 500/333 with 1 CPU and 256MB running VMS V7.3-1, with WASD 8.1, CSWS 1.3 and CSWS PHP 1.1, using the ApacheBench tool.
Environment Path Req/Sec WASD CGI /cgi-bin/php_info.php
/cgi-bin/php_rules.php5
6WASD RTE /php-bin/php_info.php
/php-bin/php_rules.php34
52CSWS mod_php /php/php_info.php
/php/php_rules.php15
18
Command-line PHP
The PHPWASD.EXE engine interface is only suitable for scripting use. It cannot be used outside of the CGI environment and certainly not from the command line. It is often useful to have a PHP tool that can be used in such a manner and the CSWS kit provides one. To access this image assign a symbol (foreign command) in the (SY)LOGIN.COM procedure.
$ PHP = "$HT_ROOT:[PHP.BIN]PHP.EXE"(This can also be used as a CGI scripting engine if desired. See PHPWASD.C for detail.)
Full Build
The PHPWASD kit comes with object code that allows the image to be linked against the CSWS PHP shareable image. To compile the PHPWASD image at least the CSWS PHP header files are required. Basically this means the full source kit needs to be installed. This may be obtained from
http://www.openvms.compaq.com/openvms/products/ips/apache/csws_source.htmland by default could be placed in HT_ROOT:[SRC.PHP.PHP...] although it is possible to build with it located elsewhere. Please check the BUILD_PHPWASD.COM procedure for detail. Note that the CSWS PHP v1.2 source kit must be located on an Extended File System (ODS-5) volume.
Problems?
Unfortunately the author of the PHPWASD interface is such a PHP novice he
is not in any position to answer queries about PHP "programming" or
usage. If there's an obvious behavioural problem with PHPWASD (preferably
diagnosed by someone with PHP experience) then he's it though.
Acknowlegements
Thanks to OpenVMS Engineering and the CSWS team for their efforts on PHP and Web technologies in general. Thanks also to the efforts of Dave Jones with his PHP port (usable with PHPWASD v1.0). Of course, thanks to the PHP development team!