First steps

To get you started with a module, PHP includes "ext_skel", which creates the skeleton of an extension. To run ext_skel, go into the ext directory of the PHP source code, then type this:

./ext_skel --extame=hello

The script ext_skel script creates for us a hello directory, which in turn contains a php_hello.h file and a hello.c file to contain our code, plus hello.php to test installation of the module has worked, a config.m4 file, which is part of PHP's automatic build system (explained later), and also a default test file for your extension.

All being well, ext_skel should output the following:

Creating directory hello                                                       
Creating basic files: config.m4 config.w32 .cvsignore hello.c php_hello.h CREDITS
EXPERIMENTAL tests/001.phpt hello.php [done].                                
To use your new extension, you will have to execute the following steps:       
1.  $ cd ..                                                                    
2.  $ vi ext/hello/config.m4                                                   
3.  $ ./buildconf                                                              
4.  $ ./configure --[with|enable]-hello                                        
5.  $ make                                                                     
6.  $ ./php -f ext/hello/hello.php                                             
7.  $ vi ext/hello/hello.c                                                     
8.  $ make                                                                     
Repeat steps 3-6 until you are satisfied with ext/hello/config.m4 and          
step 6 confirms that your module is compiled into PHP. Then, start writing     
code and repeat the last two steps as often as necessary.

As it quite rightly says, the first thing to do is edit the config.m4 file so that we allow the extension to be built. With PHP extensions, there are two ways for users to enable them: adding --enable-foo to their configure line, or adding --with-foo to their command line. They are both very similar, but the difference is that --enable-xxx is used for bundled extensions, whereas --with-xxx means that extension has outside requirements.

We need to pick the one to use in the config.m4 file, so go ahead and open it up from the "ext/hello" directory. It should look like this:

dnl $Id$
dnl config.m4 for extension hello

dnl Comments in this file start with the string 'dnl'.
dnl Remove where necessary. This file will not work
dnl without editing.

dnl If your extension references something external, use with:

dnl PHP_ARG_WITH(hello, for hello support,
dnl Make sure that the comment is aligned:
dnl [  --with-hello             Include hello support])

dnl Otherwise use enable:

dnl PHP_ARG_ENABLE(hello, whether to enable hello support,
dnl Make sure that the comment is aligned:
dnl [  --enable-hello           Enable hello support])

if test "$PHP_HELLO" != "no"; then
  dnl Write more examples of tests here...

  dnl # --with-hello -> check with-path
  dnl SEARCH_PATH="/usr/local /usr"     # you might want to change this
  dnl SEARCH_FOR="/include/hello.h"  # you most likely want to change this
  dnl if test -r $PHP_HELLO/$SEARCH_FOR; then # path given as parameter
  dnl else # search default path list
  dnl   AC_MSG_CHECKING([for hello files in default path])
  dnl   for i in $SEARCH_PATH ; do
  dnl     if test -r $i/$SEARCH_FOR; then
  dnl       HELLO_DIR=$i
  dnl       AC_MSG_RESULT(found in $i)
  dnl     fi
  dnl   done
  dnl fi
  dnl if test -z "$HELLO_DIR"; then
  dnl   AC_MSG_RESULT([not found])
  dnl   AC_MSG_ERROR([Please reinstall the hello distribution])
  dnl fi

  dnl # --with-hello -> add include path

  dnl # --with-hello -> check for lib and symbol presence
  dnl LIBNAME=hello # you may want to change this
  dnl LIBSYMBOL=hello # you most likely want to change this

  dnl [
  dnl ],[
  dnl   AC_MSG_ERROR([wrong hello lib version or lib not found])
  dnl ],[
  dnl   -L$HELLO_DIR/lib -lm -ldl
  dnl ])

  PHP_NEW_EXTENSION(hello, hello.c, $ext_shared)

As the file says at the top, lines beginning with "dnl" are comments. To get our extension working enough to compile, we need to uncomment two lines:

PHP_ARG_ENABLE(hello, whether to enable hello support,
dnl Make sure that the comment is aligned:
[  --enable-hello           Enable hello support])

With that done, we can go ahead and compile the extension as it is - we can do this because ext_skel writes just enough code for us to test things out. Testing now ensures you have a working build system - if you can't get an empty extension to compile you have serious problems! Execute these commands from the root directory of the PHP source code:

./buildconf --force
./configure --enable-hello --disable-cgi
<enter password>
make install

If you get errors about missing libtool, automake, autoconf, bison, flex, or xml-config, you need to install each of these packages. The xml-config script is available in the libxml2-dev package, if you use a package-management tool. If you got no errors back you should now have a working PHP CLI SAPI binary with your new extension compiled. You can confirm this in two ways, so let's do both. First, type "php -m" to get a list of all the modules compiled into your PHP binary - "hello" should be in there.

A much better way to test it out is to follow the instructions given back with ext_skel. That is, type "php -f ext/hello/hello.php" to run the basic test PHP script that checks whether the extension is loaded and outputs a list of all the functions in there. All being well you should see something like this:

debian php-5.0.1$ php -f ext/hello/hello.php
Functions available in the test extension:<br>
Congratulations! You have successfully modified ext/hello/config.m4.
Module hello is now compiled into PHP.

Success! Let's move onto examining the contents of the C files and writing our hello world function...


Want to learn PHP 7?

Hacking with PHP has been fully updated for PHP 7, and is now available as a downloadable PDF. Get over 1200 pages of hands-on PHP learning today!

If this was helpful, please take a moment to tell others about Hacking with PHP by tweeting about it!

Next chapter: Hello world - in C! >>

Previous chapter: Before we begin

Jump to:


Home: Table of Contents

Copyright ©2015 Paul Hudson. Follow me: @twostraws.