added id to all h2 tags to make it possible to link to specific sections, update documentation about serializable, fixed compile error for serialize implementation

12 files changed, 161 insertions, 32 deletions

diff --git a/documentation/bubblesort.html b/documentation/bubblesort.html
index 2c08888..ad347d5 100644
--- a/documentation/bubblesort.html
+++ b/documentation/bubblesort.html
@@ -137,7 +137,7 @@ extern "C" {
     Zend engine about the extension, so that the "native_bubblesort" function is 
     accessible for PHP scripts.
 </p>
-<h2>We start with a silly question</h2>
+<h2 id="silly-question">We start with a silly question</h2>
 <p>
     How would the native bubblesort function compare to the built-in sort()
     function of PHP? This is a silly question. Bubblesort is an extremely 
@@ -192,7 +192,7 @@ Native:   0.79793095588684 seconds
 Scripted: 8.9202060699463 seconds
 </pre>
 </p>
-<h2>Summary</h2>
+<h2 id="summary">Summary</h2>
 <p>
     C++ is faster - much faster - than code in PHP, even for very simple scripts.
     The source code for an extension written in C++ is almost identical to the
diff --git a/documentation/classes-and-objects.html b/documentation/classes-and-objects.html
index 5b7c063..32ca15c 100644
--- a/documentation/classes-and-objects.html
+++ b/documentation/classes-and-objects.html
@@ -69,7 +69,6 @@ extern "C" {
         counter.method("increment", &Counter::increment);
         counter.method("decrement", &Counter::decrement);
         counter.method("value", &Counter::value);
-        counter.method("instantiate", &Counter::instantiate);
         
         // add the class to the extension
         myExtension.add(std::move(counter));
@@ -131,7 +130,7 @@ Php::Value  YourClass::example8(Php::Parameters &amp;params) const;
     to add the class to the extension? This will actually <i>move</i> the class
     object into the extension, which is a more efficient operation than copying.
 </p>
-<h2>Method parameters</h2>
+<h2 id="method-parameters">Method parameters</h2>
 <p>
     Methods are just like functions, and just how you use the
     Php::ByVal and the Php::ByRef classes to <a href="parameters">specify the 
@@ -260,7 +259,7 @@ echo($counter->value()."\n");
     thought that an example was not really necessary (and we're not a big fan
     of parameters-by-reference either).
 </p>
-<h2>Static methods</h2>
+<h2 id="static-methods">Static methods</h2>
 <p>
     Static methods are supported too. A static method is a method that does
     not have access to a 'this' pointer. In C++, such static methods
@@ -417,7 +416,7 @@ myFunction();
 ?&gt;
 </code></pre>
 </p>
-<h2>Access modifiers</h2>
+<h2 id="access-modifiers">Access modifiers</h2>
 <p>
     In PHP (and in C++ too) you can mark methods as public, private or protected.
     To achieve this for your native class too, you should pass in an additional 
@@ -481,7 +480,7 @@ extern "C" {
     because after all, your methods are called by the PHP-CPP library, and if you make
     them private, they becomes invisible for the library.
 </p>
-<h2>Abstract and final</h2>
+<h2 id="abstract-and-final">Abstract and final</h2>
 <p>
     In the previous section we showed how to use the Php::Final and Php::Abstract
     flags to create a final or abstract method. If you want to make your entire
diff --git a/documentation/constructors-and-destructors.html b/documentation/constructors-and-destructors.html
index d66e8a4..110ed60 100644
--- a/documentation/constructors-and-destructors.html
+++ b/documentation/constructors-and-destructors.html
@@ -138,7 +138,7 @@ echo($counter->value()."\n");
 ?&gt;
 </code></pre>
 </p>
-<h2>Private constructors</h2>
+<h2 id="private-constructors">Private constructors</h2>
 <p>
     Just like any other method, the __construct() method can also be
     marked as being private or protected. If you do this, you will make it
@@ -176,7 +176,7 @@ extern "C" {
     needs a copy constructor, which is called when a "clone $object" instruction
     is given in a PHP script.
 </p>
-<h2>Constructing objects</h2>
+<h2 id="constructing-objects">Constructing objects</h2>
 <p>
     The Php::Value class can be used as a regular PHP $variable, and you can therefore
     also use it for storing object instances. But how do you create brand
diff --git a/documentation/exceptions.html b/documentation/exceptions.html
index fb4ec52..c4f0e5c 100644
--- a/documentation/exceptions.html
+++ b/documentation/exceptions.html
@@ -78,7 +78,7 @@ exception caught
     is as if you're not even working in two different languages, and you can 
     simply throw a Php::Exception object as if it was a regular PHP exception.
 </p>
-<h2>Catching exceptions in C++</h2>
+<h2 id="catching-exceptions">Catching exceptions in C++</h2>
 <p>
     And this works the other way around too. If your extension calls a PHP 
     function, and that PHP function happens to throw an exception, you can catch it
diff --git a/documentation/install.html b/documentation/install.html
index 80afa03..7f7a2c3 100644
--- a/documentation/install.html
+++ b/documentation/install.html
@@ -16,7 +16,7 @@
 </p>
 
 
-<h2>Limitations</h2>
+<h2 id="limitations">Limitations</h2>
 <p>
     At this moment, PHP-CPP only supports single-threaded PHP installations.
     Web servers come in a number forms: there are the ones that handle each
@@ -49,7 +49,7 @@
 
 
 
-<h2>Download</h2>
+<h2 id="download">Download</h2>
 <p>
     Installation begins with downloading the source code. You can either
     download the latest release from our
diff --git a/documentation/loading-extensions.html b/documentation/loading-extensions.html
index 00524de..3cc7059 100644
--- a/documentation/loading-extensions.html
+++ b/documentation/loading-extensions.html
@@ -7,7 +7,7 @@
     create such a *.so or *.dll file and you have to update the PHP 
     configuration file so that your own extension is loaded by PHP.
 </p>
-<h2>The get_module() startup function</h2>
+<h2 id="get-module-startup-function">The get_module() startup function</h2>
 <p>
     Before we explain how you can create your own extension, we first explain
     what PHP does to load an extension. When PHP starts, it loads the *.ini 
diff --git a/documentation/magic-interfaces.html b/documentation/magic-interfaces.html
index d793856..0497ce2 100644
--- a/documentation/magic-interfaces.html
+++ b/documentation/magic-interfaces.html
@@ -24,7 +24,7 @@
     does not have interfaces like PHP has, classes with pure virtual methods are
     used instead.
 </p>
-<h2>Support for the SPL</h2>
+<h2 id="support-for-spl">Support for the SPL</h2>
 <p>
     A standard PHP installation comes with the Standard PHP Library (SPL). This
     is an extension that is built on top of the Zend engine and that uses features
@@ -43,7 +43,7 @@
     offer the same sort of features, but they do not rely on each other. You can 
     thus safely use PHP-CPP if you have not loaded the SPL extension.
 </p>
-<h2>The Countable interface</h2>
+<h2 id="countable">The Countable interface</h2>
 <p>
     By implementing the Php::Countable interface, you can create objects that
     can be passed to the PHP count() function.
@@ -149,7 +149,7 @@ echo(count($counter)."\n");
 <p>
     The output is, as expected, the value 3.
 </p>
-<h2>The ArrayAccess interface</h2>
+<h2 id="arrayaccess">The ArrayAccess interface</h2>
 <p>
     A PHP object can be turned into a variable that behaves like an array by
     implementing the Php::ArrayAccess interface. When you do this, objects
@@ -309,7 +309,7 @@ echo($map->offsetGet("a")."\n");
     The output speaks for itself. The map has three members, "1234" (a string
     variable), "xyz" and "0".
 </p>
-<h2>The Traversable interface</h2>
+<h2 id="traversable">The Traversable interface</h2>
 <p>
     Classes can also be used in foreach loops, just like regular arrays. If you
     want to enable this feature, your class should extend from the Php::Traverable 
@@ -582,3 +582,133 @@ extern "C" {
     a C++ iterator class. It is of course up to you to create more complex
     iterators when needed.
 </p>
+<h2 id="serializable">The Serializable interface</h2>
+<p>
+    By implementing the interface "Php::Serializable" you can create custom
+    serialize and unserialize handlers for a class. The built-in PHP 
+    serialize() function - you probably already know - is a function that
+    can turn a complex data structure full of arrays and objects into a simple 
+    string. The unserialize() method does exactly the opposite, and turns such
+    a string back into a complex data structure.
+</p>
+<p>
+    The default serializer turns all publicly visible object properties into a
+    string. But because your class has a native implementation, you may want to 
+    install a custom serialize method that also stores the native variables. To 
+    do this, you can implement the Php::Serialize interface, and implement the 
+    serialize() and unserialize() methods.
+</p>
+<p>
+<pre class="language-c++"><code>
+#include &lt;phpcpp.h&gt;
+
+/**
+ *  Counter class that can be used for counting
+ */
+class Counter : public Php::Base, public Php::Serializable
+{
+private:
+    /**
+     *  The initial value
+     *  @var    int
+     */
+    int _value = 0;
+
+public:
+    /**
+     *  C++ constructor and destructor
+     */
+    Counter() {}
+    virtual ~Counter() {}
+    
+    /**
+     *  Update methods to increment or decrement the counter
+     *  Both methods return the NEW value of the counter
+     *  @return int
+     */
+    Php::Value increment() { return ++_value; }
+    Php::Value decrement() { return --_value; }
+    
+    /**
+     *  Method to retrieve the current counter value
+     *  @return int
+     */
+    Php::Value value() const { return _value; }
+    
+    /**
+     *  Serialize the object into a string
+     *  @return std::string
+     */
+    virtual std::string serialize() override
+    {
+        return std::to_string(_value);
+    }
+    
+    /**
+     *  Unserialize the object from a string
+     *  @param  buffer
+     *  @param  size
+     */
+    virtual void unserialize(const char *buffer, size_t size) override
+    {
+        _value = ::atoi(buffer);
+    }
+};
+
+/**
+ *  Switch to C context to ensure that the get_module() function
+ *  is callable by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function that is called by the Zend engine 
+     *  to retrieve all information about the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        // create static instance of the extension object
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // description of the class so that PHP knows which methods are accessible
+        Php::Class&lt;Counter&gt; counter("Counter");
+        counter.method("increment", &Counter::increment);
+        counter.method("decrement", &Counter::decrement);
+        counter.method("value", &Counter::value);
+        
+        // add the class to the extension
+        myExtension.add(std::move(counter));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+</code></pre>
+</p>
+<p>
+    The above example takes the Counter example that you've seen before, and 
+    turns it into a Serializable object. A counter can now be stored in a string
+    (and thus in a database, or on disk) and later be revived using the
+    PHP serialize() and unserialize() functions.
+</p>
+<p>
+<pre class="language-php"><code>
+&lt;?php
+// create an empty counter and increment it a few times
+$counter = new Counter();
+$counter->increment();
+$counter->increment();
+
+// turn the counter into a storable string
+$serializedCounter = serialize($counter);
+
+// revive the counter back into an object
+$revivedCounter = unserialize($serializedCounter);
+
+// show the counter value
+echo($revivedCounter->value()."\n");
+?&gt;
+</code></pre>
+</p>
+<p>
+    Does anyone know what the output is? It's 2.    
+</p>
diff --git a/documentation/magic-methods.html b/documentation/magic-methods.html
index 0e7b61f..ed7dd3b 100644
--- a/documentation/magic-methods.html
+++ b/documentation/magic-methods.html
@@ -17,7 +17,7 @@
     can not be called explicitly from PHP scripts - but they do get called
     when a property is accessed.
 </p>
-<h2>Pseudo properties</h2>
+<h2 id="pseudo-properties">Pseudo properties</h2>
 <p>
     With the methods __get(), __set(), __unset() and __isset() you can define 
     pseudo properties. It allows you to, for example, create read-only properties,
@@ -192,7 +192,7 @@ unset($user->email);
 ?&gt;
 </code></pre>
 </p>
-<h2>Magic methods __call() and __invoke()</h2>
+<h2 id="call-and-invoke">Magic methods __call() and __invoke()</h2>
 <p>
     C++ methods need to be registered explicitly in your extension get_module() 
     startup function to be accessible from PHP user space. However, when you override the __call() 
@@ -344,7 +344,7 @@ whatever a b
 invoke parameter passed to invoke
 </pre>
 </p>
-<h2>Casting methods (__toString and more)</h2>
+<h2 id="casting">Casting methods (__toString and more)</h2>
 <p>
     In PHP you can add a __toString() method to a class. This method is automatically
     called when an object is casted to a string, or when an object is used in a string
diff --git a/documentation/parameters.html b/documentation/parameters.html
index 94c0352..0051f51 100644
--- a/documentation/parameters.html
+++ b/documentation/parameters.html
@@ -42,7 +42,7 @@ extern "C" {
     will be filled with three members, and that two of them are objects of the 
     appropriate type.
 </p>
-<h2>Can you really enforce scalar parameters?</h2>
+<h2 id="enforce-scalar-parameters">Can you really enforce scalar parameters?</h2>
 <p>
     You may be surprised to see that we specified the first parameter to be of
     type Numeric. After all, in PHP there is no offical way to enforce the type of a 
@@ -114,7 +114,7 @@ example("x", "y", "z");
     The PHP engine will trigger an error if your function is called with wrong
     parameters, and will not make the actual call to the native function.
 </p>
-<h2>The Php::ByVal class further explained</h2>
+<h2 id="byval-explained">The Php::ByVal class further explained</h2>
 <p>
     The Php::ByVal class that we showed can be constructed in two ways.
     Let's look at the first constructor from the C++ header file:
@@ -221,7 +221,7 @@ extern "C" {
 }
 </pre></code>
 </p>
-<h2>Parameters by reference</h2>
+<h2 id="parameters-by-reference">Parameters by reference</h2>
 <p>
     By the name of the Php::ByVal class you may have concluded that there
     must also be a Php::ByRef class - and you could not have been more right than that. 
@@ -278,7 +278,7 @@ swap(10,20);
 ?&gt;
 </code></pre>
 </p>
-<h2>Summary</h2>
+<h2 id="summary">Summary</h2>
 <p>
     When you add your native functions to the extension object, you may supply
     an optional third parameter with a list of Php::ByVal and Php::ByRef objects
diff --git a/documentation/variables.html b/documentation/variables.html
index 9476b70..6b63598 100644
--- a/documentation/variables.html
+++ b/documentation/variables.html
@@ -11,7 +11,7 @@
     variables back into non-typed PHP variables. The PHP-CPP library offers the 
     Php::Value class that makes this a very simple task.
 </p>
-<h2>Zval's</h2>
+<h2 id="zvals">Zval's</h2>
 <p>
     But we start with sharing one of our frustrations. 
     If you have ever spent time on writing PHP extensions in plain C, or if you've
@@ -53,7 +53,7 @@
     were afraid to ask: just forget about it. Sit back and relax, and take a look
     how simple life is with PHP-CPP.
 </p>
-<h2>Scalar variables</h2>
+<h2 id="scalar-variables">Scalar variables</h2>
 <p>
     The Php::Value object can be used to store scalar variables. Scalar variables
     are variables like integers, doubles, strings, booleans and null values.
@@ -141,7 +141,7 @@ Php::Value myFunction(const Php::Value &amp;value)
     can become complicated, but for you, the extension programmer, there is
     nothing to worry about.
 </p>
-<h2>Arrays</h2>
+<h2 id="arrays">Arrays</h2>
 <p>
     PHP supports two array types: regular arrays (indexed by numbers) and
     associative arrays (indexed by strings). The Php::Value object supports
@@ -222,7 +222,7 @@ array1 = 100;
 <p>
     @todo explain how to iterate over arrays
 </p>
-<h2>Objects</h2>
+<h2 id="objects">Objects</h2>
 <p>
     Just like the Php::Array class that is an extended Php::Value that initializes
     to an empty array, there also is a Php::Object class that becomes an
@@ -255,7 +255,7 @@ std::cout &lt;&lt; object.call("format", "Y-m-d H:i:s") &lt;&lt; std::endl;
 Php::Value value = Php::Object("DateTime", "now");
 std::cout &lt;&lt; value.call("format", "Y-m-d H:i:s") &lt;&lt; std::endl;
 </code></pre>
-<h2>Functions</h2>
+<h2 id="functions">Functions</h2>
 <p>
     When a Php::Value object holds a <i>callable</i>, you can use the () operator
     to call this function or method.
@@ -283,7 +283,7 @@ array[1] = "format";
 std::cout &lt;&lt; array("Y-m-d H:i:s") &lt;&lt; std::endl;
 </code></pre>
 </p>
-<h2>Global variables</h2>
+<h2 id="global-variables">Global variables</h2>
 <p>
     To read or update global PHP variables, you can use the Php::GLOBALS 
     variable. This variable works more or less the same as the $_GLOBALS
diff --git a/documentation/your-first-extension.html b/documentation/your-first-extension.html
index 9663409..2e5914e 100644
--- a/documentation/your-first-extension.html
+++ b/documentation/your-first-extension.html
@@ -18,7 +18,7 @@
         <li><a href="http://www.php-cpp.com/EmptyExtension.tar.gz">EmptyExtension.tar.gz</a></li>
     </ul>
 </p>
-<h2>Makefile</h2>
+<h2 id="makefile">Makefile</h2>
 <p>
     The EmptyExtension file contains a Makefile with instructions for the compiler.
     You will have to make some (small) changes to this Makefile to make it compatible
diff --git a/src/classbase.cpp b/src/classbase.cpp
index e922855..ac3a0f1 100644
--- a/src/classbase.cpp
+++ b/src/classbase.cpp
@@ -1046,7 +1046,7 @@ int ClassBase::unserialize(zval **object, zend_class_entry *entry, const unsigne
     Serializable *serializable = dynamic_cast<Serializable*>(cpp_object(*object));
     
     // call the unserialize method on it
-    serializable->unserialize(buffer, buf_len);
+    serializable->unserialize((const char *)buffer, buf_len);
     
     // done
     return SUCCESS;