Linking C libraries to php extensions

After learning to create a simple php module it took a long time for me to understand the correct way of porting an existing C library to to a php module. Sometimes I thought it may be impossible for me. After all I have managed to understand the correct way of doing it. If you need to learn about creating a simple php module, follow this article. So, here's the procedure I followed to build the php module which is linked to a C library.

1) First step is creating a simple C library to link to a php module. So, write and save the following source files.

Here's the "asanka.c" file,

#include
#include "asanka.h"

void setValue(int a){
value = a;
}

int getValue(){
return value;
}

void increment(){
value = value + 1;
}

void decrement(){
value = value - 1;
}

Here's the "asanka.h" file,

#include

int value;

void setValue(int a);

int getValue();

void increment();

void decrement();

Now create the C library called "libasanka.a" by giving the command,

gcc -c asanka.c
ar -cr libasanka.a asanka.o

Ok, now we have the library. Create a directory in some place, lets's say in your home directory as the "library". Inside that directory, create two directories as "lib" and "include". Put the library file "libasanka.a" into the "lib" directory and "asanka.h" file to the "include" directory. So, now the paths to both should be,

/home/username/library/include/asanka.h
/home/username/library/lib/libasanka.a

There's a reason for giving the path's of the files. We have to give the path when we create the php module.

2) Now it's time to create the php module. Goto ext directory of the php source and give the command in the terminal,

./ext_skel --extname=asanka

3) Now go into the newly created directory "asanka" inside the ext directory and open the auto generated file "asanka.c" (this is not the file we created). Add the following entries in the appropriated places,

PHP_FE(asanka_setValue, NULL)
PHP_FE(asanka_getValue, NULL)
PHP_FE(asanka_increment, NULL)
PHP_FE(asanka_decrement, NULL)

Add the following entries also in the appropriate place in the file,

PHP_FUNCTION(asanka_setValue)
{
int locValue;
int argc = ZEND_NUM_ARGS();

if (zend_parse_parameters(argc TSRMLS_CC, "l", &locValue) == FAILURE) {
php_error_doc_ref(NULL TSRMLS_CC, E_ERROR, "Invalid Parameters");
return;
}

setValue(locValue);
}

PHP_FUNCTION(asanka_getValue)
{
int locValue;
locValue = getValue();
RETURN_LONG(locValue);
}

PHP_FUNCTION(asanka_increment)
{
increment();
}

PHP_FUNCTION(asanka_decrement)
{
decrement();
}

4) Now open the file "php_asanka.h" in the same directory and add the following to it,

PHP_FUNCTION(asanka_setValue);
PHP_FUNCTION(asanka_getValue);
PHP_FUNCTION(asanka_increment);
PHP_FUNCTION(asanka_decrement);


5) Open the config.m4 file and add change it's content to be match with the following code,

dnl $Id$
dnl config.m4 for extension asanka

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:

PHP_ARG_WITH(asanka, for asanka support,
[ --with-asanka[=DIR] Include asanka support])

dnl Otherwise use enable:

dnl PHP_ARG_ENABLE(asanka, whether to enable asanka support,
dnl Make sure that the comment is aligned:
dnl [ --enable-asanka Enable asanka support])

if test "$PHP_ASANKA" != "no"; then
dnl Write more examples of tests here...

dnl # --with-asanka -> check with-path
dnl SEARCH_PATH="/usr/local /usr" # you might want to change this
dnl SEARCH_FOR="/include/asanka.h" # you most likely want to change this
if test -r $PHP_ASANKA/lib/libasanka.a; then # path given as parameter
ASANKA_DIR=$PHP_ASANKA
else # search default path list
AC_MSG_CHECKING([for asanka files in default path])
for i in /usr/local /usr; do
if test -r $i/lib/libasanka.a; then
ASANKA_DIR=$i
AC_MSG_RESULT(found in $i)
fi
done
fi
dnl
if test -z "$ASANKA_DIR"; then
AC_MSG_RESULT([not found])
AC_MSG_ERROR([Please reinstall the libasanka distribution - asanka.h should be /include and libasanka.a should be in /lib])
fi

dnl # --with-asanka -> add include path
PHP_ADD_INCLUDE($ASANKA_DIR/include)

dnl # --with-asanka -> check for lib and symbol presence
LIBNAME=asanka # you may want to change this
LIBSYMBOL=getValue # you most likely want to change this

PHP_CHECK_LIBRARY($LIBNAME,$LIBSYMBOL,
[
PHP_ADD_LIBRARY_WITH_PATH($LIBNAME, $ASANKA_DIR/lib, ASANKA_SHARED_LIBADD)
AC_DEFINE(HAVE_ASANKALIB,1,[ ])
],[
AC_MSG_ERROR([wrong asanka lib version or lib not found])
],[
-L$ASANKA_DIR/lib -lm
])
dnl
PHP_SUBST(ASANKA_SHARED_LIBADD)

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

6) Now run the following commands in terminal inside the "asanka" directory,

/usr/local/bin/phpize

./configure --with-asanka=/home/username/library/

sudo make

7) Now our new module is ready. You can find it in the "modules" directory inside the "asanka" directory. Copy that "asanka.so" shared object to the extensions directory of your installed php. If you don't know the path to the extensions directory, look at the phpinfo() page.

8) After placing "asanka.so" into the extensions directory, next thing is editing the php.ini file. Open it and add an entry as follows in the appropriate place,

extension=asanka.so

9) Now every things ok. Write a php file with the following content and place it in the "htdocs" directory of the apache server,

asanka_setValue(10);
asanka_increment();
asanka_increment();
echo asanka_getValue();

Check whether your web browser displays the correct output. If you see number 12, then your C library works correctly with the php module.