diff options
Diffstat (limited to 'Doc/Manual/Php.html')
| -rw-r--r-- | Doc/Manual/Php.html | 149 |
1 files changed, 72 insertions, 77 deletions
diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 52bedf87f..d0ec0df7f 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Php">34 SWIG and PHP</a></H1> +<H1><a name="Php">31 SWIG and PHP</a></H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -50,20 +50,13 @@ <p> -In this chapter, we discuss SWIG's support of PHP. The PHP module -was extensively rewritten in release 1.3.26, and support for generating -OO wrappers for PHP5 was added in 1.3.30. The PHP module now supports most -of the features available in some of the other languages. +In this chapter, we discuss SWIG's support of PHP. SWIG currently supports +generating wrappers for PHP7. Support for PHP5 was removed in SWIG 4.0.0 +and support for PHP4 was removed in SWIG 1.3.37. </p> <p> -SWIG supports generating wrappers for PHP5 and PHP7. Support for PHP4 was removed -in SWIG 1.3.37. -</p> - -<p> -Currently any PHP5 or PHP7 release should work, but we don't regularly test with -PHP < 5.3. +Currently any PHP7 release should work. </p> <p> @@ -77,13 +70,13 @@ your extension into php directly, you will need the complete PHP source tree available. </p> -<H2><a name="Php_nn1">34.1 Generating PHP Extensions</a></H2> +<H2><a name="Php_nn1">31.1 Generating PHP Extensions</a></H2> <p> -To build a PHP extension, run swig using the <tt>-php5</tt> or -<tt>-php7</tt> option as follows (<tt>-php</tt> is also supported -and currently is an alias for <tt>-php5</tt>): +To build a PHP extension, run swig using the <tt>-php7</tt> option as follows +(<tt>-php</tt> is also supported and currently is an alias for <tt>-php7</tt> +but prior to SWIG 4.0.0 it was an alias for <tt>-php5</tt>): </p> <div class="code"><pre> @@ -107,9 +100,7 @@ also contain PHP class wrappers. 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>. The generated -C++ wrapper will be called example_wrap.cpp (for PHP5) or -example_wrap.cxx (for PHP7 where the default has been changed to align -with SWIG's default for every other language). You can specify a +C++ wrapper will be called example_wrap.cxx. You can specify a different extension for the C++ wrapper using <tt>-cppext</tt> - e.g. if you want example_wrap.cc use <tt>-cppext cc</tt>. </p> @@ -128,7 +119,7 @@ and it doesn't play nicely with package system. We don't recommend this approach, or provide explicit support for it. </p> -<H3><a name="Php_nn1_1">34.1.1 Building a loadable extension</a></H3> +<H3><a name="Php_nn1_1">31.1.1 Building a loadable extension</a></H3> <p> @@ -143,7 +134,7 @@ least work for Linux though): gcc -shared example_wrap.o example.o -o example.so </pre></div> -<H3><a name="Php_nn1_3">34.1.2 Using PHP Extensions</a></H3> +<H3><a name="Php_nn1_3">31.1.2 Using PHP Extensions</a></H3> <p> @@ -162,8 +153,8 @@ If the module is in PHP's default extension directory, you can omit the path. <p> For some SAPIs (for example, the CLI SAPI) you can instead use the -<a href="http://php.net/manual/en/function.dl.php">dl() function</a> to load -an extension at run time, by adding a like like this to the start of each +<a href="https://www.php.net/manual/en/function.dl.php">dl() function</a> to load +an extension at run time, by adding a line like this to the start of each PHP script which uses your extension: </p> @@ -172,8 +163,8 @@ PHP script which uses your extension: </pre></div> <p> -But note that this doesn't work when running PHP through a webserver in PHP5.3 -and later - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as +But note that <tt>dl()</tt> isn't supported when running PHP through a +webserver - you'll need to use <tt>extension</tt> in <tt>php.ini</tt> as described above. </p> @@ -191,7 +182,7 @@ This PHP module also defines the PHP classes for the wrapped API, so you'll almost certainly want to include it anyway. </p> -<H2><a name="Php_nn2">34.2 Basic PHP interface</a></H2> +<H2><a name="Php_nn2">31.2 Basic PHP interface</a></H2> <p> @@ -199,10 +190,11 @@ It is important to understand that PHP uses a single global namespace into which all symbols from extension modules are loaded. It is quite possible for names of symbols in one extension module to clash with other symbols unless care is taken to <tt>%rename</tt> them. At present -SWIG doesn't have support for the namespace feature added in PHP 5.3. +SWIG doesn't have support for generating wrappers which make use of PHP's +namespace feature. </p> -<H3><a name="Php_nn2_1">34.2.1 Constants</a></H3> +<H3><a name="Php_nn2_1">31.2.1 Constants</a></H3> <p> @@ -239,10 +231,12 @@ echo "E = " . E . "\n"; <p> There's one peculiarity of how constants work in PHP which it is useful to note (this is not specific to SWIG though) - if you try to use an undeclared -constant, PHP will emit a notice and then expand the constant to a string -version of the constant's name. Unfortunately it is easy to miss the notice -if you're using PHP in a webserver, as it will probably end up in error.log or -similar. +constant, PHP will emit a warning (or a notice in PHP 7.1 and earlier) and then +expand the constant to a string version of the constant's name. Unfortunately +it is easy to miss the warning message if you're using PHP in a webserver as +it will probably end up in error.log or similar. Apparently this will throw +an Error in a future version of PHP, but until then it's something to be +aware of. </p> <p> @@ -276,11 +270,10 @@ if(EASY_TO_MISPEL) { <p> The mis-spelled constant will become the string 'EASY_TO_MISPEL', which is treated as true by the if test, when the value of the intended constant -would be treated as false! Modern versions of PHP will at least issue -a PHP notice by default when this happens. +would be treated as false! </p> -<H3><a name="Php_nn2_2">34.2.2 Global Variables</a></H3> +<H3><a name="Php_nn2_2">31.2.2 Global Variables</a></H3> <p> @@ -329,7 +322,7 @@ undefined. At this time SWIG does not support custom accessor methods. </p> -<H3><a name="Php_nn2_3">34.2.3 Functions</a></H3> +<H3><a name="Php_nn2_3">31.2.3 Functions</a></H3> <p> @@ -382,7 +375,7 @@ print $s; # The value of $s was not changed. --> -<H3><a name="Php_nn2_4">34.2.4 Overloading</a></H3> +<H3><a name="Php_nn2_4">31.2.4 Overloading</a></H3> <p> @@ -390,8 +383,7 @@ 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 -href="SWIGPlus.html#SWIGPlus_overloaded_methods">Wrapping -Overloaded Functions and Methods</a>. +href="SWIGPlus.html#SWIGPlus_overloaded_methods">Overloaded functions and methods</a>. </p> <!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality @@ -438,7 +430,7 @@ taking the integer argument. </p> --> -<H3><a name="Php_nn2_5">34.2.5 Pointers and References</a></H3> +<H3><a name="Php_nn2_5">31.2.5 Pointers and References</a></H3> <p> @@ -527,13 +519,6 @@ named typemap REF. </p> <p> -Prior to SWIG 3.0, the REF typemaps relied on PHP's call-time -pass-by-reference, which was deprecated in PHP 5.3 and removed in PHP 5.4. -So if you use these REF typemaps, you should ensure that SWIG≥3.0 is -used to generate wrappers from your interface file. -</p> - -<p> In case you write your own typemaps, SWIG supports an attribute called <tt>byref</tt>: if you set that, then SWIG will make sure that the generated wrapper function will want the input parameter as a reference. @@ -583,7 +568,7 @@ PHP in a number of ways: by using <tt>unset</tt> on an existing variable, or assigning <tt>NULL</tt> to a variable. </p> -<H3><a name="Php_nn2_6">34.2.6 Structures and C++ classes</a></H3> +<H3><a name="Php_nn2_6">31.2.6 Structures and C++ classes</a></H3> <p> @@ -644,7 +629,7 @@ Would be used in the following way from PHP: Member variables and methods are accessed using the <tt>-></tt> operator. </p> -<H4><a name="Php_nn2_6_1">34.2.6.1 Using -noproxy</a></H4> +<H4><a name="Php_nn2_6_1">31.2.6.1 Using -noproxy</a></H4> <p> @@ -670,7 +655,7 @@ Complex_im_set($obj, $d); Complex_im_get($obj); </pre></div> -<H4><a name="Php_nn2_6_2">34.2.6.2 Constructors and Destructors</a></H4> +<H4><a name="Php_nn2_6_2">31.2.6.2 Constructors and Destructors</a></H4> <p> @@ -711,7 +696,7 @@ the programmer can either reassign the variable or call <tt>unset($v)</tt> </p> -<H4><a name="Php_nn2_6_3">34.2.6.3 Static Member Variables</a></H4> +<H4><a name="Php_nn2_6_3">31.2.6.3 Static Member Variables</a></H4> <p> @@ -754,7 +739,7 @@ Ko::threats(10); echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> -<H4><a name="Php_nn2_6_4">34.2.6.4 Static Member Functions</a></H4> +<H4><a name="Php_nn2_6_4">31.2.6.4 Static Member Functions</a></H4> <p> @@ -776,7 +761,7 @@ Ko::threats(); </pre></div> -<H4><a name="Php_nn2_6_5">34.2.6.5 Specifying Implemented Interfaces</a></H4> +<H4><a name="Php_nn2_6_5">31.2.6.5 Specifying Implemented Interfaces</a></H4> <p> @@ -794,7 +779,7 @@ so: If there are multiple interfaces, just list them separated by commas. </p> -<H3><a name="Php_nn2_7">34.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> +<H3><a name="Php_nn2_7">31.2.7 PHP Pragmas, Startup and Shutdown code</a></H3> <p> @@ -821,6 +806,15 @@ echo "example.php execution\n"; </pre></div> <p> +The <b>version</b> pragma can be used to add version to generated PHP extension module. The version is inserted in the zend_module_entry block. +</p> + +<div class="code"><pre> +%module example +%pragma(php) version="1.5" +</pre></div> + +<p> The <b>include</b> pragma is a short cut to add include statements to the example.php file. </p> @@ -882,7 +876,7 @@ The <tt>%rinit</tt> and <tt>%rshutdown</tt> statements are very similar but inse into the request init (PHP_RINIT_FUNCTION) and request shutdown (PHP_RSHUTDOWN_FUNCTION) code respectively. </p> -<H2><a name="Php_nn3">34.3 Cross language polymorphism</a></H2> +<H2><a name="Php_nn3">31.3 Cross language polymorphism</a></H2> <p> @@ -917,7 +911,7 @@ wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Php_nn3_1">34.3.1 Enabling directors</a></H3> +<H3><a name="Php_nn3_1">31.3.1 Enabling directors</a></H3> <p> @@ -944,7 +938,7 @@ globally, to specific classes, and to specific methods, like this: // generate directors for all classes that have virtual methods %feature("director"); -// generate directors for all virtual methods in class Foo +// generate directors for the virtual methods in class Foo %feature("director") Foo; </pre> </div> @@ -962,7 +956,7 @@ directors for specific classes or methods. So for example, </div> <p> -will generate directors for all virtual methods of class Foo except +will generate directors for the virtual methods of class Foo except bar(). </p> @@ -977,14 +971,14 @@ the methods one() and two() (but not three()): %feature("director") Foo; class Foo { public: - Foo(int foo); - virtual void one(); - virtual void two(); + Foo(int foo); + virtual void one(); + virtual void two(); }; class Bar: public Foo { public: - virtual void three(); + virtual void three(); }; </pre> </div> @@ -1006,7 +1000,7 @@ class MyFoo extends Foo { </div> -<H3><a name="Php_nn3_2">34.3.2 Director classes</a></H3> +<H3><a name="Php_nn3_2">31.3.2 Director classes</a></H3> @@ -1027,7 +1021,8 @@ For simplicity let's ignore the <tt>Swig::Director</tt> class and refer to the original C++ class as the director's base class. By default, a director class extends all virtual methods in the inheritance chain of its base class (see the preceding section for how to modify this behavior). -Thus all virtual method calls, whether they originate in C++ or in +Virtual methods that have a final specifier are unsurprisingly excluded. +Thus the virtual method calls, whether they originate in C++ or in PHP via proxy classes, eventually end up in at the implementation in the director class. The job of the director methods is to route these method calls to the appropriate place in the inheritance chain. By "appropriate @@ -1086,7 +1081,7 @@ so there is no need for the extra overhead involved with routing the calls through PHP. </p> -<H3><a name="Php_nn3_3">34.3.3 Ownership and object destruction</a></H3> +<H3><a name="Php_nn3_3">31.3.3 Ownership and object destruction</a></H3> <p> @@ -1116,12 +1111,12 @@ Here is an example: <pre> class Foo { public: - ... + ... }; class FooContainer { public: - void addFoo(Foo *); - ... + void addFoo(Foo *); + ... }; </pre> </div> @@ -1142,7 +1137,7 @@ In this example, we are assuming that FooContainer will take care of deleting all the Foo pointers it contains at some point. </p> -<H3><a name="Php_nn3_4">34.3.4 Exception unrolling</a></H3> +<H3><a name="Php_nn3_4">31.3.4 Exception unrolling</a></H3> <p> @@ -1166,9 +1161,9 @@ should suffice in most cases: <div class="code"> <pre> %feature("director:except") { - if ($error == FAILURE) { - throw Swig::DirectorMethodException(); - } + if ($error == FAILURE) { + throw Swig::DirectorMethodException(); + } } </pre> </div> @@ -1195,8 +1190,8 @@ suitable exception handler: <div class="code"> <pre> %exception { - try { $action } - catch (Swig::DirectorException &e) { SWIG_fail; } + try { $action } + catch (Swig::DirectorException &e) { SWIG_fail; } } </pre> </div> @@ -1209,7 +1204,7 @@ Swig::DirectorMethodException is thrown, PHP will register the exception as soon as the C wrapper function returns. </p> -<H3><a name="Php_nn3_5">34.3.5 Overhead and code bloat</a></H3> +<H3><a name="Php_nn3_5">31.3.5 Overhead and code bloat</a></H3> <p> @@ -1242,7 +1237,7 @@ optimized by selectively enabling director methods (using the %feature directive) for only those methods that are likely to be extended in PHP. </p> -<H3><a name="Php_nn3_6">34.3.6 Typemaps</a></H3> +<H3><a name="Php_nn3_6">31.3.6 Typemaps</a></H3> <p> @@ -1256,7 +1251,7 @@ need to be supported. </p> -<H3><a name="Php_nn3_7">34.3.7 Miscellaneous</a></H3> +<H3><a name="Php_nn3_7">31.3.7 Miscellaneous</a></H3> <p> Director typemaps for STL classes are mostly in place, and hence you |