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.

Fundamental issue in the integration of php-tsql module and tikirisql library.

I think we've faced with a serious problem in works. Yesterday night I was working on integration of the php-tsql module with the tikirisql library. I was faced with a situation where it's hard to compile the integrated php module since it's makefile is an auto generated one. I think our tikirisql library makes us troubles since it's coded for a general purpose. I directly called the tikirisql's functions inside the php-tsql module. Then I compiled and placed it in my php extensions directory. When I try to run a testing php script in apache server which uses our php modules functions, the php file's going to be downloaded without rendering on the browser.
I think most probably the reason should be the usage of tikirisql's C files and header files within the php module. There may be some restrictions by the creators of php about the way we create extensions to the php.
Sometimes the same problem may have been encountered by the MySQL community who use a very simple php module which does only the exchanging of the web client's queries to MySQL server and results back to clients browser. They doesn't do parsing stuff in php module. I looked at the mysql module in php. It's very simple with only the standard source files. Those standard files are in each and every module in php. As I understand everything the mysql people has changed is the content in those source files. They have written new functions and called them. Therefore I think there may be a big reason for not using external libraries inside php modules.
I think we have to study more about the php internals to understand the problem and to find a possible solution.

Initial installations before developing php extensions.

To develop php extensions we have to be installed php in our system. Since it takes time and involve lot of works we can easily forget the steps we have to follow. Therefore I decided to document the steps I followed when setting up my development environment. I use UBUNTU 9.04 as my platform for php-tsql research works. Before we do anything it's necessary to install some development tools which require in extension development life cycle. Therefore you first install the latest versions of following packages in to you system.

1. libxml2 (which is required to compile php source code)
2. libtool
3 make
4. automake
5. autoconf
6. m4
7. bison

But remember that some of the packages may require some other once to be installed previously. If the installation stop somewhere, look at the error and install the requesting package first. Then you can install the interrupted package again. These kind of installations require a huge patience because it may take lot of time in progress printing different things and finally give you an error saying, without a particular package it cannot continue. Then you have to install that package patiently. All you have to do to install each package is,

step 1: Decompress the the package file.
step 2: Go into the package directory.
step 4: Give the commands,

./configure
make
sudo make install


Now I assume you have installed those packages. Now It's time to install apache server and php. download the sources of apache2 and php. Decompress the package files and spend some time reading readme files in those. I think most important one is INSTALL file in php. Now we're installing apache2.

step 1: Decompress the the apache2 package file.
step 2: Go into the package directory.
step 3: To configure and install apache2 give the command,

./configure --enable-so
make
sudo make install

To check whether apache2 installed correctly start the apache2 server normally. eg:

sudo /usr/local/apache2/bin/apachectl start

Open your wed browser and go to localhost, it should show the message "It Works"
To stop the server,

sudo /usr/local/apache2/bin/apachectl stop

Now apache2 is ok. Its time for php installation.

step 1: Decompress the php package file.
step 2: Go into the package directory.
step 3: To configure and install php give the command,

./configure --with-apxs2=/usr/local/apache2/bin/apxs
make
sudo make install

If these steps completed without any error, php is installed. But you have to do some more before you start using php.

step 4: To setup your php.ini file, give the command

cp php.ini-development /usr/local/lib/php.ini

step 5: You have to make sure whether apache2 is aware of the installed php. Open the file httpd.conf (it should be in /usr/local/apache2/conf directory) and check whether this kind of an entry is there in the file,

LoadModule php5_module modules/libphp5.so

If not, put that line in the file.

step 5: In that httpd.conf file put this line also in the correct position,

AddType application/x-httpd-php .php .phtml

Now php also installed correctly. To check whether php is working, copy following code to a php files body named testinfo.php and put it in the htdocs directory of apache2.

phpinfo();


Now start apache2 server and go to the URL http://localhost/testinfo.php. It should give you the phpinfo page. If so, it confirms that php also working.
Here's a good reference with more detailed description about compiling from the source,
http://www.web-tech-india.com/articles/php/compiling_php_apache/

All the best & Enjoy your extensions developing works with this new platform. There's an article on extension writing in this blog. Better to read it.