How to Configure and Make PHP on FreeBSD

These are my notes for how to install a custom build of PHP 5 on FreeBSD.

These notes describe how to compile a custom-built version of PHP 5 from the source, and replace the stock build on a FreeBSD VPS server from Verio. The purpose of the custom-build is to install some extensions that can not be dynamically loaded and must be compiled in, specifically tidy and zip. These notes show how to build the Apache 2 shared module and CLI versions of PHP, but not the CGI version.

The server environment is a FreeBSD Virtual Private Server VPS v3 Hosted at Verio. Here is the server version: FreeBSD 6.0-RELEASE (VKERN) #28: Fri Mar 30 11:04:03 MDT 2007. PHP5 is pre-installed on this virtual dedicated server, or it can be installed using vinstall. The two main files that come out of this process are "php" and "libphp5.so". "php" is the CLI executable binary, and "libphp5.so" is an Apache 2 shared module. The commands below do not build the CGI version of PHP, which may have less performance, but may be more suitable to a shared-server environment.

Almost all the steps below must be run as root, and the label "root]" or "user]" indicates the user under which to run each command. Do not run these commands blindly - make sure you understand what they do and if they are appropriate for your server. I hope you find these notes useful.

INFORMATIONAL COMMANDS

root] php -r "phpinfo();" | more
	(This command displays existing configure options at the beginning. 
	Use those options as a starting point for your custom build.)
root] php -m
	(PHP loaded modules)
root] httpd -l
	(Apache compiled-in modules)

SETUP WORKING DIRECTORY

user] su root
root] cd ~
root] mkdir ~/php
root] cd ~/php

DOWNLOAD TIDY SOURCE FROM CVS AND BUILD IT

Note: The tidy source can no longer be downloaded from the tidy website as an archive. You have to download it via CVS, which is simple.

root] cvs -d:pserver:anonymous@tidy.cvs.sourceforge.net:/cvsroot/tidy checkout tidy
root] cd tidy/build/gmake
root] gmake
root] gmake install
root] gmake clean

VERIFYING TIDY INSTALLATION

root] rehash
root] tidy --version
root] ls -la /usr/local/lib | grep libtidy.a

GET LATEST PHP VERSION

root] wget http://us3.php.net/get/php-5.2.3.tar.gz/from/this/mirror
root] tar -xzvf php-5.2.3.tar.gz
root] rm php-5.2.3.tar.gz 
root] cd php-5.2.3

BUILD AND INSTALL PHP

* We enable apxs2 to create the Apache 2 module, and disable PHP-CGI.
* The main things we need are tidy and zip
* Since we are compiling many standard modules into the PHP binary, then
	those extensions need to be disabled from extensions.ini later.
* By compiling many extensions into PHP, it makes the binaries larger.
	e.g. 2.5 MB for the stock build, and 15 MB for the custom build.
	However, this does not significantly impact memory usage for us.
* Use the command below to display help about the PHP configuration options.
root] ./configure --help

* My configure command is below. You must customize it for your own use.

root] './configure' '--disable-static' '--disable-debug' '--enable-memory-limit' '--prefix=/usr/local/php5' '--with-config-file-scan-dir=/usr/local/php5/etc' '--enable-libxml' '--with-libxml-dir=/usr/local' '--enable-reflection' '--enable-spl' '--enable-zend-multibyte' '--with-regex=system' '--with-tidy' '--enable-zip' '--enable-bcmath' '--with-bz2=shared' '--enable-calendar' '--with-curl=shared' '--enable-dba' '--enable-exif' '--enable-ftp' '--with-gd' '--enable-gd-native-ttf' '--with-jpeg-dir=/usr' '--with-png-dir=/usr' '--with-zlib-dir=/usr' '--with-gettext=shared' '--with-gmp=shared' '--with-imap-ssl' '--with-imap' '--enable-mbstring' '--with-mcrypt=shared' '--with-mhash=shared' '--with-mysql' '--with-mysqli' '--with-openssl-dir' '--with-pdo-mysql' '--enable-sockets' '--with-xsl' '--with-zlib' '--with-apxs2' '--disable-cgi'

root] make
	(takes about 15 minutes)
root] make test
	(This step is optional, if you want ~2500 checks to be run 
		and you want to send the log to the PHP QA team.)
root] make install
	(does not overwrite existing php.ini; takes < 1 minute)
root] make clean

RENAME NEW FILES TO VERSION-SPECIFIC APACHE MODULE AND BINARY

We rename the output binaries to include their version number. This way, we can keep each version of PHP around, just in case. Then, we use a soft link from "php" to the latest build.

root] ls -la /usr/local/php/bin/
root] mv /usr/local/php/bin/php /usr/local/php/bin/php-5.2.3
root] ls -la /usr/local/apache2/modules/
root] mv /usr/local/apache2/modules/libphp5.so /usr/local/apache2/modules/mod_php5-5.2.3.so

UPDATE EXTENSIONS

root] pico /usr/local/php/etc/extensions.ini
	(don't load compiled-in extensions; comment them out with semi-colon; 
		run "php -v" and look for warnings like:
		"PHP Warning:  Module 'session' already loaded in Unknown on line 0")
root] pico /usr/local/php/lib/php.ini
	(update path to dynamic extensions
	e.g. extension_dir = "/usr/local/php5/lib/php/extensions/no-debug-non-zts-20060613/")
root] pico /www/conf/httpd.conf
	Make sure LoadModule points to right module; 
	PHP make install will add a line like:
		LoadModule php5_module        modules/libphp5.so
	which needs to be changed to:
		LoadModule php5_module          modules/mod_php5-5.2.3.so

TEST TO MAKE SURE NO ERRORS

root] /usr/local/php/bin/php-5.2.3 -v

UPDATE SYMBOLIC LINK TO PHP CLI

root] ls -la /usr/local/bin/php
root] rm /usr/local/bin/php
root] ln -s /usr/local/php5/bin/php-5.2.3 /usr/local/bin/php 
root] ls -la /usr/local/bin/php
root] rehash
root] php -v (This should show the latest build version)

RESTART AND CLEAN UP

root] restart_apache
root] reboot (if apache doesn't restart gracefully)
root] rm -rf /root/php

Finally, restart any background processes that rely on PHP. Your command will vary from the one I use, and most likely, you do not need to do this step.

user] php ctl-scheduler.php restart