20.3 First stepsThis is NOT the latest copy of this book; click here for the latest version.
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 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>
confirm_hello_compiled<br>
<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 see this stuff in print? PHP in a Nutshell takes the core topics covered here, adds in thousands of edits from the editorial team and myself, and combines them to make an unbeatable reference for PHP programmers at all levels.
My latest book has hundreds more tips on how to use PHP, Apache, and MySQL, plus Perl, Python, shell scripts, performance tuning, and more!
|
