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

[php] Generate PHP type declarations

Browse source 
We now automatically generate PHP type declarations for PHP >= 8.0.

The generated code still compiles with PHP 7.x but without type declarations.
This commit is contained in:
Olly Betts 2022-01-20 10:07:44 +13:00 • committed by GitHub
commit 1f1349741f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 536 additions and 196 deletions
Download patch file Download diff file Expand all files Collapse all files

73
Doc/Manual/Php.html
View file

@ -346,6 +346,79 @@ $c = bar(3.5); # Use default argument for 2nd parameter
</pre></div>
<p>
SWIG generates PHP type declarations for function parameters and return
types for PHP 8 and later (we don't try to support PHP 7's more limited type
declarations and the generated wrappers compiled for PHP 7 will not have any
type declarations).
</p>
<p>
You can control the generation of PHP type declarations using
the "php:type" %feature. This has three settings:
</p>
<ul>
<li> <p>If unset or set to "0" then no type declarations are generated, e.g.: <tt>%feature("php:type", "0");</tt>
</p></li>
<li> <p>If set to "1" then type declarations are generated for both parameters and return types, e.g.: <tt>%feature("php:type", "1");</tt>
</p></li>
<li> <p>The default setting is "compat", which is the same as "1" except no
return type declarations are generated for virtual methods for which
directors are enabled. This provides better compatibility for PHP
subclasses of wrapped virtual methods in existing SWIG-generated bindings, e.g.: <tt>%feature("php:type", "compat");</tt>
</p></li>
</ul>
<p>
If you have an existing PHP interface and are upgrading to SWIG &gt;= 4.1.0
then the default "compat" setting should work well.
</p>
<p>
If you're writing a new set of bindings and <b>only targetting PHP8 or newer</b>
then enabling type declarations everywhere probably makes sense. It will
only actually make a difference if you enable directors and are wrapping C++
classes with virtual methods, but doing it anyway means you won't forget to if
the code you are wrapping later evolves to have such classes and methods.
</p>
<p>
The type declaration information will make the generated source code and
compiler extension module larger, so you might want to turn off type
declarations if keeping these small is important to you. If you find you
need to turn off type declarations to fix a problem, please let us know
via our github issue tracker.
</p>
<p>
Note that being a SWIG feature this can be specified globally (like above) or
per class, per method, etc. See the <a
href="Customization.html#Customization_features">%feature directives</a>
section for full details of how to control at a fine-grained level.
</p>
<p>
The PHP type information is specified via a "phptype" attribute on "in" and
"out" typemaps, and these have been added for all the typemaps we supply for
PHP. We don't currently support this for "argout" templates, but probably
will in a future version.
</p>
<p>
If you have written custom SWIG typemaps for PHP and want to add PHP type
declarations, then the syntax is very like how you'd specify the type in
PHP code, e.g. <tt>%typemap(in, phptype="int|string|Foo")</tt> means the
typemap accepts a PHP int or string or an object of class Foo,
<tt>%typemap(in, phptype="?int")</tt> means a PHP int or NULL, etc.
As well as the standard PHP type declaration types, SWIG also understands the
special type "SWIGTYPE" as an entry in phptype, which means the PHP type
corresponding to the type that this typemap matched on - for a object this
will give you the PHP class for the object, and for a pointer to a non-class
type it will give you the name of the PHP class SWIG created for that
pointer type.
</p>
<!-- This isn't correct for 1.3.30 and needs rewriting to reflect reality
<p>
Because PHP is a dynamically typed language, the default typemaps