From 837152eebbbca1fec0dfaac3eb3f3baf79fd59e6 Mon Sep 17 00:00:00 2001 From: Olly Betts Date: Fri, 10 Nov 2006 01:28:28 +0000 Subject: [PATCH] Initial update for PHP5 support and overload resolution changes. git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk/SWIG@9539 626c5289-ae23-0410-ae9c-e8d60b6d4f22 --- Doc/Manual/Contents.html | 10 +- Doc/Manual/Php.html | 191 ++++++++++++++++++++++++--------------- 2 files changed, 121 insertions(+), 80 deletions(-) diff --git a/Doc/Manual/Contents.html b/Doc/Manual/Contents.html index 4c0670386..04acb08c1 100644 --- a/Doc/Manual/Contents.html +++ b/Doc/Manual/Contents.html @@ -1042,18 +1042,18 @@ -

27 SWIG and PHP4

+

27 SWIG and PHP

diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index c1d2cf6b7..1483f0137 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -2,22 +2,22 @@ -SWIG and PHP4 +SWIG and PHP -

27 SWIG and PHP4

+

27 SWIG and PHP

@@ -44,64 +44,70 @@

-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.

-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 -noproxy 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.

-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 'php-config --includes'. 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 php-config --includes. 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.

-

27.1 Generating PHP4 Extensions

+

27.1 Generating PHP Extensions

-To build a PHP4 extension, run swig using the -php4 option as -follows : +To build a PHP extension, run swig using the -php option as +follows: 

-swig -php4 example.i
+swig -php example.i

This will produce 3 files example_wrap.c, php_example.h and example.php. The first file, example_wrap.c contains all of -the C code needed to build a PHP4 extension. The second file, -php_example.h contains the header information needed to -statically link the extension into PHP. The third file, -example.php can be included by php scripts. It attempts to +the C code needed to build a PHP extension. The second file, +php_example.h contains the header information needed if +you wish to statically link the extension into the php interpreter. +The third file, +example.php 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.

-Swig can generate PHP4 extensions from C++ libraries as well when +Swig can generate PHP extensions from C++ libraries as well when given the -c++ option. The support for C++ is discussed in more detail in section 27.2.6.

-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 php.ini 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.

27.1.1 Building a loadable extension

@@ -110,7 +116,7 @@ the '-phpfull' command line switch to select the second build method.

There are two methods to build the extension as a dynamically loaded module: using standard compilation utilities (make, gcc), or using -PHP4's phpize utility. +PHP's phpize utility.

@@ -124,12 +130,12 @@ OS):

The -make command line argument to swig will generate an -additional file Makefile. This Makefile can usually build the -extension itself (on unix platforms). +additional file Makefile which can usually build the +extension itself (on UNIX platforms).

- If you want to build your extension using the phpize +If you want to build your extension using the phpize utility, or if you want to build your module into PHP directly, you can specify the -phpfull command line argument to swig.

@@ -137,7 +143,7 @@ can specify the -phpfull command line argument to swig.

The -phpfull will generate three additional files. The first extra file, config.m4 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, Makefile.in contains the information needed to build the final Makefile after substitutions. The third and final extra file, CREDITS 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. 

-	swig -php4 -phpfull
+	swig -php -phpfull

@@ -170,9 +176,9 @@ the configure file, you may need to edit the Makefile.in 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 Makefile.in, 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. +Makefile.in and config.m4 which need no further editing.

@@ -204,9 +210,9 @@ in each script.

-After running swig with the -phpfull switch, you will be left with a shockingly +After running swig with the -phpfull 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. mkdir php-4.0.6/ext/modulename).

@@ -226,18 +232,19 @@ make use of -withlibs and -withincs 

-	swig -php4 -phpfull -withlibs "xapian omquery" --withincs "om.h"
+	swig -php -phpfull -withlibs "xapian omquery" --withincs "om.h"

-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 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.

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.

-

27.1.3 Using PHP4 Extensions

+

27.1.3 Using PHP Extensions

-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 [PHP] section of +php.ini: +

+ +
+	extension=/path/to/modulename.so
+
+ +

+Alternatively, you can load it explicitly only for scripts which need it +by adding this line: 

@@ -264,7 +281,7 @@ this by putting the line,

-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 dl() call for you:

@@ -272,9 +289,7 @@ attempts to do the dl() call for you: include("example.php"); - - -

27.2 Basic PHP4 interface

+

27.2 Basic PHP interface

@@ -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 %constant 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, 

@@ -319,7 +334,7 @@ echo "E = " . E . "\n";

-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,

@@ -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!

@@ -413,7 +428,7 @@ Apologies, this paragraph needs rewriting to make some sense. )

-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.

@@ -485,8 +500,9 @@ $c = bar(3.5); # Use default argument for 2nd parameter +

27.2.4 Overloading

-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 %typecheck typemaps to allow overloading. This dispatch function's operation and precedence is described in Wrapping Overloaded Functions and Methods.

+

27.2.5 Pointers and References

@@ -680,7 +699,8 @@ echo "The sum $in1 + $in2 = $result\n";

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 add. Depending on the implementation of the function, this @@ -698,9 +718,20 @@ variable, or assigning NULL to a variable.

-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 -php4 or -php5 (currently +-php generates PHP4 class wrappers for compatibility with +SWIG 1.3.29 and earlier, but this may change in the future). +

+ +

+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.

@@ -724,7 +755,7 @@ struct Complex {

-Would be used in the following way: +Would be used in the following way from either PHP4 or PHP5: 

@@ -758,7 +789,8 @@ Member variables and methods are accessed using the -> operator.
 
 

 The -noproxy 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:
 

 
@@ -790,7 +822,7 @@ constructor to execute.
 

 
 

-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:
 

 
@@ -823,8 +855,10 @@ the programmer can either reassign the variable or call
 
 
 

-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
 

 
@@ -849,7 +883,8 @@ echo "There has now been " . Ko::threats() . " threats\n";

-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. 

@@ -863,7 +898,7 @@ echo "There has now been " . Ko::threats() . " threats\n";
 
 
 

-Class functions are supported in PHP using the
+Static member functions are supported in PHP using the
 class::function() syntax.  For example
 

 
@@ -881,9 +916,15 @@ Ko::threats();
-

27.2.7 PHP4 Pragmas, Startup and Shutdown code

+

27.2.7 PHP Pragmas, Startup and Shutdown code

+

+Note: Currently pragmas for PHP need to be specified using +%pragma(php4) but also apply for PHP5! This is just a historical +oddity because SWIG's PHP support predates PHP5. +

+

To place PHP code in the generated "example.php" file one can use the code pragma. The code is inserted after loading the shared