diff options
Diffstat (limited to 'Doc/Manual/Php.html')
| -rw-r--r-- | Doc/Manual/Php.html | 110 |
1 files changed, 72 insertions, 38 deletions
diff --git a/Doc/Manual/Php.html b/Doc/Manual/Php.html index 493c861f8..623adb68a 100644 --- a/Doc/Manual/Php.html +++ b/Doc/Manual/Php.html @@ -7,7 +7,7 @@ </head> <body bgcolor="#ffffff"> -<H1><a name="Php"></a>33 SWIG and PHP</H1> +<H1><a name="Php"></a>34 SWIG and PHP</H1> <!-- INDEX --> <div class="sectiontoc"> <ul> @@ -29,6 +29,7 @@ <li><a href="#Php_nn2_6_2">Constructors and Destructors</a> <li><a href="#Php_nn2_6_3">Static Member Variables</a> <li><a href="#Php_nn2_6_4">Static Member Functions</a> +<li><a href="#Php_nn2_6_5">Specifying Implemented Interfaces</a> </ul> <li><a href="#Php_nn2_7">PHP Pragmas, Startup and Shutdown code</a> </ul> @@ -79,7 +80,7 @@ your extension into php directly, you will need the complete PHP source tree available. </p> -<H2><a name="Php_nn1"></a>33.1 Generating PHP Extensions</H2> +<H2><a name="Php_nn1"></a>34.1 Generating PHP Extensions</H2> <p> @@ -113,9 +114,7 @@ more detail in <a href="#Php_nn2_6">section 27.2.6</a>. <p> The usual (and recommended) way is to build the extension as a separate dynamically loaded module (which is supported by all modern operating -systems). You can then specify that this be loaded -automatically in <tt>php.ini</tt> or load it explicitly for any script which -needs it. +systems). </p> <p> @@ -126,7 +125,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"></a>33.1.1 Building a loadable extension</H3> +<H3><a name="Php_nn1_1"></a>34.1.1 Building a loadable extension</H3> <p> @@ -137,16 +136,16 @@ least work for Linux though): </p> <div class="code"><pre> - gcc `php-config --includes` -fpic -c example_wrap.c - gcc -shared example_wrap.o -o example.so + gcc `php-config --includes` -fpic -c example_wrap.c example.c + gcc -shared example_wrap.o example.o -o example.so </pre></div> -<H3><a name="Php_nn1_3"></a>33.1.2 Using PHP Extensions</H3> +<H3><a name="Php_nn1_3"></a>34.1.2 Using PHP Extensions</H3> <p> -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 to the <tt>[PHP]</tt> section of +To test the extension from a PHP script, you first need to tell PHP to +load it. To do this, add a line like this to the <tt>[PHP]</tt> section of <tt>php.ini</tt>: </p> @@ -155,8 +154,14 @@ can load it for every script by adding this line to the <tt>[PHP]</tt> section o </pre></div> <p> -Alternatively, you can load it explicitly only for scripts which need it -by adding this line to the start of each such PHP script:: +If the module is in PHP's default extension directory, you can omit the path. +</p> + +<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 +PHP script which uses your extension: </p> <div class="code"><pre> @@ -164,15 +169,26 @@ by adding this line to the start of each such PHP script:: </pre></div> <p> -SWIG also generates a php module, which -attempts to do the <tt>dl()</tt> call for you: +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 +described above. +</p> + +<p> +The PHP module which SWIG generates will also attempt to do the <tt>dl()</tt> +call for you if the extension isn't already loaded: </p> <div class="code"><pre> include("example.php"); </pre></div> -<H2><a name="Php_nn2"></a>33.2 Basic PHP interface</H2> +<p> +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"></a>34.2 Basic PHP interface</H2> <p> @@ -183,7 +199,7 @@ 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. </p> -<H3><a name="Php_nn2_1"></a>33.2.1 Constants</H3> +<H3><a name="Php_nn2_1"></a>34.2.1 Constants</H3> <p> @@ -220,9 +236,9 @@ 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 issue a warning and then expand the constant to a string -version of the constant's name. The warning will often be missed though as -if you're using PHP in a webserver, it will probably end up in error.log or +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. </p> @@ -260,7 +276,7 @@ is treated as true by the if test, when the value of the intended constant would be treated as false! </p> -<H3><a name="Php_nn2_2"></a>33.2.2 Global Variables</H3> +<H3><a name="Php_nn2_2"></a>34.2.2 Global Variables</H3> <p> @@ -309,7 +325,7 @@ undefined. At this time SWIG does not support custom accessor methods. </p> -<H3><a name="Php_nn2_3"></a>33.2.3 Functions</H3> +<H3><a name="Php_nn2_3"></a>34.2.3 Functions</H3> <p> @@ -362,7 +378,7 @@ print $s; # The value of $s was not changed. --> -<H3><a name="Php_nn2_4"></a>33.2.4 Overloading</H3> +<H3><a name="Php_nn2_4"></a>34.2.4 Overloading</H3> <p> @@ -418,7 +434,7 @@ taking the integer argument. </p> --> -<H3><a name="Php_nn2_5"></a>33.2.5 Pointers and References</H3> +<H3><a name="Php_nn2_5"></a>34.2.5 Pointers and References</H3> <p> @@ -563,7 +579,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"></a>33.2.6 Structures and C++ classes</H3> +<H3><a name="Php_nn2_6"></a>34.2.6 Structures and C++ classes</H3> <p> @@ -624,7 +640,7 @@ Would be used in the following way from PHP5: Member variables and methods are accessed using the <tt>-></tt> operator. </p> -<H4><a name="Php_nn2_6_1"></a>33.2.6.1 Using <tt>-noproxy</tt></H4> +<H4><a name="Php_nn2_6_1"></a>34.2.6.1 Using <tt>-noproxy</tt></H4> <p> @@ -650,7 +666,7 @@ Complex_im_set($obj,$d); Complex_im_get($obj); </pre></div> -<H4><a name="Php_nn2_6_2"></a>33.2.6.2 Constructors and Destructors</H4> +<H4><a name="Php_nn2_6_2"></a>34.2.6.2 Constructors and Destructors</H4> <p> @@ -691,7 +707,7 @@ the programmer can either reassign the variable or call <tt>unset($v)</tt> </p> -<H4><a name="Php_nn2_6_3"></a>33.2.6.3 Static Member Variables</H4> +<H4><a name="Php_nn2_6_3"></a>34.2.6.3 Static Member Variables</H4> <p> @@ -734,7 +750,7 @@ Ko::threats(10); echo "There have now been " . Ko::threats() . " threats\n"; </pre></div> -<H4><a name="Php_nn2_6_4"></a>33.2.6.4 Static Member Functions</H4> +<H4><a name="Php_nn2_6_4"></a>34.2.6.4 Static Member Functions</H4> <p> @@ -756,7 +772,25 @@ Ko::threats(); </pre></div> -<H3><a name="Php_nn2_7"></a>33.2.7 PHP Pragmas, Startup and Shutdown code</H3> +<H4><a name="Php_nn2_6_5"></a>34.2.6.5 Specifying Implemented Interfaces</H4> + + +<p> +PHP supports the concept of abstract interfaces which a class can implement. +Since SWIG 3.0.3, you can tell SWIG that a wrapped class (for example +<code>MyIterator</code>) implements the <code>Iterator</code> interface like +so: +</p> + +<div class="code"><pre> +%typemap("phpinterfaces") MyIterator "Iterator"; +</pre></div> + +<p> +If there are multiple interfaces, just list them separated by commas. +</p> + +<H3><a name="Php_nn2_7"></a>34.2.7 PHP Pragmas, Startup and Shutdown code</H3> <p> @@ -844,7 +878,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"></a>33.3 Cross language polymorphism</H2> +<H2><a name="Php_nn3"></a>34.3 Cross language polymorphism</H2> <p> @@ -879,7 +913,7 @@ wrapper functions takes care of all the cross-language method routing transparently. </p> -<H3><a name="Php_nn3_1"></a>33.3.1 Enabling directors</H3> +<H3><a name="Php_nn3_1"></a>34.3.1 Enabling directors</H3> <p> @@ -968,7 +1002,7 @@ class MyFoo extends Foo { </div> -<H3><a name="Php_nn3_2"></a>33.3.2 Director classes</H3> +<H3><a name="Php_nn3_2"></a>34.3.2 Director classes</H3> @@ -1048,7 +1082,7 @@ so there is no need for the extra overhead involved with routing the calls through PHP. </p> -<H3><a name="Php_nn3_3"></a>33.3.3 Ownership and object destruction</H3> +<H3><a name="Php_nn3_3"></a>34.3.3 Ownership and object destruction</H3> <p> @@ -1104,7 +1138,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"></a>33.3.4 Exception unrolling</H3> +<H3><a name="Php_nn3_4"></a>34.3.4 Exception unrolling</H3> <p> @@ -1163,7 +1197,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"></a>33.3.5 Overhead and code bloat</H3> +<H3><a name="Php_nn3_5"></a>34.3.5 Overhead and code bloat</H3> <p> @@ -1196,7 +1230,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"></a>33.3.6 Typemaps</H3> +<H3><a name="Php_nn3_6"></a>34.3.6 Typemaps</H3> <p> @@ -1210,7 +1244,7 @@ need to be supported. </p> -<H3><a name="Php_nn3_7"></a>33.3.7 Miscellaneous</H3> +<H3><a name="Php_nn3_7"></a>34.3.7 Miscellaneous</H3> <p> Director typemaps for STL classes are mostly in place, and hence you |