diff options
author | Emiel Bruijntjes <emiel.bruijntjes@copernica.com> | 2014-03-08 12:53:39 +0100 |
---|---|---|
committer | Emiel Bruijntjes <emiel.bruijntjes@copernica.com> | 2014-03-08 12:53:39 +0100 |
commit | 2e6efbd587e88be19b0c8f34d1597448125e23cf (patch) | |
tree | 026a8c94ddcd215de9be2be0541e54140770fd00 /documentation | |
parent | 5b93d44d2a05b3648ec13ae1f076e224d63287d5 (diff) |
fixed small typos in documentation, and added article about calling functions
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/bubblesort.html | 2 | ||||
-rw-r--r-- | documentation/calling-functions-and-methods.html | 140 | ||||
-rw-r--r-- | documentation/constructors-and-destructors.html | 4 | ||||
-rw-r--r-- | documentation/variables.html | 4 | ||||
-rw-r--r-- | documentation/your-first-extension.html | 2 |
5 files changed, 146 insertions, 6 deletions
diff --git a/documentation/bubblesort.html b/documentation/bubblesort.html index 2c94652..3125b6e 100644 --- a/documentation/bubblesort.html +++ b/documentation/bubblesort.html @@ -17,7 +17,7 @@ * * This function takes an unsorted array as input, sorts it, and returns * the output. It only uses normal PHP operations, and does not rely on - * any builtin PHP functions or on functions from extensions + * any built-in PHP functions or on functions from extensions * * @param array An unsorted array of integers * @return array A sorted array diff --git a/documentation/calling-functions-and-methods.html b/documentation/calling-functions-and-methods.html new file mode 100644 index 0000000..15e32f7 --- /dev/null +++ b/documentation/calling-functions-and-methods.html @@ -0,0 +1,140 @@ +<h1>Calling PHP functions</h1> +<p> + Let's get one thing clear first. Running native code is much faster than + running PHP code. So, once your C++ function or your C++ method finally + gets called, you normally cast the parameters to native variables, and + you start running your own fast algorithm. And you don't want to call + other PHP functions from that moment on. +</p> +<p> + If, however, you would like to make a call to a PHP function - whether that + is a function that is built-in in the Zend engine, that is defined in an + extension, or even a function that comes from PHP user space - you can do + so. +</p> +<p> +<pre class="language-c++"><code>#include <phpcpp.h> +#include <iostream> + +/** + * Native function that is callable from PHP + * + * This function gets two parameters: an associative array and a callback. + * It does not do anything meaningful, it is just a demonstration function. + * + * @param params The parameters passed to the function + */ +void example_function(Php::Parameters &params) +{ + // first parameter is an array + Php::Value array == params[0]; + + // call the PHP array_keys() function to get the parameter keys + std::vector<std::string> keys = Php::array_keys(array); + + // loop through the keys + for (auto &key : keys) + { + // output key + std::cout << "key: " << key << std::endl; + } + + // call a function from user space + Php::Value data = Php::call("some_method", "some_parameter"); + + // create an object (this will also call __construct()) + Php::Object time("DateTime", "now"); + + // call a method on the datetime object + std::cout << time.call("format", "Y-m-d H:i:s") << std::endl; + + // second parameter is a callback function + Php::Value callback = params[1]; + + // call the callback function + callback("some","parameter"); + + // in PHP it is possible to create an array with two parameters, the first + // parameter being an object, and the second parameter should be the name + // of the method, we can do that in PHP-CPP too + Php::Array time_format(time, "format"); + + // call the method that is stored in the array + std::cout << time_format("Y-m-d H:i:s") << std::endl; +} + +/** + * Switch to C context, because the Zend engine expects get get_module() + * to have a C style function signature + */ +extern "C" { + /** + * Startup function that is automatically called by the Zend engine + * when PHP starts, and that should return the extension details + * @return void* + */ + PHPCPP_EXPORT void *get_module() + { + // the extension object + static Php::Extension extension("my_extension", "1.0"); + + // add the example function so that it can be called from PHP scripts + extension.add("example_function", example_function); + + // return the extension details + return extension; + } +}</code></pre> +</p> +<p> + In above example you can see quite some different ways how to call PHP + functions from C++. The first one is the call to Php::array_keys(). The + PHP-CPP internally has a long list of all important PHP functions, and + you can call these functions directly from your extension. Php::array_keys() + is one of them. +</p> +<p> + Many of the built-in function functions (like Php::array_keys()) return a + Php::Value object. In the example however, you saw that we assigned the + return value directly to a std::vector. This works because the Php::Value + object has an implicit casting operator to automatically transform the + object to a vector. +</p> +<p> + Not every PHP function can of course be called like the built-in functions + can. User space functions, or functions from optional PHP extensions are not + automatically forwarded by the PHP-CPP library. Such functions can still be + called by using the Php::call() function. You must supply the name of the + fuinction to call, and a list of optional arguments to call a function + from user space. +</p> +<p> + The Php::Object class (which is derived from Php::Value) can be used to + create objects, and implicitly call the __construct() method. To call a + method on an object, you can use the method Php::Value::call() method, which + is used in the example to call the PHP method DateTime::format(). +</p> +<p> + In PHP scripts you can create an array with two members: and object and + the name of a method. This array then automatically becomes callable. You + can do similar things in C++ as well, as we showed in the example with the + "time_format" variable. +</p> +<p> + The following script runs the example. +</p> +<p> +<pre class="language-php"><code> +<?php + // example input + $input = array( + 'x' => 10, + 'y' => 20, + 'z' => 30 + ); + + example_function($input, function($param) { + echo("callback called with param $param\n"); + }); +?></code></pre> +</p> diff --git a/documentation/constructors-and-destructors.html b/documentation/constructors-and-destructors.html index 7e1398c..57f82c4 100644 --- a/documentation/constructors-and-destructors.html +++ b/documentation/constructors-and-destructors.html @@ -198,7 +198,7 @@ Php::Object counter1("Counter"); // the __construct() is being called with value 10 Php::Object counter2("Counter", 10); -// new builtin DateTime object, constructed with "now" +// new built-in DateTime object, constructed with "now" Php::Object time("DateTime", "now"); // valid, a Php::Object is an extended Php::Value, and @@ -212,7 +212,7 @@ Php::Object copy2 = counter0; <p> The constructor of a Php::Object takes the name of a class, and an optional list of parameters that will be passed to the __construct() function. You - can use names from builtin PHP classes and other extensions (like DateTime), + can use names from built-in PHP classes and other extensions (like DateTime), classes from your extension (like Counter), and even classes from PHP user space. </p> diff --git a/documentation/variables.html b/documentation/variables.html index e2515d4..2985ce5 100644 --- a/documentation/variables.html +++ b/documentation/variables.html @@ -35,7 +35,7 @@ that deal with pointer-to-pointer-to-pointer-to-zval's. </p> <p> - Every single PHP module, every PHP extension, and every builtin PHP function + Every single PHP module, every PHP extension, and every built-in PHP function is busy manipulating these zval structures. It is a big surprise that nobody ever took the time to wrap such a zval in a simple C++ class that does all this administration for you. C++ is such a nice language with constructors, @@ -254,7 +254,7 @@ std::cout << value.call("format", "Y-m-d H:i:s") << std::endl; // create a string with a function name Php::Value date = "date"; -// "date" is a builtin PHP function and thus can it be called +// "date" is a built-in PHP function and thus can it be called std::cout << date("Y-m-d H:i:s") << std::endl; // create a date-time object diff --git a/documentation/your-first-extension.html b/documentation/your-first-extension.html index bb262a3..9663409 100644 --- a/documentation/your-first-extension.html +++ b/documentation/your-first-extension.html @@ -134,7 +134,7 @@ MKDIR = mkdir -p # # All source files are simply all *.cpp files found in the current directory # -# A builtin Makefile macro is used to scan the current directory and find +# A built-in Makefile macro is used to scan the current directory and find # all source files. The object files are all compiled versions of the source # file, with the .cpp extension being replaced by .o. # |