PHP4 Extension Module HOWTO

After getting a module to work under PHP4 RC1 i wrote down what I did in some small steps. Note that this document is not at all complete but its a start. If anyone wanna contrib to it email me suggestion/text/etc to me privatly and hopefully we will have a good HOWTO in a few weeks. -- Jerry Lundström:<jerry.lundstrom@citat.se> mobile+46.739.876053:phone+46.31.7107244:fax+46.31.7107201 citat.solutions:Kronhusgatan.9:SE-411.05.Göteborg:Sweden www.citat.se/solutions

PHP4 Extension Module HOWTO Jerry Lundstrom v0.1, 2000-03-30 This document explains in brief HOWTO create a PHP4 extension module. ______________________________________________________________________ Table of Contents 1. Introduction 2. Creating the necessary files 2.1 Makefile.in 2.1.1 Tips and Tricks 2.2 config.m4 2.2.1 Tips and Tricks 3. The Source Code Files 3.1 <module name>.c 3.2 php_<module name>.h 4. Further Information ______________________________________________________________________ 11.. IInnttrroodduuccttiioonn This document explains the most basic things that need to be done in order to create a new PHP4 extension module. Note that there is no confirmation that any of this information is correct what so ever! The examples in this document has been tried on PHP4 RC1. 22.. CCrreeaattiinngg tthhee nneecceessssaarryy ffiilleess After unpacking the source code you do this. % cd ext % ./ext_skel <module name> This will create a dir called <module name> and some files under that. The important files are MMaakkeeffiillee..iinn and ccoonnffiigg..mm44. When you run the eexxtt__sskkeell script it will tell you to run some scripts at the top dir. You should do that but have in mind that you will have to redo that every time you change the MMaakkeeffiillee..iinn or the ccoonnffiigg..mm44 file. In the following examples we have made a tteesstt module. 22..11.. MMaakkeeffiillee..iinn This is the skeleton file used to create the real MMaakkeeffiillee. There are some important variables here that define what files are compiled and what included. A normal MMaakkeeffiillee..iinn looks like this. ______________________________________________________________________ # $Id$ DEPTH = ../.. topsrcdir = @topsrcdir@ srcdir = @srcdir@ VPATH = @srcdir@ LTLIBRARY_NAME = libtest.la LTLIBRARY_SOURCES = test.c include $(topsrcdir)/build/ltlib.mk ______________________________________________________________________ There are lots of other variables that can be set in order to get dif- ferent results. Here is a brief list on variables. LLTTLLIIBBRRAARRYY__NNAAMMEE The name of the library module file, should be ".la". LLTTLLIIBBRRAARRYY__SSOOUURRCCEESS The source code for the library module. LLTTLLIIBBRRAARRYY__LLIIBBAADDDD Extra libraries to link into the LLTTLLIIBBRRAARRYY__NNAAMMEE. Note that this must be ".lo" files. LLTTLLIIBBRRAARRYY__DDEEPPEENNDDEENNCCIIEESS This variable goes onto the LLTTLLIIBBRRAARRYY__NNAAMMEE dependency line. Note that this variable is used both in non-shared and shared library module. LLTTLLIIBBRRAARRYY__SSHHAARREEDD__NNAAMMEE Same as LLIIBBRRAARRYY__NNAAMMEE but used when creating shared library module. LLTTLLIIBBRRAARRYY__SSHHAARREEDD__LLIIBBAADDDD Same as LLIIBBRRAARRYY__LLIIBBAADDDD but used when creating shared library module. 22..11..11.. TTiippss aanndd TTrriicckkss Here is a example how to create a module using C++ code. ______________________________________________________________________ # $Id$ DEPTH = ../.. topsrcdir = @topsrcdir@ srcdir = @srcdir@ VPATH = @srcdir@ LTLIBRARY_NAME = libtest.la LTLIBRARY_SOURCES = test.c LTLIBRARY_LIBADD = test_cc.lo LTLIBRARY_DEPENDENCIES = $(LTLIBRARY_LIBADD) include $(topsrcdir)/build/ltlib.mk .SUFFIXES: .cc .cc.lo: $(PHP_COMPILE) ______________________________________________________________________ This example can be use when compiling any outside PHP code. 22..22.. ccoonnffiigg..mm44 This file is used when creating the ccoonnffiigguurree file that lives in the top dir. Usage of this can be to check for a external library function that you need for your code. The default file looks like this. ______________________________________________________________________ dnl $Id$ dnl config.m4 for extension test dnl don't forget to call PHP_EXTENSION(test) PHP_EXTENSION(test) ______________________________________________________________________ The call to PPHHPP__EEXXTTEENNSSIIOONN is very important because that activates the module for compiling, if that call is missed the module will not be compiled or included into php. There are some useful function here too. AACC__AADDDD__IINNCCLLUUDDEE(( <<ddiirr ttoo aadddd>> )) This is used to add include paths. AACC__AADDDD__LLIIBBRRAARRYY__WWIITTHH__PPAATTHH(( <<lliibbnnaammee>>,, <<ppaatthh ttoo lliibb>> )) This is used to add library files used when linking the final php program. 22..22..11.. TTiippss aanndd TTrriicckkss Here is an example on how to check for a external library and include it. ______________________________________________________________________ dnl $Id$ AC_MSG_CHECKING(for zlib support) AC_ARG_WITH(zlib, [ --with-zlib[=DIR] Include zlib support.], [ if test "$withval" != "no"; then if test "$withval" = "yes"; then ZLIB_DIR=/usr else ZLIB_DIR=$withval fi AC_ADD_INCLUDE($ZLIB_DIR/include) AC_ADD_LIBRARY_WITH_PATH(zlib, $ZLIB_DIR/lib) if test ! -f "$ZLIB_DIR/include/zlib.h"; then AC_MSG_ERROR(Unable to find zlib include files, please check so that the path is correct) fi AC_DEFINE(HAVE_ZLIB,1,[zlib]) AC_MSG_RESULT(yes) PHP_EXTENSION(test) else AC_MSG_ERROR(no) fi ],[ AC_MSG_RESULT(no) ]) ______________________________________________________________________ 33.. TThhee SSoouurrccee CCooddee FFiilleess By default a file with the name <<mmoodduullee nnaammee>>..cc is expected. Also a include file named pphhpp__<<mmoodduullee nnaammee>>..hh is needed. 33..11.. <<mmoodduullee nnaammee>>..cc First lets take a look at a example file. ______________________________________________________________________ #include "php.h" #include "php_test.h" function_entry test_functions[] = { PHP_FE(test_me, NULL) {NULL, NULL, NULL} }; zend_module_entry test_module_entry = { "test", test_functions, PHP_MINIT(test), PHP_MSHUTDOWN(test), NULL, NULL, PHP_MINFO(test), STANDARD_MODULE_PROPERTIES }; PHP_MINIT_FUNCTION(test) { return SUCCESS; } PHP_MSHUTDOWN_FUNCTION(test) { return SUCCESS; } PHP_MINFO_FUNCTION(test) { php_printf("Test support enabled"); } PHP_FUNCTION(test_me) { RETURN_TRUE; } ______________________________________________________________________ Short info on the important things to know. ffuunnccttiioonn__eennttrryy This struct contains all the functions that will be available to the PHP script. Simply use the macro PPHHPP__FFEE to add functions. Note that there is no , needed at the end and that it must be close off by a {NULL, NULL, NULL} sequence. zzeenndd__mmoodduullee__eennttrryy This module entry is what defines the module. First we have the name of the module then the struct of the function declarations. Third value is the PPHHPP__MMIINNIITT function that will be called upon creation. After that we have to PPHHPP__MMSSHHUUTTDDOOWWNN function that, as it says, will be called upon shutdown of the module. The 5th and 6th is unknown to me at this point but may be added in later versions. 7th value is the PPHHPP__MMIINNFFOOmation function, this is not a very important function. Last value is the module properties, this document does not go into the module properties but it safe to say that SSTTAANNDDAARRDD__MMOODDUULLEE__PPRROOPPEERRTTIIEESS is all you need for non- complex modules. PPHHPP__MMIINNIITT__FFUUNNCCTTIIOONN(( <<mmoodduullee nnaammee>> )) Macro for creating the init module function. PPHHPP__MMSSHHUUTTDDOOWWNN__FFUUNNCCTTIIOONN(( <<mmoodduullee nnaammee>> )) Macro for creating the shutdown module function. PPHHPP__MMIINNFFOO__FFUUNNCCTTIIOONN(( <<mmoodduullee nnaammee>> )) Macro for creating the module information function. PPHHPP__FFUUNNCCTTIIOONN(( <<ffuunnccttiioonn nnaammee>> )) Macro for creating PHP functions. 33..22.. pphhpp__<<mmoodduullee nnaammee>>..hh First lets take a look at a example file. ______________________________________________________________________ #ifndef _TEST_H #define _TEST_H extern zend_module_entry test_module_entry; #define test_module_ptr &test_module_entry extern PHP_MINIT_FUNCTION(test); extern PHP_MSHUTDOWN_FUNCTION(test); extern PHP_MINFO_FUNCTION(test); PHP_FUNCTION(test_me); #define phpext_test_ptr test_module_ptr #endif /* _TEST_H */ ______________________________________________________________________ Some of these macro/structs are explained in the <<mmoodduullee nnaammee>>..cc section and are only exported in this file. tteesstt__mmoodduullee__ppttrr Speaks for it self, a pointer to the module entry. pphhppeexxtt__tteesstt__ppttrr This define/pointer is important because it is used in the internal_function.c file. If this doesn't exist there will be a compile error. If you want to be able to not define a module if something was missing, like a library that you really needed, you can define the pphhppeexxtt__<<mmoodduullee nnaammee>>__ppttrr to NULL. 44.. FFuurrtthheerr IInnffoorrmmaattiioonn +o Get the php source package from www.php.net <http://www.php.net/> +o apidoc.txt and apidoc-zend.txt files that are included in the php source code. +o PHP Mailing lists, found at www.php.net <http://www.php.net/> Attachment: [application/octet-stream] PHP4-Extension-Module-HOWTO.sgml