updated documentation about functions, introducted += operator with a Php::Value on the right side, and an integral variable on the left

1 files changed, 58 insertions, 0 deletions

diff --git a/documentation/parameters.html b/documentation/parameters.html
new file mode 100644
index 0000000..464d855
--- /dev/null
+++ b/documentation/parameters.html
@@ -0,0 +1,58 @@
+<h1>Limiting function parameters</h1>
+<p>
+    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.
+</p>
+<p>
+    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:
+</p>
+<p>
+<pre class="language-c++"><code>
+#include &lt;phpcpp.h&gt;
+
+extern void example(Php::Parameters &amp;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();
+    }
+}
+</pre></code>
+</p>
+<p>
+    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.
+</p>
+<h2>Working with variables</h2>
+<p>
+    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.
+</p>
+<p>
+    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.
+</p>
+<p>
+    
\ No newline at end of file