added documentation about class constants

2 files changed, 172 insertions, 1 deletions

diff --git a/documentation/constants.html b/documentation/constants.html
new file mode 100644
index 0000000..cd51224
--- /dev/null
+++ b/documentation/constants.html
@@ -0,0 +1,165 @@
+<h1>Constants</h1>
+<p>
+    In PHP scripts you can define constants - both global constants and
+    class level constants. This can also be done with PHP-CPP. If you want
+    to expose constants to user space PHP code, you can do that by adding
+    the constants to the Php::Extension object inside the get_module()
+    call.
+</p>
+<p>
+<pre class="language-c++"><code>
+#include &lt;phpcpp.h&gt;
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // add integer constants
+        myExtension.add(Php::Constant("MY_CONSTANT_1", 1));
+        myExtension.add(Php::Constant("MY_CONSTANT_2", 2));
+        
+        // floating point constants
+        myExtension.add(Php::Constant("MY_CONSTANT_3", 3.1415927));
+        myExtension.add(Php::Constant("MY_CONSTANT_4", 4.932843));
+        
+        // string constants
+        myExtension.add(Php::Constant("MY_CONSTANT_5", "This is a constant value"));
+        myExtension.add(Php::Constant("MY_CONSTANT_6", "Another constant value"));
+        
+        // null constants
+        myExtension.add(Php::Constant("MY_CONSTANT_7", nullptr));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+</code></pre>
+</p>
+<p>
+    It is all very straight forward. Using the constants in a PHP script is
+    just as easy:
+</p>
+<p>
+<pre class="language-php"><code>
+&lt;?php
+echo(MY_CONSTANT_1."\n");
+echo(MY_CONSTANT_2."\n");
+echo(MY_CONSTANT_3."\n");
+echo(MY_CONSTANT_4."\n");
+echo(MY_CONSTANT_5."\n");
+echo(MY_CONSTANT_6."\n");
+echo(MY_CONSTANT_7."\n");
+?&gt;
+</code></pre>
+</p>
+<p>
+    PHP also supports the concept of class level constants. Internally, in
+    the Zend engine, class level constants are implemented as regular class
+    members, but instead of a "public" or "private" flag, a constant property
+    is marked with a "constant" flag. PHP-CPP exposes this too. You can 
+    register class properties with a Php::Const flag.
+</p>
+<p>
+    Besides this, a Php::Class instance also has a "constant" method, and
+    you can add instances of Php::Constant to the class. Semantically, all
+    these three ways to create class level constants are identical.
+</p>
+<p>
+<pre class="language-c++"><code>
+/**
+ *  The C++ class that we're going to expose
+ *
+ *  (For this example we use a completely empty class, as only examples
+ *  are given on how to use constants)
+ */
+class Dummy : public Php::Base
+{
+};
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // create a class objects
+        Php::Class&lt;Dummy&gt; dummy("Dummy");
+        
+        // there are many different ways to add constants, but semantically,
+        // they're all the same
+        dummy.property("MY_CONSTANT_1", 1, Php::Const);
+        dummy.property("MY_CONSTANT_2", "abcd", Php::Const);
+        dummy.constant("MY_CONSTANT_3", "xyz");
+        dummy.constant("MY_CONSTANT_4", 3.1415);
+        dummy.add(Php::Constant("MY_CONSTANT_5", "constant string"));
+        dummy.add(Php::Constant("MY_CONSTANT_5", true));
+        
+        // add the class to the extension
+        myExtension.add(std::move(dummy));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+</code></pre>
+</p>
+<h2>Runtime constants</h2>
+<p>
+    If you want to find out the value of a user space constant at runtime
+    from your C++ code, or when you want to find out if a constant is
+    defined or not, you can simply use the Php::constant() or Php::defined()
+    functions. To define constants at runtime, use Php::define():
+</p>
+<p>
+<pre class="language-c++"><code>
+/**
+ *  Function that can be called from a PHP script
+ */
+void example_function()
+{
+    // check if a certain user space constant is defined
+    if (Php::defined("USER_SPACE_CONSTANT"))
+    {
+        // retrieve the value of a constant
+        Php::Value constant = Php::constant("ANOTHER_CONSTANT");
+        
+        // define other constants at runtime
+        Php::define("DYNAMIC_CONSTANT", 12345);
+    }
+}
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // add a function to the extension
+        extension.add("example_function", example_function);
+        
+        // return the extension
+        return myExtension;
+    }
+}
+</code></pre>
+</p>
diff --git a/documentation/properties.html b/documentation/properties.html
index 6f3ece5..db7c44f 100644
--- a/documentation/properties.html
+++ b/documentation/properties.html
@@ -194,7 +194,13 @@ extern "C" {
 </p>
 <p>
     The class constant can be accessed from PHP scripts using Example::MY_CONSTANT,
-    and the static properties with Example::$my_property.
+    and the static properties with Example::$my_property. 
+</p>
+<p>
+    Besides using the property() method, you can also
+    create class constants using the constant() method, or using the
+    Php::Constant class. More information about this can be found in our 
+    <a href="constants">article about constants</a>.
 </p>
 <h2>Smart properties</h2>
 <p>