From 62402594bfd5ecb057b2cc2ab4dc02cf60e4ab48 Mon Sep 17 00:00:00 2001 From: Emiel Bruijntjes Date: Wed, 12 Mar 2014 16:36:00 +0100 Subject: mentioned static methods in documentation --- documentation/classes-and-objects.html | 278 ++++++++++++++++++++++++++++++--- 1 file changed, 256 insertions(+), 22 deletions(-) diff --git a/documentation/classes-and-objects.html b/documentation/classes-and-objects.html index 008a9e5..6e62809 100644 --- a/documentation/classes-and-objects.html +++ b/documentation/classes-and-objects.html @@ -16,23 +16,52 @@ 

 #include <phpcpp.h>
 
-// actual class implementation
+/**
+ *  Counter class that can be used for counting
+ */
 class Counter : public Php::Base
 {
 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; }
 };
 
+/**
+ *  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
@@ -40,6 +69,7 @@ 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));
@@ -63,28 +93,29 @@ extern "C" {
     of the counter after the operation, the value() method returns the current value.
 

 

-    If you want to make a class method that is accessible from PHP, you must
-    ensure that it has one of the eight supported signatures (which are the same
-    signatures that exportable plain functions can have),
-    plus their const variant.
+    If you want to make a class method accessible from PHP, you must
+    ensure that it matches one of the supported signatures. These are essentially
+    the same signatures as exportable plain functions,
+    can have, but with versions for const and non-const methods, and signatures
+    for static methods.
 

 

 

-void YourClass::example1();
-void YourClass::example2(Php::Parameters &params);
-Php::Value YourClass::example3();
-Php::Value YourClass::example4(Php::Parameters &params);
-void YourClass::example5() const;
-void YourClass::example6(Php::Parameters &params) const;
-Php::Value YourClass::example7() const;
-Php::Value YourClass::example8(Php::Parameters &params) const;
+// signatures of supported regular methods
+void        YourClass::example1();
+void        YourClass::example2(Php::Parameters &params);
+Php::Value  YourClass::example3();
+Php::Value  YourClass::example4(Php::Parameters &params);
+void        YourClass::example5() const;
+void        YourClass::example6(Php::Parameters &params) const;
+Php::Value  YourClass::example7() const;
+Php::Value  YourClass::example8(Php::Parameters &params) const;
 

 

 

     Methods work exactly the same as regular functions, with the 
     difference that in a method you have (of course) access to the member
-    variables of the object (and in C++ you you do not have to use "this->"
-    to access member variables).
+    variables of the object.
 

 

     To make the class accessible from PHP, you must add it to the extension
@@ -111,51 +142,86 @@ Php::Value YourClass::example8(Php::Parameters &params) const;
 

 #include <phpcpp.h>
 
-// actual class implementation
+/**
+ *  Counter class that can be used for counting
+ */
 class Counter : public Php::Base
 {
 private:
+    /**
+     *  The initial value
+     *  @var    int
+     */
     int _value = 0;
 
 public:
+    /**
+     *  C++ constructor and destructor
+     */
     Counter() {}
     virtual ~Counter() {}
     
-    Php::Value increment(Php::Parameters ¶ms) 
+    /**
+     *  Increment operation
+     *  This method gets one optional parameter holding the change
+     *  @param  int     Optional increment value
+     *  @return int     New value
+     */
+    Php::Value increment(Php::Parameters &params) 
     { 
         return _value += params.size() > 0 ? (int)params[0] : 1; 
     }
-    
-    Php::Value decrement(Php::Parameters ¶ms) 
+
+    /**
+     *  Decrement operation
+     *  This method gets one optional parameter holding the change
+     *  @param  int     Optional decrement value
+     *  @return int     New value
+     */
+    Php::Value decrement(Php::Parameters &params) 
     { 
         return _value -= params.size() > 0 ? (int)params[0] : 1; 
     }
     
+    /**
+     *  Method to retrieve the current value
+     *  @return int
+     */
     Php::Value value() const 
     { 
         return _value; 
     }
 };
 
+/**
+ *  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<Counter> counter("Counter");
         
         // register the increment method, and specify its parameters
-        counter.method("increment", &Counter::increment, { 
+        counter.method("increment", &Counter::increment, { 
             Php::ByVal("change", Php::Type::Numeric, false) 
         });
         
         // register the decrement, and specify its parameters
-        counter.method("decrement", &Counter::decrement, { 
+        counter.method("decrement", &Counter::decrement, { 
             Php::ByVal("change", Php::Type::Numeric, false) 
         });
         
         // register the value method
-        counter.method("value", &Counter::value);
+        counter.method("value", &Counter::value, {});
         
         // add the class to the extension
         myExtension.add(std::move(counter));
@@ -195,6 +261,144 @@ echo($counter->value()."\n");
     thought that an example was not really necessary (and we're not a big fan
     of parameters-by-reference either).
 

+
Static methods

+

+    Static methods are supported too. A static method is a method that does
+    not have access to a 'this' pointer when it is called. In C++, such a static method
+    is therefore identical to a regular function, which also does not
+    have a 'this' pointer. The only difference between static C++ methods and 
+    regular C++ functions is at compile time. The compiler allows the static 
+    method to access private data. The signature of a static method is however
+    completely identical to the signature of a regular function.
+

+

+    PHP-CPP allows you to register static methods. But because the signature of
+    a static method is identical to the signature of a regular function, the static 
+    PHP method that you register does not even have to be a static method of the 
+    C++ class. Regular functions and static methods of other classes
+    have the same signature and can be registered too! From a software architectural
+    standpoint, it of course is better to use only static methods of the same class.
+

+

+#include <phpcpp.h>
+
+/**
+ *  Regular function
+ *
+ *  Because a regular function does not have a 'this' pointer,
+ *  it has the same signature as static methods
+ *
+ *  @param  params      Parameters passed to the function
+ */
+void regularFunction(Php::Parameters &params)
+{
+    // @todo add implementation
+}
+
+/**
+ *  A very simple class that will not be exported to PHP
+ */
+class PrivateClass
+{
+public:
+    /**
+     *  C++ constructor and destructor
+     */
+    PrivateClass() {}
+    virtual ~PrivateClass() {}
+
+    /** 
+     *  Static method
+     *
+     *  A static method also has no 'this' pointer and has
+     *  therefore a signature identical to regular functions
+     *
+     *  @param  params      Parameters passed to the method
+     */
+    static void staticMethod(Php::Parameters &params)
+    {
+        // @todo add implementation
+    }
+};
+
+/**
+ *  A very simple class that will be exported to PHP
+ */
+class PublicClass : Php::Base
+{
+public:
+    /**
+     *  C++ constructor and destructor
+     */
+    PublicClass() {}
+    virtual ~PublicClass() {}
+
+    /** 
+     *  Another static method
+     *
+     *  This static has exactly the same signature as the
+     *  regular function and static method that were mentioned
+     *  before
+     *
+     *  @param  params      Parameters passed to the method
+     */
+    static void staticMethod(Php::Parameters &params)
+    {
+        // @todo add implementation
+    }
+};
+
+/**
+ *  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<PublicClass> myClass("MyClass");
+        
+        // register the PublicClass::staticMethod to be a
+        // static method callable from PHP
+        myClass.method("static1", &PublicClass::staticMethod);
+        
+        // regular functions have the same signatures as 
+        // static methods. So nothing forbids you to register
+        // a normal function as static method too
+        myClass.method("static2", regularFunction);
+        
+        // and even static methods from completely different
+        // classes have the same function signature and can
+        // thus be registered
+        myClass.method("static3", &PrivateClass::staticMethod);
+        
+        // add the class to the extension
+        myExtension.add(std::move(counter));
+        
+        // In fact, because a static method has the same signature
+        // as a regular function, you can also register static
+        // C++ methods as regular global PHP functions
+        myExtension.add("myFunction", &PrivateClass::staticMethod);
+        
+        // return the extension
+        return myExtension;
+    }
+}
+

+

+

+    It is questionable how useful this all is. It is probably advisable to keep 
+    your code clean, simple and maintainable, and only register static PHP methods 
+    that are also in C++ static methods of the same class. But C++ does not forbid
+    you to do it completely different.
+

 
Access modifiers

 

     In PHP (and in C++ too) you can mark methods as public, private or protected.
@@ -205,8 +409,18 @@ echo($counter->value()."\n");
 

 

 

+/**
+ *  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
@@ -258,8 +472,18 @@ extern "C" {
 

 

 

+/**
+ *  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
@@ -282,8 +506,18 @@ extern "C" {
 

 

 

+/**
+ *  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
-- 
cgit v1.2.3