PHP: Hypertext Preprocessor: WASD
 PHPWASD v1.1.1, 15th January 2002

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 (although other comparable versions and images should be possible, including the original CSWS PHP 1.0). 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 :^).

Currently CSWS PHP is Alpha (AXP) only. The release notes state a minimum requirement of VMS V7.2-2. PHPWASD has been developed and tested on VMS V7.3-1.

NOTE
This 10th January kit is an interim release while an issue with the CSWS v1.1 PHP shareable image is resolved. It appears as if PHP.INI directives are not being processed by the CSWS image. This version of PHPWASD contains a kludge to work around this. If it is a requirement to make any local configuration changes using PHP.INI settings then a logical name needs to be defined initiating the kludge behaviour and locating the file. 
  $ DEFINE /SYSTEM PHPWASD$KLUDGE PHP_ROOT:[000000]PHP.INI
The above example shows the default location of PHP.INI being used. Further detail on this issue is available in the description of PhpIniKludge() in PHPWASD.C.


PHPWASD v1.1

For those who have used PHPWASD v1.0, 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.

DirectoryPurpose
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.1) based on PHP 4.1.1. 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_PHPWASD
[APACHE.PHP.BIN]PHP.EXEHT_ROOT:[PHP.BIN]
[APACHE.PHP.BIN]PHPSHR.EXEHT_ROOT:[PHP.BIN]
[APACHE.PHP.EXTENSIONS]*.EXEHT_ROOT:[PHP.EXTENSIONS]
[APACHE.PHP.SCRIPTS]*.PHPHT_ROOT:[PHP.SCRIPTS]

The CSWS PHP 1.1 kit contains a significant number of PHP extensions:

BCMATH  BZ2  CALENDAR  CTYPE  DBA  EXIF  FTP  ICONV  LDAP  MHASH  OCI8  ODBC  OPENSSL  ORACLE  PCRE  POSIX  SESSION  SOCKETS  XML  ZIP  ZLIB
(shareable images in the format PHP_extension.EXE).


Installation

  1. It is suggested that any exisiting 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:[SRC]PHP.DIR HT_ROOT:[SRC]PHP10.DIR

  2. Obtain the WASDPHP kit from (or one of the mirror sites) 
      http://wasd.vsm.com.au/wasd/
    and install it as per the kit instructions.

  3. Obtain the CSWS_PHP PCSI kit from 
      http://www.openvms.compaq.com/openvms/products/ips/apache/csws_php.html

  4. Install the CSWS kit (partial) and perform the WASD build 
      $ @HT_ROOT:[SRC.PHP]INSTALL kit:[location]
    Note that this performs a link-only build - full build instructions.

  5. Configure the Web server

  6. Configure the PHP environment

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

    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).

  8. 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


Configure WASD

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.EXE
  [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.exe)/cgi-bin/*
  ..
  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
  if (!script-name:/php/*) map /cgi-bin/*.php* /php-bin/*.php*
  exec /php-bin/* (cgi-bin:[000000]phpwasd.exe)/cgi-bin/*
  ..
  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). 

  set /web/**.php* script=as=OTHER-ACCOUNT
  exec+ /web/**.php* /web/**.php*


Configure PHP

See NOTE with introduction.

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.INI
A default version is provided in 
  HT_ROOT:[SRC.PHP]PHP.INI
and 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 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.

EnvironmentPathReq/Sec
WASD CGI /cgi-bin/php_info.php
/cgi-bin/php_rules.php		 5
6
WASD RTE /php-bin/php_info.php
/php-bin/php_rules.php		 30
43
CSWS mod_php /php/php_info.php
/php/php_rules.php		 17
20


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.html
and by default should 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.


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!