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:
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 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:
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...
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
Home: Table of Contents
Copyright ©2015 Paul Hudson. Follow me: @twostraws.