From dd8a17b8e6696566eb1d2be453a4c21cf8e41b66 Mon Sep 17 00:00:00 2001
From: Emiel Bruijntjes <emiel.bruijntjes@copernica.com>
Date: Wed, 19 Mar 2014 09:53:34 +0100
Subject: added documentation about defining interfaces, this is an answer to
 question #45

---
 documentation/classes-and-objects.html | 71 ++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 4 deletions(-)

diff --git a/documentation/classes-and-objects.html b/documentation/classes-and-objects.html
index 6e565ab..78a3292 100644
--- a/documentation/classes-and-objects.html
+++ b/documentation/classes-and-objects.html
@@ -516,9 +516,11 @@ extern "C" {
 </code></pre>
 </p>
 <p>
-    It may seem strange that you have to pass in the address of a real C++ method
-    when you register an abstract method. Abstract methods do normally not 
-    have an implementation, so what do you need this C++ implementation for?
+    Like we explained before, when you want to register an abstract method, you 
+    should pass in a Php::Abstract flag to the call to Php::Class::method(). 
+    However, it may seem strange that this method also requires that you pass 
+    in the address of a real C++ method. Abstract methods do normally not have 
+    an implementation, so what do you need to supply a pointer to a method?
     Luckily, there also is a different way for registering abstract methods.
 </p>
 <p>
@@ -541,11 +543,20 @@ extern "C" {
         Php::Class&lt;Counter&gt; counter("Counter");
         
         // register an abstract method
-        counter.method("myAbstractMethod", { Php::ByVal("value", Php::Type::String, true) });
+        // no need to pass in a pointer to the method or to pass in a flag: 
+        // thet method automatically becomes abstract if no address of a C++
+        // method is supplied
+        counter.method("myAbstractMethod", { 
+            Php::ByVal("value", Php::Type::String, true) 
+        });
         
         // register other methods
         ...
         
+        // add the counter to the extension
+        // (or move it into the extension, which is faster)
+        myExtension.add(std::move(counter));
+        
         // return the extension
         return myExtension;
     }
@@ -556,6 +567,58 @@ extern "C" {
     To register abstract methods, you can simply use an alternative form of the 
     Counter::method() method that does not take a pointer to a C++ method.
 </p>
+<h2 id="interfaces">Interfaces</h2>
+<p>
+    In C++ interfaces do not exist. C++ supports multiple inheritance, which is
+    more powerful than interfaces or traits. Interfaces and traits are basically
+    PHP workarounds to make up for not having multiple inheritance. So when 
+    you're writing C++ code, you don't need interfaces or traits.
+</p>
+<p>
+    In case you want your extension to <i>define</i> an interface, so that the
+    interface can be implemented from PHP user space scripts, you can do that
+    almost similar to how you would define an abstract class. The only difference
+    is that you will not use a Php::Class instance to define the methods, but
+    a Php::Interface instance.
+</p>
+<p>
+<pre class="language-c++"><code>
+/**
+ *  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 interface so that PHP knows which methods 
+        // are defined by it
+        Php::Interface interface("MyInterface");
+        
+        // define an interface method
+        interface.method("myMethod", { 
+            Php::ByVal("value", Php::Type::String, true) 
+        });
+        
+        // register other methods
+        ...
+
+        // add the interface to the extension
+        // (or move it into the extension, which is faster)
+        myExtension.add(std::move(interface));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+</code></pre>
+</p>
 <p>
     There is much more to say about classes and objects, in the next section
     we'll explain <a href="constructors-and-destructors">constructors and 
-- 
cgit v1.2.3