From fdffdbdfe573839178fe08b81522d18ad2d9468c Mon Sep 17 00:00:00 2001
From: Emiel Bruijntjes <emiel.bruijntjes@copernica.com>
Date: Thu, 6 Mar 2014 22:40:53 +0100
Subject: update documentation

---
 documentation/constructors-and-destructors.html |  4 +--
 documentation/variables.html                    | 45 ++++++++++++++++++++++++-
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/documentation/constructors-and-destructors.html b/documentation/constructors-and-destructors.html
index 8b9211f..7e1398c 100644
--- a/documentation/constructors-and-destructors.html
+++ b/documentation/constructors-and-destructors.html
@@ -16,9 +16,9 @@
 </p>
 <p>
     In PHP however, the __construct() method has a different behavior. When
-    it gets called, the object is already fully initialized and it is perfectly 
+    it gets called, the object is already initialized and it is perfectly 
     legal to make calls to even abstract methods that are implemented in derived 
-    classes. The following PHP script is completely legal - but it is impossible
+    classes. The following PHP script is completely valid - but it is impossible
     to do a similar thing in C++.
 </p>
 <p>
diff --git a/documentation/variables.html b/documentation/variables.html
index f46712d..f0ac126 100644
--- a/documentation/variables.html
+++ b/documentation/variables.html
@@ -11,9 +11,52 @@
     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>
+<p>
+    If you have ever spent time on writing PHP extensions in plain C, or if you've
+    ever read something about the internals of PHP, you must have heard about zval's.
+    A zval is a C structure in which PHP variables are stored. Internally, this zval
+    keeps a refcount, a union with the possible types and a number of other members
+    too. Every time that you access such a zval, make a copy of it, or write to
+    it, you must break your head to correctly update the refcount, and/or split the 
+    zval into different zvals, explicitly call copy constructors, allocate or 
+    free memory (using special memory allocation routines), or choose not to 
+    do this and leave the zval alone.
+</p>
+<p>
+    This all is crazy difficult and a big source for mistakes and all sorts of bugs.
+</p>
+<p>
+    And to make things even worse, there are literally hundreds of different 
+    undocumented macro's and functions in the Zend engine that can manipulate these 
+    zval variables. There are special macro's that work on zval's, macro's for 
+    pointers-to-zval's, macro's for pointer-to-pointer-to-zval's and even macro's 
+    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
+    is busy manipulating these zval structures. It is a big surprise that nobody
+    ever took the time to wrap such a zval into a simple C++ class that does all 
+    this administration for you. C++ is such a nice language with constructors, 
+    destructors, casting operators and operator overloading that can encapsulate all
+    this complicated zval handling.
+</p>
+<p>
+    And that is exactly what we did with PHP-CPP. We have introduced the Php::Value
+    object with a very simple interface, and the takes away all the problems of zval 
+    handling. Internally, the Php::Value object is a wrapper around a zval variable, 
+    and the completely hides the complexity of zval handling.
+</p>
+<p>
+    So, everything that you always wanted to ask about the internals of PHP, but
+    were afraid to ask: just forget about it. Sit back and relax, and take a look
+    how simple life is if you use PHP-CPP.
+</p>
 <h2>Scalar variables</h2>
 <p>
-    This section is not finished yet
+    The Php::Value object can be used to store scalar variables. Integers
+    
+    
 </p>
 
 
-- 
cgit v1.2.3