jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial update for PHP5 support and overload resolution changes.

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@9539 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Olly Betts 2006-11-10 01:28:28 +00:00
commit 837152eebb
2 changed files with 121 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

10
Doc/Manual/Contents.html
View file

@ -1042,18 +1042,18 @@
</div>
<!-- INDEX -->
<h3><a href="Php.html#Php">27 SWIG and PHP4</a></h3>
<h3><a href="Php.html#Php">27 SWIG and PHP</a></h3>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="Php.html#Php_nn1">Generating PHP4 Extensions</a>
<li><a href="Php.html#Php_nn1">Generating PHP Extensions</a>
<ul>
<li><a href="Php.html#Php_nn1_1">Building a loadable extension</a>
<li><a href="Php.html#Php_nn1_2">Building extensions into PHP</a>
<li><a href="Php.html#Php_nn1_3">Using PHP4 Extensions</a>
<li><a href="Php.html#Php_nn1_3">Using PHP Extensions</a>
</ul>
<li><a href="Php.html#Php_nn2">Basic PHP4 interface</a>
<li><a href="Php.html#Php_nn2">Basic PHP interface</a>
<ul>
<li><a href="Php.html#Php_nn2_1">Constants</a>
<li><a href="Php.html#Php_nn2_2">Global Variables</a>
@ -1067,7 +1067,7 @@
<li><a href="Php.html#Php_nn2_6_3">Static Member Variables</a>
<li><a href="Php.html#Php_nn2_6_4">Static Member Functions</a>
</ul>
<li><a href="Php.html#Php_nn2_7">PHP4 Pragmas, Startup and Shutdown code</a>
<li><a href="Php.html#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
</ul>
</div>

191
Doc/Manual/Php.html
View file

@ -2,22 +2,22 @@
<!-- Hand crafted HTML -->
<html>
<head>
<title>SWIG and PHP4</title>
<title>SWIG and PHP</title>
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body bgcolor="#ffffff">
<H1><a name="Php"></a>27 SWIG and PHP4</H1>
<H1><a name="Php"></a>27 SWIG and PHP</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Php_nn1">Generating PHP4 Extensions</a>
<li><a href="#Php_nn1">Generating PHP Extensions</a>
<ul>
<li><a href="#Php_nn1_1">Building a loadable extension</a>
<li><a href="#Php_nn1_2">Building extensions into PHP</a>
<li><a href="#Php_nn1_3">Using PHP4 Extensions</a>
<li><a href="#Php_nn1_3">Using PHP Extensions</a>
</ul>
<li><a href="#Php_nn2">Basic PHP4 interface</a>
<li><a href="#Php_nn2">Basic PHP interface</a>
<ul>
<li><a href="#Php_nn2_1">Constants</a>
<li><a href="#Php_nn2_2">Global Variables</a>
@ -31,7 +31,7 @@
<li><a href="#Php_nn2_6_3">Static Member Variables</a>
<li><a href="#Php_nn2_6_4">Static Member Functions</a>
</ul>
<li><a href="#Php_nn2_7">PHP4 Pragmas, Startup and Shutdown code</a>
<li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a>
</ul>
</ul>
</div>
@ -44,64 +44,70 @@
</p>
<p>
In this chapter, we discuss SWIG's support of PHP4. The PHP4 module
has been extensively rewritten in release 1.3.26. Although it is
In this chapter, we discuss SWIG's support of PHP. The PHP module
was extensively rewritten in release 1.3.26, and although it is
significantly more functional, it still does not implement all the
features available in other languages.
features available in some of the other languages.
</p>
<p>
The examples and test cases have been developed with PHP4.
Support for PHP5 at this time is limited to wrapping C libraries or
C++ libraries while using the <tt>-noproxy</tt> flag. This deficiency
will be fixed in a subsequent release of SWIG.
The examples and test cases have been developed with PHP4. Release
1.3.30 added support for generating PHP5 class wrappers for C++
libraries.
</p>
<p>
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. You can find these
files by running <tt>'php-config --includes'</tt>. 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.
In order to use this module, you will need to have a copy of the PHP4 or PHP5
include files to compile the SWIG generated files. If you installed
PHP from a binary package, you may need to install a "php-dev" or "php-devel"
package for these to be installed. You can find out where these files are
by running <tt>php-config --includes</tt>. To use the built PHP module you
will need either the php binary or the Apache php module. If you want to build
your extension into php directly, you will need the complete PHP source tree
available.
</p>
<H2><a name="Php_nn1"></a>27.1 Generating PHP4 Extensions</H2>
<H2><a name="Php_nn1"></a>27.1 Generating PHP Extensions</H2>
<p>
To build a PHP4 extension, run swig using the <tt>-php4</tt> option as
follows :
To build a PHP extension, run swig using the <tt>-php</tt> option as
follows:
</p>
<div class="code"><pre>
swig -php4 example.i
swig -php example.i
</pre></div>
<p>
This will produce 3 files example_wrap.c, php_example.h and
example.php. The first file, <tt>example_wrap.c</tt> contains all of
the C code needed to build a PHP4 extension. The second file,
<tt>php_example.h</tt> contains the header information needed to
statically link the extension into PHP. The third file,
<tt>example.php</tt> can be included by php scripts. It attempts to
the C code needed to build a PHP extension. The second file,
<tt>php_example.h</tt> contains the header information needed if
you wish to statically link the extension into the php interpreter.
The third file,
<tt>example.php</tt> can be included by PHP scripts. It attempts to
dynamically load the extension and contains extra php code specified
in the interface file.
in the interface file. If wrapping C++ code for PHP5, it will
also contain PHP5 class wrappers.
</p>
<p>
Swig can generate PHP4 extensions from C++ libraries as well when
Swig can generate PHP extensions from C++ libraries as well when
given the <tt>-c++</tt> option. The support for C++ is discussed in
more detail in <a href="#Php_nn2_6">section 27.2.6</a>.
</p>
<p>
To finish building the extension, you have two choices. You can either build
the extension as a separate shared object file which will then have to be explicitly
loaded by each script. Or you can rebuild the entire php source tree and build
To finish building the extension, you have two choices. The usual way is
to build the extension as a separate dynamically loaded module. You can then
specify that this be loaded automatically in <tt>php.ini</tt> or
load it explicitly for any script which needs it. The alternative to
creating a dynamically loaded module is to
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 '-phpfull' command line switch to select the second build method.
the '-phpfull' command line switch to swig to select the second build method.
</p>
<H3><a name="Php_nn1_1"></a>27.1.1 Building a loadable extension</H3>
@ -110,7 +116,7 @@ the '-phpfull' command line switch to select the second build method.
<p>
There are two methods to build the extension as a dynamically loaded
module: using standard compilation utilities (make, gcc), or using
PHP4's <em>phpize</em> utility.
PHP's <em>phpize</em> utility.
</p>
<p>
@ -124,12 +130,12 @@ OS):
<p>
The <tt>-make</tt> command line argument to swig will generate an
additional file Makefile. This Makefile can usually build the
extension itself (on unix platforms).
additional file <tt>Makefile</tt> which can usually build the
extension itself (on UNIX platforms).
</p>
<p>
If you want to build your extension using the <tt>phpize</tt>
If you want to build your extension using the <tt>phpize</tt>
utility, or if you want to build your module into PHP directly, you
can specify the <tt>-phpfull</tt> command line argument to swig.
</p>
@ -137,7 +143,7 @@ can specify the <tt>-phpfull</tt> command line argument to swig.
<p>
The <tt>-phpfull</tt> will generate three additional files. The first
extra file, <tt>config.m4</tt> contains the shell code needed to
enable the extension as part of the PHP4 build process. The second
enable the extension as part of the PHP build process. The second
extra file, <tt>Makefile.in</tt> contains the information needed to
build the final Makefile after substitutions. The third and final
extra file, <tt>CREDITS</tt> should contain the credits for the
@ -151,17 +157,17 @@ 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,
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. ) If you like SWIG can generate simple extra tests for
phpize.) You can also get SWIG to generate simple extra tests for
libraries and header files for you.
</p>
<div class="code"><pre>
swig -php4 -phpfull
swig -php -phpfull
</pre></div>
<p>
@ -170,9 +176,9 @@ the configure file, you may need to edit the <tt>Makefile.in</tt>
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
them to the <tt>Makefile.in</tt>, or add the names of libraries if they are
needed. In simple cases SWIG is pretty good at generating a complete
Makefile.in and config.m4 which need no further editing.
<tt>Makefile.in</tt> and <tt>config.m4</tt> which need no further editing.
</p>
<p>
@ -204,9 +210,9 @@ in each script.
</p>
<p>
After running swig with the -phpfull switch, you will be left with a shockingly
After running swig with the <tt>-phpfull</tt> switch, you will be left with a shockingly
similar 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 .)
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. <tt>mkdir php-4.0.6/ext/modulename</tt>).
</p>
<p>
@ -226,18 +232,19 @@ make use of <tt>-withlibs</tt> and <tt>-withincs</tt>
</p>
<div class="code"><pre>
swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
swig -php -phpfull -withlibs "xapian omquery" --withincs "om.h"
</pre></div>
<p>
Will include in the config.m4 and Makefile.in search for libxapian.a or
libxapian.so and search for libomquery.a or libomquery.so as well as a
search for om.h
Will include in the <tt>config.m4</tt> and <tt>Makefile.in</tt> search for
<tt>libxapian.a</tt> or <tt>libxapian.so</tt> and search for
<tt>libomquery.a</tt> or <tt>libomquery.so</tt> as well as a
search for <tt>om.h</tt>.
</p>
<p>
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,
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
@ -251,12 +258,22 @@ which contains your new module. You can test it with a php script which
does not have the 'dl' command as used above.
</p>
<H3><a name="Php_nn1_3"></a>27.1.3 Using PHP4 Extensions</H3>
<H3><a name="Php_nn1_3"></a>27.1.3 Using PHP Extensions</H3>
<p>
To test the extension from a PHP script, you need to load it first. You do
this by putting the line,
To test the extension from a PHP script, you need to load it first. You
can load it for every script by adding this line the <tt>[PHP]</tt> section of
<tt>php.ini</tt>:
</p>
<div class="code"><pre>
extension=/path/to/modulename.so
</pre></div>
<p>
Alternatively, you can load it explicitly only for scripts which need it
by adding this line:
</p>
<div class="code"><pre>
@ -264,7 +281,7 @@ this by putting the line,
</pre></div>
<p>
at the start of each PHP file. SWIG also generates a php module, which
to the start of each PHP file. SWIG also generates a php module, which
attempts to do the <tt>dl()</tt> call for you:
</p>
@ -272,9 +289,7 @@ attempts to do the <tt>dl()</tt> call for you:
include("example.php");
</pre></div>
<H2><a name="Php_nn2"></a>27.2 Basic PHP4 interface</H2>
<H2><a name="Php_nn2"></a>27.2 Basic PHP interface</H2>
<p>
@ -292,7 +307,7 @@ These work in much the same way as in C/C++, constants can be defined
by using either the normal C pre-processor declarations, or the
<tt>%constant</tt> SWIG directive. These will then be available from
your PHP script as a PHP constant, (i.e. no dollar sign is needed to
access them. ) For example, with a swig file like this,
access them.) For example, with a swig interface file like this,
</p>
<div class="code"><pre>
@ -319,7 +334,7 @@ echo "E = " . E . "\n";
</div>
<p>
There are two peculiarities with using constants in PHP4. The first is that
There are two peculiarities with using constants in PHP. The first is that
if you try to use an undeclared constant, it will evaluate to a string
set to the constant's name. For example,
</p>
@ -352,7 +367,7 @@ if(EASY_TO_MISPEL) {
will issue a warning about the undeclared constant, but will then
evaluate it and turn it into a string ('EASY_TO_MISPEL'), which
evaluates to true, rather than the value of the constant which would
be false. This is a feature.
be false. This is a feature!
</p>
<p>
@ -413,7 +428,7 @@ Apologies, this paragraph needs rewriting to make some sense. )
<p>
Because PHP4 does not provide a mechanism to intercept access and
Because PHP does not provide a mechanism to intercept access and
assignment of global variables, global variables are supported through
the use of automatically generated accessor functions.
</p>
@ -485,8 +500,9 @@ $c = bar(3.5); # Use default argument for 2nd parameter
</pre></div>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
<p>
Because PHP4 is a dynamically typed language, the default typemaps
Because PHP is a dynamically typed language, the default typemaps
used for simple types will attempt to coerce the arguments into the appropriate type. That is the following invocations are equivalent:
</p>
@ -507,13 +523,14 @@ $s = "2 A string representing two";
$a = foo($s); # invokes 'foo(2)';
print $s; # The value of $s was not changed.
</pre></div>
-->
<H3><a name="Php_nn2_4"></a>27.2.4 Overloading</H3>
<p>
Although PHP4 does not support overloading functions natively, swig
Although PHP does not support overloading functions natively, swig
will generate dispatch functions which will use <tt>%typecheck</tt>
typemaps to allow overloading. This dispatch function's operation and
precedence is described in <a
@ -521,6 +538,7 @@ href="TypemapsSWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping
Overloaded Functions and Methods</a>.
</p>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
<p>
Because PHP4 is a dynamically typed language, simple values can be
silently converted from one type to another. For example, integers,
@ -562,6 +580,7 @@ void doit( int i );
Cause less confusion and <tt>doit("2");</tt> will invoke the function
taking the integer argument.
</p>
-->
<H3><a name="Php_nn2_5"></a>27.2.5 Pointers and References</H3>
@ -680,7 +699,8 @@ echo "The sum $in1 + $in2 = $result\n";
<p>
It is important to note that a php variable which is NULL when passed
by reference would end up passing a NULL pointer into the function.
In PHP, an unassigned variable (ie first reference is not assigned) is
In PHP, an unassigned variable (i.e. where the first reference to the
variable is not an assignment) is
NULL. In the above example, if any of the three variables had not
been assigned, a NULL pointer would have been passed into
<tt>add</tt>. Depending on the implementation of the function, this
@ -698,9 +718,20 @@ variable, or assigning <tt>NULL</tt> to a variable.
<p>
By default, SWIG represents structs and C++ classes using a PHP4
class. The PHP4 class is implemented entirely using the Zend C API so
no additional php code is generated.
SWIG defaults to wrapping C++ structs and classes with PHP classes. This
requires SWIG to generate different code for PHP4 and PHP5, so you must
specify which you want using <tt>-php4</tt> or <tt>-php5</tt> (currently
<tt>-php</tt> generates PHP4 class wrappers for compatibility with
SWIG 1.3.29 and earlier, but this may change in the future).
</p>
<p>
PHP4 classes are implemented entirely using the Zend C API so
no additional php code is generated. For PHP5, a PHP wrapper
class is generated which calls a set of flat functions wrapping the C++ class.
In many cases the PHP4 and PHP5 wrappers will behave the same way,
but the PHP5 ones make use of better PHP5's better OO funcationality
where appropriate.
</p>
<p>
@ -724,7 +755,7 @@ struct Complex {
</pre></div>
<p>
Would be used in the following way:
Would be used in the following way from either PHP4 or PHP5:
</p>
<div class="code"><pre>
@ -758,7 +789,8 @@ Member variables and methods are accessed using the <tt>-&gt;</tt> operator.
<p>
The <tt>-noproxy</tt> option flattens the object structure and
generates collections of named functions. The above example results
generates collections of named functions (these are the functions
which the PHP5 class wrappers call). The above example results
in the following PHP functions:
</p>
@ -790,7 +822,7 @@ constructor to execute.
</p>
<p>
Because PHP4 uses reference counting to manage resources, simple
Because PHP uses reference counting to manage resources, simple
assignment of one variable to another such as:
</p>
@ -823,8 +855,10 @@ the programmer can either reassign the variable or call
<p>
Class variables are not supported in PHP. Static member variables are
therefore accessed using a class function with the same name, which
Static member variables are not supported in PHP4, and it does not
appear to be possible to intercept accesses to static member variables
in PHP5. Therefore, static member variables are
wrapped using a class function with the same name, which
returns the current value of the class variable. For example
</p>
@ -849,7 +883,8 @@ echo "There has now been " . Ko::threats() . " threats\n";
</pre></div>
<p>
To set the static member variable, pass the value as the argument to the class function, e.g.
To set the static member variable, pass the value as the argument to the class
function, e.g.
</p>
<div class="code"><pre>
@ -863,7 +898,7 @@ echo "There has now been " . Ko::threats() . " threats\n";
<p>
Class functions are supported in PHP using the
Static member functions are supported in PHP using the
<tt>class::function()</tt> syntax. For example
</p>
@ -881,9 +916,15 @@ Ko::threats();
</pre></div>
<H3><a name="Php_nn2_7"></a>27.2.7 PHP4 Pragmas, Startup and Shutdown code</H3>
<H3><a name="Php_nn2_7"></a>27.2.7 PHP Pragmas, Startup and Shutdown code</H3>
<p>
Note: Currently pragmas for PHP need to be specified using
<tt>%pragma(php4)</tt> but also apply for PHP5! This is just a historical
oddity because SWIG's PHP support predates PHP5.
</p>
<p>
To place PHP code in the generated "example.php" file one can use the
<b>code</b> pragma. The code is inserted after loading the shared