?2 PHP: Hypertext Preprocessor: WASDHPHP:Hypertext Preprocessor:WASDCPHPWASDv1.3.2, 18th August 20055A
?

This is an5interface to a PHP interpreter engine and environmentFfor the WASD OpenVMS Web server.  It is designed to be able to beusedEin standard CGI and CGIplus/RTE persistent scripting modes.  The7persistent modes provide a ~10x (yes, an approximate ten times)improvement inFscript activation times and reduced load on server and system. PHPWASDCcannot be used interactively or at the command line, it is only forDscripting use.  Note that this package does not contain the PHPengine,that has to be"obtained and installed separately.

F

PHPWASD is linked3against the [C]SWS (OpenVMS Apache) PHP interpreterFshareable image and so shares a set of PHP capabilities in common withOpenVMS Apache.


CSWS PHP v1.2BCSWS PHP isLsupported on Alpha (AXP) and Itanium (IA64)Nplatforms.  It is not supported on VAX . The release notes state a;minimum requirement of VMS V7.2-2 for Alpha VMS.

> C K  8 =  6 =  8 =  8 8 
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)

E

An incompatible CRTL can easily be diagnosed:

N
$ 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
E

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


PHPWASD v1.3DFor those who3have used PHPWASD v1.0 but not later releases, notethatEthis kit has a significantly different structure in line with changesDintroduced with WASD v8.1. This effectively decouples the source and&executable components of the kits.

G H ' %  < 2  ; P  < 5  3 > 
DirectoryPurpose
HT_ROOT:[SRC.PHP]Source code for PHPWASD. Containsnothing 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]Qdirectory could be used for .PHP files with appropropriate mappings.
HT_ROOT:[CGI-BIN]Contains the .PHP script files. Thismay be changed (to[.SCRIPTS] for#example) via mappings.
HT_ROOT:[AXP-BIN]
HT_ROOT:[IA64-BIN]		PHP interface; PHPWASD.EXE image
.
EPHPWASD v1.2 dot-pointBreleases added file-system syntax handling enhancements supporting$Unix-style-derived applications.

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

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

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

    G
  • Uses a CGI response (rather than NPH) allowing the server (v9.0.2Dand later) to gzip compress2(reducing transmission size and time) and/or chunk the output (improvingconnection persistence).
    • 
  • A

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

    
    • 
  • +

    Allows the location of the secondary8initialization file to be specified by mapping rule.

    
    • 
  • G

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

    
    • 
  • F

    Automatically translates SCRIPT_FILENAME and PATH_TRANSLATED toUnix-style syntax.

    
    • ?
  • Introduces a "watch" mode, allowing some debugging of theserver/script interaction.
    
    • 
/CSWS(OpenVMS Apache)FCurrently (CSWS7PHP V1.2) based on PHP 4.3.2. The procedure INSTALL.COMCwill use the PCSI kit as a source of required files, extracting andEinstalling them in a HT_ROOT:[PHP] directory tree (that parallels theECSWS tree).  The following files are extracted from the CSWS PHPkit andEplaced into the WASD directory structure.  Of course there is noreasonEwhy this tree cannot be relocated (with appropriate startup procedure changes).

C & P  5 2  8 2  : 9  7 6 
CSWS_PHPWASD
[APACHE.PHP.BIN]PHP.EXEHT_ROOT:[PHP.AXP.BIN]
*HT_ROOT:[PHP.IA64.BIN]
[APACHE.PHP.BIN]PHPSHR.EXEHT_ROOT:[PHP.AXP.BIN]
*HT_ROOT:[PHP.IA64.BIN]
[APACHE.PHP.EXTENSIONS]*.EXEHT_ROOT:[PHP.AXP.EXTENSIONS]
1HT_ROOT:[PHP.IA64.EXTENSIONS]
[APACHE.PHP.SCRIPTS]*.PHPHT_ROOT:[PHP.AXP.SCRIPTS]
.HT_ROOT:[PHP.IA64.SCRIPTS]
E

The CSWS PHP 1.2(kit contains a significant number of PHP extensions:

R
BCMATH  BZ2 ECALENDAR  CTYPE  DBA  EXIF  FTP  ICONV 9LDAP  MHASH  MYSQL*  OCI8  ODBC 4OPENSSL  OPENVMS*  ORACLE  PCRE LPOSIX  SESSION  SOCKETS  XML  ZIP  ZLIB
I  *new with v1.2
Installation5
    F
  1. It is suggested that any exisiting PHPWASD kit be renamed out ofBthe way before installing this kit so there can be no interactionsEbetween kit contents.  After successful installation the old kitmay be deleted.
    d 
    $ RENAME HT_ROOT:[SRC]PHP.DIR HT_ROOT:[SRC]PHP_nnn.DIR
    
    2. 
  2. E

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

    & 
    http://wasd.vsm.com.au/wasd/
    
    3. 
  3. B

    Obtain the platform-specific CSWS_PHP v1.2 PCSI kit from

    >
    http://h71000.www7.hp.com/openvms/products/ips/apache/csws.html
    
    4. 
  4. K

    Using the CSWS PHP v1.2 PCSI kit location perform the following WASD build

    X 
    $ @HT_ROOT:[SRC.PHP]INSTALL kit:[location]
    
    5. L
  5. Note that this performs a link-only build - fullbuild instructions.
    6. 
  6. B

    Configure the Web server

    
    7. 
  7. F

    Configure the PHP environment

    
    8. 
  8. '

    Start scripting  :^) <Try the example scripts.

    
    9. 
  9. G

    With the default configuration PHP script files will need to beplaced;into [CGI-BIN] (examples from [SRC.PHP]WEBSERVERSPY.PHP and[PHP.SCRIPTS]*.PHP).

    
    10. 
  10. 9

    When you're satisfied you want to keep it add
    

    : 
    $ @HT_ROOT:[SRC.PHP]PHP_STARTUP.COM
    9(or the equivalent) to your system/Web startup procedures

    
    11. 
5
    
Configure WASD There are various5ways to employ the WASD PHP interpreter.  It canEbe used in vanilla CGI mode, or in persistent CGIplus/RTE mode. EBenchmarking indicates the CGIplus/RTE use reduces activation time toA10% of CGI (yes, that's correct, by a factor 10).  There aresubtleFdifferences in the way CGIplus and RTE parse and provide the PATH_INFOCdata.  See the "WASD Scripting Overview" for more detail.
>#

PHPWASD.EXE or PHPWASD.COM?


GFor VMS V7.3 and,later the v1.2.3 (and later) PHPWASD.EXE canFinternally enable the required DECC RTL features for suitably handlingBExtended File System (EFS) specifications for PHP processing (e.g.&a.file.name.with.multiple.periods.php,Lin escaped format as a^.file^.name^.with^.multiple^.periods.php).

VMS (or CRTL)5versions earlier than V7.3 requires the use of the PHPWASD.COM procedure rather than theFPHPWASD.EXE image.  If the PHP interpreter is required to processCExtended File System (EFS) files specifications this procedure willCdefine the required DECC RTL environment supporting this capabilityEbefore activating the PHP engine.  Direct use of the PHPWASD.EXEimageFis 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 global4configuration (HTTPD$CONFIG) can be used to indicateDwhich file types should activate the PHP interpreter and how performnon-script access.
    • 
N
# 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

    G
  • The following rules require the PHP script files to be located inthe siteBadministrator controlled /cgi-bin/ path.  This may be changedusing<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.
    • 
N
# HTTPD$MAP for automatic RTE usagemap /cgi-bin/*.php* /php-bin/*.php*exec /php-bin/* (@cgi-bin:[000000]phpwasd.com)/cgi-bin/*  script=query=relaxed

    
  • The followingBrule would allow .phptypefiles anywhere in the mapped directoryBstructure to be executed. This may be what is desired but might be1dangerous in some circumstances. PHP provides forthisGtype of usage.  Please familiarise yourself with it's requirementsandCcontrols.  As an additional safeguard it is suggested that PHPscriptsbe>executed under a non-server account.  This is the default configurationforEWASD v8.1 and later.  If not using the default setup it can alsobe doneusing>the WASD PERSONA capabilities (see the "Technical Overview" if;unfamiliar with this functionality and configuration).
    
    )
    style="font-family: monospace;">exec /web/**.php* /web/*.php*$script=as=OTHER-ACCOUNT
    
    • 
9

2

No PHP or Zend Logos?

By'default WASD validates query strings inFit's own inimitable fashion (correctly in the author's HO).  ThisEvalidation interferes with the requesting of the internally generated0PHP and Zend logos (as are included by the php_info.phpGscript) and may similarly for other PHP scripts.  To disable query%string validation by WASD include theEfollowing HTTPD$MAP rule at an appropriate location before mapping of PHP scripts.N
set /**.php* script=query=relaxed
=

PHP on ODS-5 Volumes


?

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

N
set /**.php script=query=relaxed ods=5
GWhen a script environment is mapped as residing on an ODS-5 volume, any?VMS-syntax file specifications contained in PATH_TRANSLATED andDSCRIPT_NAME are automatically translated to Unix-style syntax. EThis has been demonstrated to better support PHP applications derived.from such environments, in particular allowingCrelative directory references.  This occurs whether or not theNpath is SET using script=syntax=unix.
C

For example; by default aFrequest's underlyingDCGI variables might be:

=
4 + F ) 1 / 1 + 5 / <
REQUEST_URI/php-bin/php_info.php/ht_root/src/php/
PATH_INFO/ht_root/src/php/
PATH_TRANSLATEDHT_ROOT:[SRC.PHP]
SCRIPT_NAME/php-bin/php_info.php
SCRIPT_FILENAMEPHP-BIN:[000000]PHP_INFO.PHP
B

After mappingBbeing on ODS-5 and subsequent translation they are presented as:

=
4 6 F 4 1 : 1 6 5 : <
_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


F

The PHPWASD engineCwill by default chdir() totheGUnix-style syntax equivalent of the directory containing the PHP scriptBfile.  It also does a setenv() against the environmentvariableBPATH to this same string. This location may be explicitly providedFusing the value of CGI variable SCRIPT_DEFAULT and set on a per-script.or general basis using the mapping rule setFscript=default=<string> (minimum WASD v8.4.3).  It willacceptGeither VMS and Unix specifications depending on the requirements of thescript itself.


L

set /php-bin/mumble.php*2script=default="/mumble_device/000000"
Kset /php-bin/mumble.php* script=default="mumble_device:[000000]"



"Watch" Mode


@This is a basic facility to assist in debugging the interactionsDbetween the WASD server, PHPWASD scripting engine, script activationGand input/output.  It does not provide for debugging of the scriptFitself but may be of some elementary assistance when investigating theGenvironment the script is activating under.  There are a number ofmethods for activating "watch" mode.

    
  • ,

    Defining the logical name  PHPWASD$WATCH_SCRIPT_NAME Gto 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 8to contain the IP address of the "watching" browser.

    b 
    $ define /system phpwasd$watch_remote_addr "192.168.0.2"
    
    • 
  • J

    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);
    ?>
    
    • 
  • D

    Having a string "#watch:remote_addr=..." in the first line ofHthe 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);
    ?>
    
    • 
BWhen either of the logical names is defined without the other eachGoperates to enable "watch" completely independently.  When definedGconcurrently both must match for "watch" to be enabled.   ForFexample; when PHPWASD$WATCH_SCRIPT_NAME is defined only that script isA"watch"ed; when PHPWASD$WATCH_REMOTE_ADDR is defined, all scriptsDactivated by the specified host are "watch"ed; when both are definedGonly the specified script can be "watch"ed by the specified host. CSimilar (but different :-) constraints apply to the script-embedded string.

GA WATCH statement contains a statement number, timestamp, and then someGfree-form text (that hopefully is self-explanatory).  WATCH outputcan0also comprise a hex-dump of a block of data.
M

ConfigurePHP

B

The author of1PHPWASD is only a PHP novice, so anything in thisGsection should be taken with a large pinch of salt.  Any scriptingFenvironment should be approached with due caution and diligence. PleaseBensure you are familiar with PHP and it's security requirements inFparticular before betting the company on anything in this section.


DMappings rules configure on a per-request basis.  Logicals nameFvalues are loaded once at persistent PHPWASD engine startup.  TheCcontent of what they point at (in the case of files) is loaded witheach request.


PHPWASD$INI


F

The PHP engine has0a set of default configuration parameters and soEcan be used without specific configuration.  This not a tutorialFon which changes should be made for any give circumstance, just how toEpass those changes into the PHPWASD scripting engine.  To changethe defaults a@configuration file PHP.INI should be provided.  The defaultlocationof this for CSWS and WASD is

N
PHP_ROOT:[000000]PHP.INI
@A default!version is provided in :
HT_ROOT:[SRC.PHP]PHP.INI
Aand may be!copied to the above location.

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


PHPWASD$INI2

CPHPWASD also has a secondary PHP.INI which contains directives thatFoverride those from the primary PHP.INI.  This can be useful whenBmaintaining the site-wide PHP configuration in the primary PHP.INIDwhile placing only those directives required to be added or modified+for the particular application.  To have the PHPWASD#engine process this file define theRlogical name  PHPWASD$INI2 6to contain the location of the file.  This can beDdefined in any table the scripting process can access (e.g. process,job,Lsystem). To suppress useBof the primary PHP.INI file and rely entirely on the secondary forDconfiguration define the primary logical name to the NL: device.
V
$ DEFINE PHPWASD$INI NL:
S

PHPWASD$INIS

FTo specify PHP.INI directives directly (and avoid the overhead of file(processing) the logical name  PHPWASD$DEFINE  can be2defined.  The format for this string is name="value"[;name="value"], where?a semicolon is used toGseparate directives.  Any directive used in this logical overridesFthe 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"""
2

Mapping Rules

GIt is possible to pass parameters to PHP scripts and applications usingFthe script=param=(name=value)Gmapping rule.  The PHPWASD scripting engine checks for a number ofBreserved identifiers and will use the contents of those present toFperform the indicated function.   The primary PHP.INI cannotHbe supplied via mapping rule due to PHP module startup requirements.

? ParameterName
 M  : G  : F 
Purpose

PHP_INI2
 		Provides the location forthe)secondary PHP.INI configuration file.

PHP_INIS
 		Allows the specificationof aGvalue for any of the configuration directives allowed in PHP.INI. GThe format for these parameters is name="value"[;name="value"], where a/semi-colon is used to separate directives. See examples below.


FThe first example shows the specification of a secondary PHP.INI file,?and the second the use of a configuration directive string.
6
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"')
Example Scripts4



:

After:configuration the following scripts may be used to confirmtheenvironment is functioning.

5PerformanceG

The performance of4PHPWASD is quite respectable.  This table showsAsome results on an AlphaServer 4100 5/400, running VMS V7.3-2, HPTCP/IPCServices 5.4, with WASD 9.0 and PHPWASD v1.3, CSWS 1.3 and CSWS PHPF1.2, using the ApacheBench tool.

G ) " %  & * $  & * %  * & % 
EnvironmentPathReq/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-linePHPD

The PHPWASD.EXE/engine interface is only suitable for scripting?use.  It cannot be used outside of the CGI environment and certainly notGfrom the command line.  It is often useful to have a PHP tool thatcanGbe used in such a manner and the CSWS kit provides one.  To accessthisGimage assign a symbol (foreign command) in the (SY)LOGIN.COM procedure.

O
 $ PHP = "$HT_ROOT:[PHP.BIN]PHP.EXE"
FThis could also<be used as a non-persistent CGI scripting engine if desired.Full Build4



D

The PHPWASD kit2comes with object code that allows the image to beAlinked against the CSWS PHP shareable image.  To compile thePHPWASDFimage at least the CSWS PHP header files are required.  Basicallythis4means the full source kit needs to be installed.


"
http://h71000.www7.hp.com/openvms/products/ips/apache/csws_source.html
JCheck the BUILD_PHPWASD.COM procedure for detail. ENote that the CSWS PHP v1.2 source kit must be located on an ExtendedFile System (ODS-5) volume.Problems?5
    %
  • With the PHPWASD script ... Mark.Daniel@wasd.vsm.com.au
    • F
  • 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
    
    • 7
  • comp.os.vms
    • 
F

Unfortunately the-author of the PHPWASD interface is such a PHP<novice he is not in any position to answer queries about PHP"programming" orCusage.  If there's an obvious behavioural problem with PHPWASDB(preferably diagnosed by someone with PHP experience) then he's itthough.

AcknowlegementsF

Thanks to OpenVMS/Engineering and the CSWS team for their efforts@on PHP and Web technologies in general.  Thanks also to the efforts ofADave Jones with his PHP port (usable with PHPWASD v1.0).  Ofcourse,#thanks to the PHP development team!

A