PHP: Run-Time Environment for WASD

Contents

• Mark Berryman PHP Port
• CSWS PHP v2.0
• CSWS PHP v1.3
• CSWS PHP v1.2
• PHPWASD v2.0
• CSWS
• Installation
• Configure WASD
• Configure PHP
• Example Scripts
• Performance
• Command-line PHP
• Full Build
• Problems?
• Acknowlegements

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 ~10x (yes, an approximate ten 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 [C]SWS (OpenVMS Apache) PHP interpreter shareable image and so shares a set of PHP capabilities in common with OpenVMS Apache.

Mark Berryman PHP Port

This port is more complete and up-to-date than that provided by HP, and is always in-development. It supplements the HP kits with an updated engine and modules, and contains additional modules. Any feedback most welcome (even just "worked a treat!") to Mark Berryman at mark@theberrymans.com.

http://www.theberrymans.com/php_kits/

Based on PHP V5.2.6.

CSWS PHP is supported on Alpha (AXP) and Itanium (IA64) platforms.  It is not available for VAX.  The release notes state a minimum requirement of VMS V7.3-2 for Alpha and V8.2 for Itanium.

NOTE:  The initial release (May 2009) contains a "session management" extension (PHP_ROOT:[EXTENSIONS]PHP_SESSION.EXE) that appears to output spurious debug(?) information when initialised. This at the very least interferes with the required CGI response format. As a workaround PHPWASD optionally suppresses <stdout> during script startup until the first time it SAPI writes. To enable this define the following logical name:

$ DEFINE /SYSTEM PHPWASD$ABSORB_PRE_WRITESAPI TRUE

Based on PHP V4.3.10.

This is the previous release of CSWS PHP is supported on Alpha (AXP) and Itanium (IA64) platforms.  It is not available for VAX.  The release notes state a minimum requirement of VMS V7.3-2 for Alpha and V8.2 for Itanium.

CSWS PHP v1.2

Based on PHP V4.3.2.

This is the earliest release of CSWS PHP available and is suitable for VMS V7.2-2 on Alpha.

Alpha 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.<arch>.BIN]PHP.EXE -v
%IMGACT-F-SYMVECMIS, shareable image's symbol vector table mismatch
-IMGACT-F-FIXUPERR, error when PHPSHR referenced DECC$SHR

This version provides no additional functionality to that of v1.3. This release required a minor data structure tweak to make it compatible with CSWS PHP V2.0 and confirmed its suitability via WASD field testing.

The following table explains the directory layout and content for WASD PHP.

Directory	Purpose
HT_ROOT:[SRC.PHP]	Source code for PHPWASD. Contains nothing from the CSWS PHPkit.
HT_ROOT:[PHP.AXP] HT_ROOT:[PHP.IA64]	Location of the architecture independent 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 [.SCRIPTS] for example) via mappings.
HT_ROOT:[AXP-BIN] HT_ROOT:[IA64-BIN]	PHP interface; PHPWASD.EXE image

PHPWASD has been developed and tested on VMS V8.3 using the ODS-5 dependent PHP source kit available from http://h71000.www7.hp.com/openvms/products/ips/apache/csws_source.html.

PHPWASD v1.3 introduces a number of enhancements over previous versions.

• Uses a CGI response (rather than NPH) allowing the server (v9.0.2 and later) to gzip compress (reducing transmission size and time) and/orchunk the output (improving connection persistence).

• Provides for a secondary PHP.INI file.  This allows a site-wide, primary PHP.INI (usually in PHP_ROOT:[000000]PHP.INI) to specify the fundamental site PHP configuration and then allow the secondary, perhaps per-script/application configuration file to modify those basics to suit.  This means the secondary initialization files can be far smaller and simpler than they might otherwise.

• Allows the location of the secondary initialization file to be specified by mapping rule.

• Allows PHP.INI directives to be specified by mapping rule, allow fine tailoring of script processing.

• Automatically translates SCRIPT_FILENAME and PATH_TRANSLATED to Unix-style syntax.

• Introduces a "watch" mode, allowing some debugging of the server/script interaction.

PHPWASD v1.2 dot-point releases added file-system syntax handling enhancements supporting Unix-style-derived applications.

• Perform a chdir() to the Unix-style syntax script location or as specified by the script=default=<location> mapping rule.  This allows include fils, etc., to use relative path specifications to get to other parts of the application source (e.g. ../include/fred.php).

• Allowed to SCRIPT_FILENAME to be specified in Unix-style syntax to support the WASD v9.0 script=syntax=unix mapping rule.  This feature was added to allow PHP applications expecting all request parameter file specifications (e.g. PATH_TRANSLATED, SCRIPT_FILENAME) to be in a slash-separated format to be supported.

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.AXP.BIN] HT_ROOT:[PHP.IA64.BIN]
[APACHE.PHP.BIN]PHPSHR.EXE	HT_ROOT:[PHP.AXP.BIN] HT_ROOT:[PHP.IA64.BIN]
[APACHE.PHP.EXTENSIONS]*.EXE	HT_ROOT:[PHP.AXP.EXTENSIONS] HT_ROOT:[PHP.IA64.EXTENSIONS]
[APACHE.PHP.SCRIPTS]*.PHP	HT_ROOT:[PHP.AXP.SCRIPTS] HT_ROOT:[PHP.IA64.SCRIPTS]

PHP extensions (shared images) available with versions 2.0, 1.3 and 1.2:

BCMATH  BZ2  CALENDAR  CTYPE  DBA  EXIF  FTP  GD***  ICONV  LDAP  MHASH  MYSQL*  OCI8  ODBC  OPENSSL  OPENVMS*  ORACLE  PCRE  PHP_GD**  POSIX  SESSION  SOCKETS  XML  ZIP  ZLIB
  ^*new with v1.2
  ^**new with v1.3, replace by GD with v2.0
  ^**new with v2.0

1. It is suggested that any existing PHPWASD kit be renamed out of the way before installing this kit so there can be no interactions between kit contents.  After successful installation the old kit may be deleted.

   $ RENAME HT_ROOT:[000000]PHP.DIR HT_ROOT:[000000]PHP_nnn.DIR
   $ RENAME HT_ROOT:[SRC]PHP.DIR HT_ROOT:[SRC]PHP_nnn.DIR
   

2. Obtain the PHPWASD kit from (or one of the mirror sites)

   http://wasd.vsm.com.au/wasd/

3. Obtain the platform-specific CSWS_PHP v2.0 PCSI kit from

   http://h71000.www7.hp.com/openvms/products/ips/apache/csws_php.html

   Use an UPDATE kit if available.

4. Using the CSWS PHP v2.0 PCSI kit location perform the following WASD build

   $ @HT_ROOT:[SRC.PHP]INSTALL kit:[location]

   Do not have multiple PHP kits in this path

   Note that this performs a link-only build. It is also possible to do a full build (compilation) and then an INSTALL.

5. Configure the Web server

6. Configure the PHP environment

7. Start scripting  :^)  Try the example scripts.

8. With the default configuration PHP script files are placed into [CGI-BIN] by the INSTALL.COM procedure (examples from [SRC.PHP]WEBSERVERSPY.PHP and the architecture dependent [PHP.AXP.SCRIPTS]*.PHP or [PHP.IA64.SCRIPTS]*.PHP ).

9. When you're satisfied you want to keep it add

   $ @HT_ROOT:[SRC.PHP]PHP_STARTUP.COM

   (or the equivalent) to your system/Web startup procedures

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 10% of CGI (yes, that's correct, by a factor 10).  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.

PHPWASD.EXE or PHPWASD.COM?

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.

Configuration and Mapping

One or more of the following approaches can be implemented.

• Server global configuration (HTTPD$CONFIG) can be 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
  

• 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 /cgi-bin/* /cgi-bin/*
  exec+ /cgiplus-bin/* /cgi-bin/*
  exec /php-bin/* (@cgi-bin:[000000]phpwasd.com)/cgi-bin/* script=query=relaxed
  

• Alternatively, 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
  

• The following rule would allow .php type files anywhere in the mapped directory structure to be executed. This may be what is desired but might be dangerous in some circumstances.  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
  

No PHP or Zend Logos?

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) and may similarly for other PHP scripts.  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

PHP on ODS-5 Volumes

For scripts requiring extended file specification (EFS, located on ODS-5 volumes) the script path needs to be mapped as ODS-5.

set /**.php* script=query=relaxed ods=5

When a script environment is mapped as residing on an ODS-5 volume, any VMS-syntax file specifications contained in PATH_TRANSLATED and SCRIPT_NAME are automatically translated to Unix-style syntax.  This has been demonstrated to better support PHP applications derived from such environments, in particular allowing relative directory references.  This occurs whether or not the path is SET using script=syntax=unix.

For example; by default a request's underlying CGI variables might be:

REQUEST_URI	/php-bin/php_info.php/ht_root/src/php/
PATH_INFO	/ht_root/src/php/
PATH_TRANSLATED	HT_ROOT:[SRC.PHP]
SCRIPT_NAME	/php-bin/php_info.php
SCRIPT_FILENAME	PHP-BIN:[000000]PHP_INFO.PHP

After mapping being on ODS-5 and subsequent translation they are presented 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

Script Default or Home Directory

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]"

"Watch" Mode

This is a basic facility to assist in debugging the interactions between the WASD server, PHPWASD scripting engine, script activation and input/output.  It does not provide for debugging of the script itself but may be of some elementary assistance when investigating the environment the script is activating under.  There are a number of methods for activating "watch" mode.

• Defining the logical name PHPWASD$WATCH_SCRIPT_NAME to contain a (case-sensitive) string from the SCRIPT_NAME variable.

  $ define /system phpwasd$watch_script_name "php_info"
  

• Defining the logical name PHPWASD$WATCH_REMOTE_ADDR to contain the IP address of the "watching" browser.

  $ define /system phpwasd$watch_remote_addr "192.168.0.2"
  

• Adding the string "#watch" to the first line of the PHP script.
  

  <?php #watch
  echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
  phpinfo (INFO_ALL);
  ?>
  

• Having a string "#watch:remote_addr=..." in the first line of the PHP script, specifying the IP address of the "watching" browser.
  

  <?php #watch:remote_addr=192.168.0.2
  echo "<h1><center>Testing the PHPINFO () function</center></h1><br>\n";
  phpinfo (INFO_ALL);
  ?>
  

When either of the logical names is defined without the other each operates to enable "watch" completely independently.  When defined concurrently both must match for "watch" to be enabled.   For example; when PHPWASD$WATCH_SCRIPT_NAME is defined only that script is "watch"ed; when PHPWASD$WATCH_REMOTE_ADDR is defined, all scripts activated by the specified host are "watch"ed; when both are defined only the specified script can be "watch"ed by the specified host.  Similar (but different :-) constraints apply to the script-embedded string.

A WATCH statement contains a statement number, timestamp, and then some free-form text (that hopefully is self-explanatory).  WATCH output can also comprise a hex-dump of a block of data.

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.

Remember that extensions are by default disabled so to employ some of the more useful facilities in PHP (.e. SSL, LDAP, MYSQL, etc.) the extension needs to be enabled in PHP.INI and the scripting engine restarted using $HTTPD/DO=DCL=PURGE.

Mappings rules configure on a per-request basis.  Logicals name values are loaded once at persistent PHPWASD engine startup.  The content of what they point at (in the case of files) is loaded with each request.

PHPWASD$INI

The PHP engine has a set of default configuration parameters and so can be used without specific configuration.  This not a tutorial on which changes should be made for any give circumstance, just how to pass those changes into the PHPWASD scripting engine.  To change the defaults a configuration file PHP.INI should be provided.  The default location of this for CSWS and WASD is

PHP_ROOT:[000000]PHP.INI

A default version is provided in

HT_ROOT:[SRC.PHP]PHP.INI

and may be copied to the above location.

To use a PHP.INI  from a location other than the CSWS PHP default define the logical name PHPWASD$INI to locate the file.  This logical name can be in any table the scripting process can access (e.g. process, job, system).

PHPWASD$INI2

PHPWASD also has a secondary PHP.INI which contains directives that override those from the primary PHP.INI.  This can be useful when maintaining the site-wide PHP configuration in the primary PHP.INI while placing only those directives required to be added or modified for the particular application.  To have the PHPWASD engine process this file define the logical name PHPWASD$INI2 to contain the location of the file.  This can be defined in any table the scripting process can access (e.g. process, job, system).  To suppress use of the primary PHP.INI file and rely entirely on the secondary for configuration define the primary logical name to the NL: device.

$ DEFINE PHPWASD$INI NL:

PHPWASD$INIS

To specify PHP.INI directives directly (and avoid the overhead of file processing) the logical name PHPWASD$DEFINE can be defined.  The format for this string is name="value"[;name="value"], where a semicolon is used to separate directives.  Any directive used in this logical overrides the same directive in the primary and secondary PHP.INI.  This is an example of such a logical value string and it's definition (continued for printed page clarity).

short_open_tag=1 ; expose_php=0 ; include_path="/php/application3/include"

$ DEFINE PHPWASD$INIS "short_open_tag=1 ; expose_php=0 ; include_path=""/php/application3/include"""

It is possible to pass parameters to PHP scripts and applications using the script=param=(name=value) mapping rule.  The PHPWASD scripting engine checks for a number of reserved identifiers and will use the contents of those present to perform the indicated function.  The primary PHP.INI cannot be supplied via mapping rule due to PHP module startup requirements.

Parameter Name	Purpose
PHP_INI	Provides the location for the primary PHP.INI configuration file.
PHP_INI2	Provides the location for the secondary PHP.INI configuration file.
PHP_INIS	Allows the specification of a value for any of the configuration directives allowed in PHP.INI.  The format for these parameters is name="value"[;name="value"], where a semi-colon is used to separate directives. See examples below.

The first example shows the specification of a primary PHP.INI file, the second of a secondary PHP.INI file, and the third the use of a configuration directive string.

set /php/application_a/* script=param=(PHP_INI="php:[application_a]php.ini")

set /php/application_b/* script=param=(PHP_INI2="php:[application_b]php.ini")

# continuation lines used for printed page clarity
set /php/application_c* script=param=(PHP_INIS=\
'short_open_tag=1 ; expose_php=0 ; include_path="/php/application_c/include"')

After configuration the following scripts may be used to confirm the environment is functioning.

• /cgi-bin/php_rules.php   (or rather, PHPWASD rules!)
• /cgi-bin/php_info.php   (no PHP or Zend logos?)
• /cgi-bin/php_openvms.php
• /cgi-bin/php_calendar.php
• /cgi-bin/php_odbc.php
• /cgi-bin/webserverspy.php

The performance of PHPWASD is quite respectable.  This table shows some results on an AlphaServer 4100 5/400, running VMS V7.3-2, HP TCP/IP Services 5.4, with WASD 9.0 and PHPWASD v1.3, CSWS 1.3 and CSWS PHP 1.2, using the ApacheBench tool.

Environment	Path	Req/Sec
WASD CGI	/cgi-bin/php_info.php /cgi-bin/php_rules.php	6 9
WASD RTE	/php-bin/php_info.php /php-bin/php_rules.php	62 82
CSWS mod_php	/php/php_info.php /php/php_rules.php	14 16

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"

be used as a non-persistent CGI scripting engine if desired.

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.

http://h71000.www7.hp.com/openvms/products/ips/apache/csws_source.html

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?

• With the PHPWASD script ... Mark.Daniel@wasd.vsm.com.au  (A pox on the houses of all SPAmers. Make that two poxes.)
• With the CSWS PHP engine ... (perhaps) HP OpenVMS Support
• The info-WASD mailing list
• http://forums1.itrc.hp.com/service/forums/familyhome.do?familyId=288
• comp.os.vms

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!