Once you’ve installed PHP, if you don’t already have a web server instance set up (Apache or NGINX), you’ll want to create one. These steps show how to configure an Apache instance to run PHP.

Creating the web server manually

1. Go to web administration

You will need to make sure the web administration site is running. Navigate to http://ibmihost.example.org:2001/HTTPAdmin (putting in the hostname for your IBM i) and log in as needed.

2. Create the web server

In the HTTP admin interface, create a new site. Give it whatever name you prefer, select a port number that does not conflict with another running service on the system, and set up logging as you want.

3. Add the FastCGI module to Apache

From the HTTP admin interface (or a text editor pointed to /www/YOUR SITE NAME HERE/conf/httpd.conf), add the following lines after the Listen statement:

# IBM FastCGI module with handler for PHP
LoadModule zend_enabler_module /QSYS.LIB/QHTTPSVR.LIB/QZFAST.SRVPGM
AddType application/x-httpd-php .php
AddHandler fastcgi-script .php

# Set CCSID
DefaultFsCCSID 37 
CGIJobCCSID 37    

While the name says zend_enabler, it’s actually a generic PASE FastCGI handler that ships as part of IBM i.

There is one additional configuration option related to PHP, and that’s FastCGIServerID. By default, the FastCGI jobs will run as QTMHHTTP, but you may want to run as a different user, with different authorities or library lists. For example:

FastCGIServerID MYUSER

Note: for top performance, set up content compression (deflate / gzip) in your Apache configuration.

4. Create the FastCGI configuration module

You need to create the file /www/YOUR SITE NAME HERE/conf/fastcgi.conf; this is the FastCGI configuration file. The file’s contents should look like something like this (and should be saved as UTF-8/ASCII text):

; Static PHP servers for default user
Server type="application/x-httpd-php" CommandLine="/QOpenSys/pkgs/bin/php-cgi" SetEnv="PHPRC=/QOpenSys/etc/php" SetEnv="PHP_INI_SCAN_DIR=/QOpenSys/etc/php/conf.d" StartProcesses="1" SetEnv="PHP_FCGI_CHILDREN=10" SetEnv="PHP_FCGI_MAX_REQUESTS=0" ConnectionTimeout="30" RequestTimeout="60" SetEnv="LC_ALL=EN_US"

; Where to place socket files
IpcDir /www/YOUR SITE NAME HERE/logs

Of course, replace YOUR SITE NAME HERE in the IpcDir statement with your site’s name. Many of the statements here can be tweaked, so if you’re curious what each is:

  • Server type="application/x-httpd-php": Declare a FastCGI server, and the MIME type used. This matches the one in httpd.conf.
  • CommandLine="/QOpenSys/pkgs/bin/php-cgi": The PHP executable itself.
  • SetEnv="LC_ALL=EN_US": Set a UTF-8 locale for PASE (change for your locale)
  • SetEnv="PHPRC=/QOpenSys/etc/php": The directory where PHP looks for php.ini. By default, PHP looks in /QOpenSys/etc/php, so it can be omitted. We prefer to be explicit, however.
  • SetEnv="PHP_INI_SCAN_DIR=/QOpenSys/etc/php/conf.d": The directory where PHP looks for module configuration. By default, PHP looks in /QOpenSys/etc/php/conf.d by default, so it can be omitted. We prefer to be explicit, however.
  • RequestTimeout="60": How long the FastCGI handler waits for a request to finish. This is different from PHP’s own timeout, and used in case PHP for some reason cannot kill the job itself.
  • ConnectionTimeout="30": When a connection starts, how long it should wait for the request to come in. Having this set low can help mitigate DDoS attacks but hurt users on slow connections.
  • SetEnv="PHP_FCGI_CHILDREN=10": The number of child jobs spawned by FastCGI.
  • SetEnv="PHP_FCGI_MAX_REQUESTS=0": How often the FastCGI handler can reuse jobs. When this is zero, the handler will always reuse jobs. When this is set to a certain number, the handler will let a FastCGI job handle that many requests, then restart it. This has a performance impact and should only be changed if you’re encountering a bug like a memory leak.
  • IpcDir /www/YOUR SITE NAME HERE/logs: The directory in which to put the socket that PHP and Apache will use to coordinate. The logs directory is generally writeable by the web server user, so it’s a frequent choice.

5. Start the web server

The web server can be started. If there’s an issue with configuration files (either Apache’s or FastCGI’s), it will emit an error in the Apache error log, stored at /www/YOUR SITE NAME HERE/logs.

6. Copy your application into htdocs

You likely want to copy your application into /www/YOUR SITE HERE/htdocs/. You may have to make tweaks to your application for the new location. If you’ve upgraded to a newer PHP version than what you had before, you may also need to make tweaks there too.