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:

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:

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   HELLO_DIR=$PHP_HELLO
  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
  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 PHP_ADD_INCLUDE($HELLO_DIR/include)

  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 PHP_CHECK_LIBRARY($LIBNAME,$LIBSYMBOL,
  dnl [
  dnl   PHP_ADD_LIBRARY_WITH_PATH($LIBNAME, $HELLO_DIR/lib, HELLO_SHARED_LIBADD)
  dnl   AC_DEFINE(HAVE_HELLOLIB,1,[ ])
  dnl ],[
  dnl   AC_MSG_ERROR([wrong hello lib version or lib not found])
  dnl ],[
  dnl   -L$HELLO_DIR/lib -lm -ldl
  dnl ])
  dnl
  dnl PHP_SUBST(HELLO_SHARED_LIBADD)

  PHP_NEW_EXTENSION(hello, hello.c, $ext_shared)
fi

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
make
su
<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:

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

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