WWW FAQs: How do I add a missing extension like gd or dbase to PHP on my Linux server?


2008-06-21: The PHP programming language, like Perl and many other interpreted languages, supports the idea of extensions that bring in otherwise missing features that would execute too slowly if they were written directly in PHP. Well-known examples include the mysql extension (for the MySQL database, of course) and the gd extension (for drawing graphics on the fly).

Today I needed a less well-known extension, dbase, which provides access to files in the exceedingly old-school dbase database format. And I wanted to add that extension with a minimum of work, doing as few dumb things as possible, with as few repercussions for the future stability and reliability of PHP on my system as possible. I've taken this opportunity to share several solutions for adding PHP extensions, depending on the packages provided with your Linux distribution and your technical skills.

Compiling PHP From Source

There are several ways to add add these extensions to PHP. For extensions that are provided as part of the PHP distribution (but not necessarily always "compiled in" to PHP), one solution is to simply enable them when compiling PHP from source code. You just change your PHP configure command appropriately:


./configure --enable-dbase ... enable lots of other things ...
make
make install
invoke-rc.d apache2 restart

Alas, that's a simplified configure command which only attempts to account for this single extension. In reality you'd need to take care of all of the other not-so-"optional" features you need for PHP to work properly on your site. To give you an idea of how hairy things can get, this is the configure command for PHP5 on a server of mine which runs a Linux distribution that doesn't include PHP5 as standard equipment:

./configure --enable-bcmath --with-bcmath --enable -bz2 --with-bz2 --enable-calendar --with-calendar --enable-ctype --wit h-ctype --enable-curl --with-curl --enable-dba --with-dba --enable-dbx --with-dbx --enable-dio --with-dio --enable-exif --with-exif --enab le-ftp --with-ftp --enable-gd --with-gd --enable-gettext --with-gettex t --enable-gmp --with-gmp --enable-iconv --with-iconv --enable-mbstrin g --with-mbstring --enable-mime_magic --with-mime_magic --enable-mysql --with-mysql --enable-openssl --with-openssl --enable-overload --with-o verload --enable-pcntl --with-pcntl --enable-pcre --with-pcre --enable -posix --with-posix --enable-session --with-session --enable-shmop --w ith-shmop --enable-sockets --with-sockets --enable-standard --with-stand ard --enable-sysvsem --with-sysvsem --enable-sysvshm --with-sysvshm -- enable-tokenizer --with-tokenizer --enable-wddx --with-wddx --enable-xml --with-xml --enable-yp --with-yp --enable-zlib --with-zlib --prefix =/usr/local/php5 --with-apxs2=/usr/sbin/apxs --with-freetype-dir --enable- gd-native-ttf --with-jpeg --enable-jpeg --with-jpeg-dir=/usr --with-xsl --enable-xsl

Yipes!

Clearly, compiling PHP from source isnot something that everyone wants to do. Do you even know which other extensions are part of the PHP build currently running on your web server? Some command line builds of PHP will report the configure command used to build them when you type php -i, but others (such as Ubuntu's) do not.

Do you know which libraries and header files must also be present and enabled to compile each extension successfully? Do you want to be forever responsible for keeping track of the latest PHP bug fixes and making sure you install them in a timely manner— instead of just allowing your Linux distribution's package manager to do it for you?

Once you compile from source, you're stuck in the role of a distribution maintainer, keeping track of these things religiously and getting hacked if you don't.

Yeah, I don't like doing that either. Fortunately, there are smarter ways.

Distribution Packages for PHP Modules

Fortunately, many PHP extensions are available as a package for your Linux distribution that can be installed with a simple package manager command. Many, many, many users don't seem to be aware of this, and wind up compiling things from source (or offering me money to do so) when they don't have to.

For instance, the gd extension is available as a package in pretty much every Linux distribution. Under Ubuntu Hardy Heron, adding gd is as simple as:


apt-get install php5-gd
invoke-rc.d apache2 restart

Alas, not every extension is available as part of your distribution. Which brings us to PECL.

PECL: the PHP Extension Community Library

Many PHP programmers know about PEAR, a community-supported library of reusable PHP classes that implement handy things like user authentication and database interfaces at a much higher level than the standard PHP library. PEAR classes are made up entirely of PHP code; they are simply code you don't have to write yourself, wheels that have already been invented for you. And the tools to install them are standard in most Linux distributions, or a simple package installation away:


apt-get install php5-pear
pear install packagename

Fewer programmers are familiar with PECL, which provides similar capabilities— but for libraries of native C-language code that extend the core of PHP itself with capabilities that either can't be or shouldn't be implemented directly in PHP. PECL extensions often provide "wrappers" for C-language libraries that are already out there on many operating systems. Once you install the appropriate PECL wrapper, you'll have access to new functions in PHP:


pecl install extensionname

Now, enable the newly installed module for both command line and Apache PHP. Edit the files /etc/php5/cli/php.ini and /etc/php5/apache2/php.ini, adding this line to both files (substitute the name of the extension you installed, of course):


extension=extensionname.so

Finally, signal the web server to restart:

invoke-rc.d apache2 restart

When your distribution leaves stuff out: compiling "built-in" PHP features dynamically

Unfortunately, none of these techniques were helpful to me today. That's because I needed the dbase extension, which is "standard" in PHP. I put "standard" in quotes because while it is distributed with the PHP source code, it isn't actually enabled (compiled into PHP) in Ubuntu. Joy.

What's more, Ubuntu has no php5-dbase package available to install with the apt-get command.

Ugh! Are we stuck? Not quite.

Fetching the same PHP source code your server is actually running

The bad news is we have to compile the module manually. The good news, and it is very good news, is that we can take advantage of Ubuntu's package management to make sure we are compiling the same version that should have been included in the first place. These commands do the magic:


apt-get source php5

This gives you a new subdirectory called, as of this writing, php5-5.2.4 containing the PHP source code corresponding to the same php5 package you're running on this box already. (Since Ubuntu is upgraded regularly, the directory name may differ for you.)


cd php5-5.2.4/ext/dbase
phpize
./configure --enable-dbase
make

These commands descend to the directory where the dbase module's source code lives and compile it correctly as a dynamic extension library... one that can be loaded into PHP on the fly, just as if it had been compiled for us by PECL.


cd modules
cp dbase.so /usr/lib/php5/20060613+lfs/

These commands copy the compiled dbase module to the directory where PHP5 is expecting to find extensions. Depending on your version of Ubuntu, the folder name may vary for you. Use the newest dated folder in /usr/lib/php5.

Almost there! All we have to do now is enable the module, both in command line PHP and in the Apache PHP module. Edit the files /etc/php5/cli/php.ini and /etc/php5/apache2/php.ini, adding this line to both files:


extension=dbase.so

Now, signal Apache to restart:


invoke-rc.d apache2 restart

Victory! You can now use the dbase_open function, just as if it had been there all along.

Staying Up to Date

A word of warning: PHP will get updated by Ubuntu. (For security reasons, that's a very good thing.) And when it does, your extension might not be used anymore. That's because an updated version of PHP might look at a different extensions folder (one with a different date in its filename).

If PHP is updated by the Ubuntu package manager, check for this situation and if necessary, repeat the steps above, downloading the newer PHP source and rebuilding the module. Yes, this is a pain, but it's much less painful than maintaining your entire PHP build yourself.

Legal Note: yes, you may use sample HTML, Javascript, PHP and other code presented above in your own projects. You may not reproduce large portions of the text of the article without our express permission.

Got a LiveJournal account? Keep up with the latest articles in this FAQ by adding our syndicated feed to your friends list!