welcome hpws docs hp-ux webservers home contact hp support
hp logo - invent  hp-ux web server suite

Admin Guide for PHP 5.0.4

TABLE OF CONTENTS

Overview - Whats new Setup - Enabling PHP - Extensions for PHP - Enabling PHP extensions - Enabling Oracle extension GUI Setup and Overview - Enabling PHP - Overview of PHP Configuration and Extensions Migration from PHP4 to PHP5 - What has changed in PHP 5 - Backward Incompatible Changes - CLI SAPI - Migrating Configuration Files - New Functions - New Directives - Databases - New Object Model - Error Reporting - DOM Extension Additional Information - Apachectl - Environment variables Troubleshooting Legal Notices

OVERVIEW

PHP is a server-side scripting language that allows for easy development of complex web-based applications. It is open source, runs on many platforms and has a short learning curve. HP-UX Apache-based Web Server also features several useful PHP extensions. Additional extensions are available from the PHP open source community. (http://www.php.net) Whats New This release contains PHP version 5.0.4. To see a log of changes point your browser to http://www.php.net/ChangeLog-5.php#5.0.4 This release includes a new extension, the DOM extension. It is a replacement for the DOMXML extension from PHP 4.

SETUP

Enabling PHP Uncomment the following line from httpd.conf: LoadModule php5_module modules/libphp5.so Extensions for PHP HP-UX Apache-based Web Server comes bundled with some useful extensions for PHP. These extensions enhance the functionality available to PHP scripts. Complete technical documentation for these extensions along with sample code is available at http://www.php.net The following extensions are part of the HP-UX Apache-based Web Server bundle - Sockets (sockets.sl): Provides an interface to the socket communication functions based on the popular BSD sockets. Dependency: None - Ftp (ftp.sl): Provides client access to file servers speaking the File Transfer Protocol (FTP) Dependency: None - Ldap (ldap.sl): Use this extension to connect to Directory Servers using the LDAP protocol. Dependency: None - PostgreSQL (pgsql.sl): Provides access to PostgreSQL databases. Currently this extension is supported on HP-UX 11.11, HP-UX 11.23 32-bit and HP-UX 11.23 64-bit versions of HP-UX Apache-based Web Server when used with the PostgreSQL available in HP-UX Internet Express. HP-UX Internet Express is not available on HP-UX 11.00. This extension may however work on 11.00 when used with third party distributions of PostgreSQL database 7.3.1 and above. Dependency: PostgreSQL database is available as part of HP-UX Internet Express collection. This can be downloaded from http://www.software.hp.com/ - Oracle (oci8.sl): Allows access to Oracle databases. It uses the Oracle 8 call-Interface (OCI8). For more information, refer to the section: Enabling Oracle extension Dependency: Needs Oracle client side libraries version 8.1.6 or better installed. - Network Information System (yp.sl) : Allows network management of important administrative files (e.g. the password file). This extension is also referred to by the name Yellow Pages. Dependency: None - Dom (dom.sl): The DOM extension is a replacement for the DOMXML extension from PHP 4. The extension allows you to operate on an XML document with the DOM API. Dependency: libxml2 version 2.6.23 libxslt version 1.1.15 - Zlib (zlib.sl): This module enables you to transparently read and write gzip (.gz) compressed files, through versions of most of the file system functions which work with gzip-compressed files (and uncompressed files, too, but not with sockets). Dependency: zlib version 1.2.3 - Image (gd.sl) : Is used to create and manipulate image files in a variety of different image formats like png, jpg, wbmp, and xpm. Dependency: libjpeg version 6b libpng version 1.0.11 libxpm version 3.4k libfreetype version 2.1.2 t1lib version 5.0.0 (SHOULD be installed in /usr/local/lib) Note: libgd is no longer required. It is built into the extension's binary. - Crack (crack.sl): This provdies an interface to the CrackLib library which is used to test the strength of passwords. It is still in the experimental phase, and the behavior of this extension may change without notice in a future version of PHP. Dependency: cracklib version 2.8.3 - MySQL (mysql.sl): The MySQL extension provides access to MySQL databases. This extension was built into the core php binary in PHP 4.x. Starting from PHP 5.x, it is not delivered as part of the core php binary. Instead it comes as an extension library which has to be loaded via php.ini configuration file. Currently this extension is supported only on HP-UX 11.11 and HP-UX 11.23 32-bit version of HP-UX Apache-based Web Server when used with the MySQL available in HP-UX Internet Express. This extension is not supported on HP-UX 11.00 and 11.23 64-bit version of Apache-based Web Server. This extension may however work on 11.00 when used with third party distributions of MySQL. Dependency: MySQL database is available as part of HP-UX Internet Express collection. This can be downloaded from http://www.software.hp.com/ - Openssl: This extension uses the functions of OpenSSL for generation and verification of signatures and for sealing (encrypting) and opening (decrypting) data. OpenSSL offers many features that this module currently doesn't support. Some of these may be added in the future. Dependency: None Enabling PHP extensions The extensions are bundled in the form of shared libraries that can be loaded into memory when the webserver is started (if PHP is enabled). The PHP configuration file (php.ini) is used to load the extensions. The 'extension' directive is used to specify the extensions that need to be loaded. For example the following lines load the sockets and ftp extensions. extension=sockets.sl extension=ftp.sl Thus the administrator has the ability to chose to load only those extensions that are used by the php scripts. All PHP extensions bundled with HP-UX Apache-based Web Server are located in the following location by default /opt/hpws/apache/php/lib/php/extensions The following directive in the php.ini indicates the location where PHP will look for extensions: extension_dir = /opt/hpws/apache/php/lib/php/extensions Some extensions have dependencies on certain libraries as noted in the previous section. These libraries are not shipped as part of this distribution. The web server looks for these libraries under /usr/local/lib first. If the libraries are installed elsewhere on the system, set the SHLIB_PATH environment variable to (also) point to the install locations. Eg. export SHLIB_PATH=$SHLIB_PATH:/opt/lib1/:/opt/lib2 This setting is best made in /opt/hpws/apache/bin/apachectl file that is used to start the web server. Refer to section titled "Environment variables" for more information. Dependencies: If you do not have the libraries (identified as dependencies) installed, sources and HP-UX binaries for most of them are available for free from many Internet sources. The HP-UX Porting Archive Center (http://hpux.cs.utah.edu) provides many of these libraries in source form and also HP-UX binaries. All technical support questions in relation to bugs in these libraries or building these libraries should be directed to the authors of the libraries or other help resources identified in their respective distributions. Enabling Oracle extension The Oracle extension for PHP currently supports Oracle version 8.1.6. Oracle 8.1.6 client side libraries are required to use the extension. In order to enable the extension, perform the following steps: a) Uncomment the following line in /opt/hpws/apache/conf/php.ini extension=oci8.sl This tells PHP to load the Oracle extension on startup. The 'extension_dir' directive in php.ini file points to the location where oci8.sl can be found. It is set to the following default value: /opt/hpws/apache/php/libs/php/extensions/ b) Uncomment and set appropriate values for the following variables in apachectl: export ORACLE_HOME = /path/to/oracle-8.1.6/client/side/libraries export SHLIB_PATH=$SHLIB_PATH:$ORACLE_HOME/lib export LD_PRELOAD=$LD_PRELOAD:$ORACLE_HOME/JRE/lib/PA_RISC/native_threads/libjava.sl export ORACLE_SID=ConnectionName ** Note that the LD_PRELOAD variable is only required for PA-RISC systems. The next section provides additional information on these variables.

GUI SETUP AND OVERVIEW

Enabling PHP 1. Start HP-UX Webmin-based Admin if it isn't already running. 2. Access HP-UX Webmin-based Admin at http://yourserver.com:10000 3. In the "HP-UX Web Server Suite" section, click on the "HP-UX Apache-based Web Server" icon 4. In the "HP-UX Apache-based Web Server" section, click on the "Apache Modules" icon 5. In the "Home > Global > Apache Modules" section, click on "mod_php5" check-box click on the "Save" button in the bottom click on "Restart Apache"/"Start Apache" link on the top Note: Sometimes, you may have to actually "Stop Apache" and "Start Apache" in two different steps for the changes to take effect. Overview of PHP Configuration and Extensions No support for PHP extension or configurations is available at present from HP-UX Webmin-based Admin.

MIGRATION FROM PHP4 TO PHP5

- What has changed in PHP 5 ? PHP 5 and the integrated Zend Engine 2 have greatly improved PHP's performance and capabilities, but great care has been taken to break as little existing code as possible. So migrating your code from PHP 4 to 5 should be very easy. Most existing PHP 4 code should be ready to run without changes, but you should still know about the few differences listed below and take care to test your code before switching versions in production environments. - Backward Incompatible Changes: Although most existing PHP 4 code should work without changes, you should pay attention to the following backward incompatible changes: - strrpos() and strripos() now use the entire string as a needle. - Illegal use of string offsets causes E_ERROR instead of E_WARNING. An example illegal use is: $str = 'abc'; unset($str[0]);. - array_merge() was changed to accept only arrays. If a non-array variable is passed, a E_WARNING will be thrown for every such parameter. Be careful because your code may start emitting E_WARNING out of the blue. - PATH_TRANSLATED server variable is no longer set implicitly under Apache2 SAPI in contrast to the situation in PHP constant. However the PHPDoc style comments /** */, which starting PHP 5 are parsed by PHP, are recognized as T_DOC_COMMENT. - $_SERVER should be populated with argc and argv if variables_order includes "S". If you have specifically configured your system to not create $d. Otherwise the behaviour is the old. - get_class(), get_parent_class() and get_class_methods() now return the name of the classes/methods as they were declared (case-sensitive) which may lead to problems in older scripts that rely on the previous behaviour (the class/method name was always returned lowercased). A possible solution is to search for those functions in all your scripts and use strtolower(). This case sensitivity change also applies to the magical predefined constants __CLASS__, __METHOD__, and __FUNCTION__. The values are returned exactly as they're declared (case-sensitive). - ip2long() now returns FALSE when an invalid IP address is passed as argument to the function, and no longer -1. - If there are functions defined in the included file, they can be used in the main file independent if they are before return() or after. If the file is included twice, PHP 5 issues fatal error because functions were already declared, while PHP 4 doesn't complain about it. It is recommended to use include_once() instead of checking if the file was already included and conditionally return inside the included file. - CLI SAPI: In PHP 5, the CLI version will always populate the global $argv and $argc variables regardless of any php.ini directive setting. Even having register_argc_argv set to off will have no affect in CLI. - Migrating Configuration Files: Since the ISAPI(php) modules changed their names, from php4xxx to php5xxx, you need to make some changes in the configuration files. The following change has to be made in the Apache configuration file(httpd.conf) to load php5 module. # change this line: LoadModule php4_module /opt/hpws/apache/modules/libphp4.so # with this one: LoadModule php5_module /opt/hpws/apache/modules/libphp5.so NOTE: HPUX-Apache includes this change by default. Also please note that if any of your custom scripts have the module name hard coded to "libphp4.so", make sure that it is changed to "libphp5.so". - New Functions: PHP 5 adds a huge list of new functions to its API. For a entire list please refer to http://www.php.net/manual/en/migration5.functions.php - New Directives: A new directive has been added to php.ini file for enabling compatibility with PHP4's Zend Engine. zend.ze1_compatibility_mode By default the value of this directive is set to Off. To enable the compatibility mode set it to On as below. zend.ze1_compatibility_mode=On For other new directives added Please refer to http://www.php.net/manual/en/migration5.newconf.php - Databases: There were some changes in PHP 5 regarding databases (MySQL and SQLite). In PHP 5 the MySQL client libraries are NOT bundled with core PHP. Since PHP 5, the SQLite extension is built-in PHP. SQLite is an embeddable SQL database engine and is not a client library used to connect to a big database server (like MySQL or PostgreSQL). The SQLite library reads and writes directly to and from the database files on disk. - New Object Model In PHP 5 there is a new Object Model. PHP's handling of objects has been completely rewritten, allowing for better performance and more features. In previous versions of PHP, objects were handled like primitive types (for instance integers and strings). The drawback of this method was that semantically the whole object was copied when a variable was assigned, or pass as a parameter to a method. In the new approach, objects are referenced by handle, and not by value. The new Object Model is documented at http://www.php.net/manual/en/language.oop5.php. - Error Reporting As of PHP 5 new error reporting constant E_STRICT was introduced with value 2048. It enables run-time PHP suggestions on your code interoperability and forward compatibility, that will help you to keep latest and greatest suggested method of coding. E.g. STRICT message will warn you on using deprecated functions. NOTE: E_ALL does not include E_STRICT so it's not enabled by default - DOM Extension When moving from PHP4 to PHP5, some modifications are required in the scripts using domxml API. In PHP4, the experimental domxml extension was used to manage XML, but this has been replaced by the DOM extension in PHP5. The main problem with the domxml extension was that it didn't follow the standard method naming convention as defined by the W3C standard. The new DOM extension is completely based on the W3C standard, including method and property names. As a consequence of this new W3C compatibility, the old domxml-based scripts won't work anymore. The API is quite different in PHP 5. But if the "almost W3C compatible" method names available in PHP 4.3.x were used, porting is simple. The changes that needs to be done are in the loading and saving methods, along with removal of the underscores("_") in the methodnames (the DOM standard uses studlyCaps). For example, a PHP function name of the form my_php_function() in PHP 4, would now be myPhpFunction() according to the new standard.

ADDITIONAL INFORMATION

Apachectl The above-mentioned exports are best placed in the /opt/hpws/apache/bin/apachectl. Since the HP-UX Apache-based Web Server is usually started/restarted/stopped using this script, all environment variables are guaranteed to be setup before the HP-UX Apache-based Web Server starts up. Environment variables Verify the following variables are setup correctly in /opt/hpws/apache/bin/apachectl. a) PHPRC : This is where PHP looks for the php.ini file. This variable is set by default to $APACHE_PREFIX/conf. b) LD_PRELOAD : (Oracle extension only on PA-RISC) HP-UX does not have full support for dynamic loading of libraries with thread local storage (TLS). The following environment variable needs to be set-up to use PHP's oracle extension. It would require the system to be loaded with an ld patch PHSS_26559 or later. If PHP's Oracle extension is being used then we need to preload the following library. export LD_PRELOAD="$LD_PRELOAD:$ORACLE_HOME/JRE/lib/PA_RISC/native_threads/libjava.sl" c) ORACLE_HOME : (Oracle extension only) This variable specifies the path where the Oracle 8 installation exists. This could refer to a local server/client side installation, depending upon which one is installed on the machine running HP-UX Apache-based Web Server. Example: export ORACLE_HOME=/opt/oracle/8.1.6 Ignore this variable if not using PHP's Oracle extension. d) ORACLE_SID : (Oracle extension only) This identifies a running instance of an Oracle database server that PHP will connect to by default. Example: export ORACLE_SID=ConnectionName "ConnectionName" has to be defined in the tnsnames.ora file. Lookup the Oracle documentation for more information on the tnsnames.ora file and setting up connection strings. Optionally the PHP function "OCILogon" can also be passed an alternate sid to be used Ignore this variable if not using PHP's Oracle extension. e) SHLIB_PATH : This variable is used by the loader during program startup to look for shared libraries when they are not found in the location expected by the dependent binary. Example: export SHLIB_PATH=$SHLIB_PATH:$ORACLE_HOME/lib

TROUBLESHOOTING

- Can't change PHP default settings. ---------------------------------------------------------------- PHP defaults can be changed in /opt/hpws/apache/conf/php.ini. Set the environment variable: export PHPRC=/opt/hpws/apache/conf This tells PHP where to look for the php.ini file - Error loading PHP when Oracle extension is enabled ---------------------------------------------------------------- Ensure that $ORACLE_HOME is set to the correct location of Oracle 8.1.6 client side libraries. Also make sure you have followed all the steps mentioned in Enabling Oracle extension - Error loading a PHP extension ---------------------------------------------------------------- 1) If you have more than one extension failing to load correctly, disable all other extensions and try to successfully load one extension at a time. See section Enabling PHP extensions 2) Ensure that the dependent libraries (if any) are available on the local system. 3) Ensure that the environment variable SHLIB_PATH is set correctly apachectl if the libraries are not located in /usr/local/lib. 4) Check to see if you have the right versions of the libraries available. Information on the specific version numbers can be found in: Extensions for PHP 5) For more information, refer to the following sections: Enabling PHP extensions Environment Variables ***************************************************************************