From 432cf5a03158a9db9b19460bb0e16a1347258cee Mon Sep 17 00:00:00 2001 From: Emiel Bruijntjes Date: Wed, 5 Mar 2014 14:34:04 +0100 Subject: added functions documentation --- documentation/loading-extensions.html | 143 ++-------------------------------- 1 file changed, 6 insertions(+), 137 deletions(-) (limited to 'documentation/loading-extensions.html') diff --git a/documentation/loading-extensions.html b/documentation/loading-extensions.html index fac26da..2fb723d 100644 --- a/documentation/loading-extensions.html +++ b/documentation/loading-extensions.html @@ -13,9 +13,9 @@ on your system, you can run the following command from the command line:

- 

-        php --ini
-
+
+php --ini
+

This will output a list of all configuration files that are loaded by PHP. @@ -33,9 +33,9 @@ extension directory, use the following command line instruction:

- 

-        php -i|grep extension_dir
-
+
+php -i|grep extension_dir
+

The extension dir often has the form /usr/lib/php5/20121212 - or a different @@ -150,134 +150,3 @@ extern "C" { native classes to PHP - it only creates the extension. That is going to be the next step.

- - - -

Exporting native functions

-

- An extension can of course only be useful if you define functions and/or - classes that can be accessed from PHP scripts. For functions you can do this - by adding your native function implementations to the Extension object: -

-

-


-    #include <phpcpp.h>
-    
-    extern void example1();
-    extern void example2(Php::Parameters &params);
-    extern Php::Value example3();
-    extern Php::Value example4(Php::Parameters &params);
-    
-    extern "C" {
-        PHPCPP_EXPORT void *get_module() {
-            static Php::Extension myExtension("my_extension", "1.0");
-            myExtension.add("native1", example1);
-            myExtension.add("native2", example2);
-            myExtension.add("native3", example3);
-            myExtension.add("native4", example4);
-            return myExtension.module();
-        }
-    }
-
-

-

- What do we see here? We've added four function declarations ("example1", - "example2", "example3" and "example4") to the source code of our extension. - The reason why we've only declared the functions, and not fully implemented - them is to keep the example code relatively small. We assume that the - four example functions are implemented in a different file. In a real world - example you could just as well remove the "extern" keyword and implement the - four functions in the same source file as the get_module() call. -

-

- The four functions all have a different signature: Some return a value, while - others do not return anything. And some take parameters, while others do not. - Despite the different signature of the functions, they can all be made - available in PHP by adding them to the extension object, by simply calling - the myExtension.add() method. This method takes two parameters: the name by - which the function should be accessible in PHP, and the actual native - function. -

-

- In the example above we've used different names for the native functions - ("example1" up to "example4") as for the PHP functions ("native1" to - "native4"). This is legal - you do not have to use the same names for your - native functions as for your PHP functions. The following PHP script can be - used to call the four native functions: -

-

- 

-        <?php
-        native1();
-        native2("a","b");
-        $x = native3();
-        $y = native4(1,2);
-        ?>
-
-

-

- It is not possible to export every thinkable C/C++ function to the - PHP extension. Only functions that have one of the four supported signatures - can be exported: functions that return - void or a Php::Value object, and that either accept a Php::Parameters object - or no parameters at all, can be added to the extension object and can thus - be exported to PHP. -

-

Parameter types

-

- PHP has a mechanism to enforce function parameters types, and to accept - parameters either by reference or by value. In the examples above, we have - not yet used that mechanism yes: it is up to the function implementations - themselves to inspect the 'Parameters' object, and check if the - variables are of the right type. -

-

- However, the 'Extension::add()' method takes a third optional parameter that - you can use to specify the number of parameters that are supported, whether - the parameters are passed by reference or by value, and what the type of - the parameters is: -

-

-


-#include <phpcpp.h>
-
-extern void example(Php::Parameters &params);
-
-extern "C" {
-    PHPCPP_EXPORT void *get_module() {
-        static Php::Extension myExtension("my_extension", "1.0");
-        myExtension.add("example", example, {
-            Php::ByVal("a", Php::Type::Numeric),
-            Php::ByVal("b", "ExampleClass"),
-            Php::ByRef("c", "OtherClass")
-        });
-        return myExtension.module();
-    }
-}
-
-

-

- Above you see that we passed in additional information when we registered the - "example" function. We tell our extension that our function accepts three parameters: - the first parameter must be a regular number, while the other ones are object - instances of type "ExampleClass" and "OtherClass". In the end, your native C++ - "example" function will still be called with a Php::Parameters instance, but - the moment it gets called, you can be sure that the Php::Parameters object - will be filled with three members, and that two of them are objects of the - appropriate type, and that the third one is also passed by reference. -

-

Working with variables

-

- Variables in PHP are non-typed. A variable can thus hold any possible type: - an integer, string, a floating point number, and even an object or an array. - C++ on the other hand is a typed language. In C++ an integer variable always - has a numeric value, and a string variable always hold a string value. -

-

- When you mix native code and PHP code, you will need to convert the non-typed - PHP variables into native variables, and the other way round: convert native - variables back into non-typed PHP variables. The PHP-CPP library offers the - "Value" class that makes this a very simple task. -

-

- \ No newline at end of file -- cgit v1.2.3