usage note of swig for php
TRANSCRIPT
Index What is SWIG? ..................................................................................................................................................... 3
Install SWIG Tool & Library............................................................................................................................... 4
SWIG for PHP....................................................................................................................................................... 6
Generate and Install PHP Extension................................................................................................................... 7
Use PHP Extension.............................................................................................................................................. 18
What is SWIG? SWIG, Simplified Wrapper and Interface Generator, is a software development tool for building scripting
language interfaces to C and C++ programs. It is a kind of interface definition/description language (IDL).
Originally developed in 1995, SWIG was first used by scientists in the Theoretical Physics Division at Los
Alamos National Laboratory for building user interfaces to simulation codes running on the Connection
Machine 5 supercomputer.
SWIG was originally designed to make it extremely easy for scientists and engineers to build extensible
scientific software without having to get a degree in software engineering. It simplifies the task of interfacing
different languages to C and C++ programs by largely automating the task of language integration--allowing
developers and users to focus on more important problems.
In a nutshell, SWIG is a compiler that takes C/C++ declarations and creates the wrappers needed to access
those declarations from other languages including Perl, PHP, Python, Tcl, Ruby, Guile, and Java. SWIG
normally requires no modifications to existing code and can often be used to build a usable interface in only a
few minutes.
SWIG official site:
* http://swig.org/
SWIG documentation and tutorial:
* http://swig.org/doc.html
* http://swig.org/tutorial.html
Download SWIG source archive for different operating system platforms:
* http://sourceforge.net/projects/swig/files/
Example codes for this documentation could be downloaded from the GitHub:
https://github.com/wiliwe/swig-php-example
Install SWIG Tool & Library The environment used in this document:
* Linux CentOS 6.5 64-bit (could be updated to 6.6 or 6.7)
* GCC C/C++ compiler v4.9.0 (which support C++11 and C++14 standards)
* SWIG v3.0.7 (released on 2015-08-03)
(Note that in console/terminal, type “swig -version”, it will show v1.3.40)
* PHP v5.3.3
* Qt Creator v3.3.1 IDE tool
Before installing the SWIG v3.0.7, please remove the old built-in SWIG from CentOS 6.5:
$ su (change to root)
# yum erase swig
Build & Install SWIG tool and libraries
The SWIG tool/library installation guide is described in “Installation” section of chapter 1, “Preface.”
1) Donwload the SWIG v3.0.7 source archive for Unix/Linux, swig-3.0.7.tar.gz, from the site:
http://sourceforge.net/projects/swig/files/swig/swig-3.0.7/
2) Unpack swig-3.0.7.tar.gz to generate a folder named “swig-3.0.7”.
3) Enter the folder “swig-3.0.7” and run below commands to build and install SWIG tool and library:
$ ./configure --prefix=/usr --libdir=/usr/lib64
$ make
$ su (change to root)
# make install
By default SWIG installs itself in “/usr/local”. The installation path could be found in the file config.log
which is under the directory “swig-3.0.7”. In config.log , search “prefix=” and “libdir=” variable
assignments and you could see the installation path.
After installing, run “swig -version” to verify the version of the SWIG is what we set.
4) It could use command “swig -swiglib” tool to find out where SWIG thinks its library is located (be sure
SWIG tool and library are installed properly before running this command).
SWIG for PHP For PHP scripting language, SWIG generates PHP Extensions (or called modules) for gluing C or C++ codes.
PHP extension is as a dynamically loaded library: in MSFT Windows, it is DLL(.dll) ; in Unix/Linux, it is
SO(.so); in Apple Mac OS X, it is DYLIB(.dylib).
The location of PHP built-in modules could be found from the result of execution of PHP phpinfo() function:
In SWIG documentaiton 3.0 (http://swig.org/Doc3.0/index.html), chapter 4 explain the relationship between
scripting language (pythong, PHP, perl, etc) and C/C++ languages.
Generate and Install PHP Extension Basic steps of using SWIG are as below:
1) Write a SWIG interface file describing the interface name and its parameter. The interface files usually end
with “.i” extension name which stands for “interface.”
Below snapshots are examples for SWIG interface writing. It could declare all interfaces name in the
interface file or use a header to contain it and include this header file into the interface file.
<Non Header Way>
< Header way>
2) Use SWIG tool(swig) with the written interface file as input to generate files for building out
extension/module file of target language.
Below commands are for building out PHP extensions from C and C++, you could put then into a Make file and
make it. Remember that it MUST run “swig” tool to generate C or C++ wrapping source and header files for
the generation of PHP extension file as the FIRST step.
For generating PHP extension, it needs PHP development library header, so run below commands to install it:
$ su (change to root)
# yum install php-devel.x86_64
<For C>
swig -php swigphp.i (replace “swigphp.i” with your SWIG interface file name)
gcc `php-config --includes` -fpic -c swigphp_wrap.c swigphp.c
gcc -shared swigphp_wrap.o helloswig.o -o swigphp.so
Running “swig” tool for C++ will generate three files:
* swigphp_wrap.c
* php_swigphp.h
* swigphp.php
<For C++>
swig -c++ -php swigphp.i (replace “swigphp.i” with your SWIG interface file name)
g++ `php-config --includes` -fpic -c swigphp_wrap.cpp swigphp.cpp
g++ -shared swigphp_wrap.o swigphp.o -o swigphp.so
Running “swig” tool for C++ will generate three files:
* swigphp_wrap.cpp
* php_swigphp.h
* swigphp.php
Below snapshots show an example of generation and compilation of a PHP extension, helloswigc.so.
Besides command line way, it could use Qt Creator IDE and QMake to build out PHP extension. The Qt
Creator project setup steps are show below. The needed C or C++ source files are needed to be generated
through “swig” tool in advance.
1) Create a whole new Qt project by clicking these items:
“Library” -> “C++ Library”
In project window, remove the Qt Creator generated files.
Add C or C++ source files generated by “swig” tool into Qt Creator project.
* php_SWIG-Module-Name.h
* SWIG-Module-Name _wrap.c (for C)
or
SWIG-Module-Name _wrap.cpp (for C++).
5) In Qt PRO file, change the value of TARGET variable for output file name you want.
6) In Qt PRO file, add below line for searching PHP zend.h file when building.
QMAKE_CXXFLAGS += `php-config --includes`
Also, add C++10 standard supporting flag.
QMAKE_CXXFLAGS += -std=c++0x
7) Uncheck “Projects-> Build & Run -> Shadow build“ for “Debug” and “Release”.
8) Start to build by clicking “Build” button (a hammer icon) on IDE’s side panel.
9) After building out SWIG PHP extension SO file successfully, it will generate the file "libhelloswigc.so.1.0.0"
whose version number may not be “1.0.0”, it is up to your setting.
Change extension file name from " libhelloswigc.so.1.0.0" to "helloswigc.so".
Install PHP Extension
Edit /etc/php.ini , in "Dynamic Extensions" section, add this line:
extension = helloswigc.so
Drop down to change to
Debug or Release.
It could add more than one lines of “extension=” for multiple PHP extension loading.
Save /etc/php.ini and use “php -m” command to verify if it could load new assigned PHP extension
successfully.
If a PHP extension file specified in php.ini does not exist under PHP extension folder, it will show below error
message:
Finally, restart Apache through the commands:
$ su (change to root)
# service httpd restart
Note that the PHP configuration file, php.ini, may locate in other folder. You could find it through put a PHP
page(file name ends with ".php") under /var/www/html folder and the page's contents are as below:
In Web browser, to browse this PHP page, if it could be run successfully, it will show information about PHP.
<?php
phpinfo();
?>
Note
When running “php -m” If it could not find one or more needed libraries the PHP extension
depends on, it will show error message that tell you which library could not be found.
Look at the entry having the string "Loaded Configuration File" , it shows the actual path to php.ini file.
Run below commands in root to put "helloswigc.so" file to PHP module folder.
$ su (change to root)
# cp ./helloswigc.so `php-config --extension-dir`
, where `php-config --extension-dir` option will output the path to PHP module folder.
Note
<1> When building C++ file, it MUST use g++ or c++ instead of gcc compiler, or it will happen error when
loading PHP extension/module that it will say it could not find name mangling/decoration symbol as
below snapshot.
<2> For earlier version of SWIG, if the version of PHP library for building PHP extension is not the same as
the one you will run on, it might show this error message when running “php -m” command:
“Unable to initialize module”
, see below sites for more information:
* http://php.net/manual/en/solr.installation.php
* http://stackoverflow.com/questions/2394532/apache-is-unable-to-initialize-module-because-of-modules-and-phps-api-dont
* http://stackoverflow.com/questions/3130910/php-warning-php-startup-unable-to-initialize-module
Use PHP Extension
Write a PHP file including “swig” tool generated PHP file and call the interface specified in SWIG interface file.
Below snapshot shows an example that helloswigc_test.php includes helloswigc.php which was generated by
“swig” tool.
In Web browser, locate to helloswigc_test.php, if anything is okay, it could show the result what you want.
It could use “php” tool to run PHP page. For example:
$ php -c . /var/www/html/ helloswigc_test.php
Note
If one or more PHP extensions contain more than one identical class names or macro without using namespace
to isolate it, it will cause fatal errors and let Apache Web server crash, it will not boot successfully until the class
name confilict issue is remove.