SWIG and PHP4

Caution: This chapter (and module!) is still under construction

In this chapter, we discuss SWIG's support of PHP4. The PHP4 module is still under development so some of the features below may not work properly (or at all!.)

Preliminaries

In order to use this module, you will need to have a copy of the PHP 4.0 (or above) include files to compile the SWIG generated files. To test the modules you will need either the php binary or the Apache php module. If you want to build your extension into php directly (without having the overhead of loading it into each script), you will need the complete PHP source tree available.

Building PHP4 Extensions

To build a PHP4 extension, run swig using the -php4 option as follows :

swig -php4 example.i

This will produce 5 files by default. The first file, example_wrap.c contains all of the C code needed to build a PHP4 extension. The second file, php_example.h contains the header information needed to link the extension into PHP. The third file, config.m4 contains the shell code needed to enable the extension as part of the PHP4 build process. The fourth file, Makefile.in contains the information needed to build the final Makefile after substitutions. The fifth and final file, CREDITS should contain the credits for the extension. The last three files are only needed for the build process and you can stop then from being generated by passing the '-noextra' command line switch.

To finish building a extension, you have two choices. You can either build the extension as a seperate object file which will then have to be explicitly loaded by each script. Or you can rebuild the entire php source tree and build the extension into the php executable/library so it will be available in every script. The first choice is the default, however it can be changed by passing the '-phpall' command line switch to select the second build method.

Building a loadable extension

In order to complete the compilation, after you have run swig you will need to run the 'phpize' command (installed as part of php ) in the same directory. This re-creates the php build environment in that directory. It also creates a configure file which includes the shell code from the config.m4 that was generated by SWIG, this configure script will accept a command line argument to enable the extension to be run ( by default the command line argument is --enable-modulename, however you can edit the config.m4 file before running phpize to accept --with-modulename. You can also add extra tests in config.m4 to check that a correct library version is installed or correct header files are included, etc, but you must edit this file before running phpize. )

Before running the generated configure file, you may need to edit the Makefile.in file. This contains the names of the source files to compile (just the wrapper file by default) and any additional libraries needed to be linked in. If there are extra C files to compile, you will need to add them to the Makefile.in, or add the names of libraries if they are needed.

You then run the configure script with the command line argument needed to enable the extension. Then run make, which builds the extension. The extension object file will be left in the modules sub directory, you can move it to wherever it is convenient to call from your php script. To test the extension from a PHP script, you need to load it first. You do this by putting the line,

	dl("/path/to/modulename.so");	// Load the module
at the start of each PHP file.

Building extension into php

This method, selected with the '-phpall' command line switch, involves rebuilding the entire php source tree. Whilst more complicated to build, it does mean that the extension is then available without having to load it in each script.

After running swig with the -phpall switch, you will be left with a shockingly similiar set of files to the previous build process. However you will then need to move these files to a subdirectory within the php source tree, this subdirectory you will need to create under the ext directory, with the name of the extension ( e.g mkdir php-4.0.6/ext/modulename .)

After moving the files into this directory, you will need to run the 'buildall' script in the php source directory. This rebuilds the configure command and includes the extra command line arguments from the module you have added.

Before running the generated configure file, you may need to edit the Makefile.in. This contains the names of the source files to compile ( just the wrapper file by default) and any additional libraries needed to link in. If their are extra C files to complile you will need to add them to the Makefile, or add the names of libraries if they are needed.

You then need to run the configure command and pass the necessary command line arguments to enable your module ( by default this is --enable-modulename, but this can be changed by editing the config.m4 file in the modules directory before running the buildall script. In addition, extra tests can be added to the config.m4 file to ensure the correct libraries and header files are installed.)

Once configure has completed, you can run make to build php. If this all compiles correctly, you should end up with a php executable/library which contains your new module. You can test it with a php script which does not have the 'dl' command as used above.

To be continued...