path: root/documentation/classes-and-objects.html

<h1>Classes and objects</h1>
<p>
    Serious business now. C++ and PHP are both object oriented programming 
    languages, in which you can create classes and objects. The PHP-CPP library
    gives you the tools to combine these two and make a native C++ class 
    accessible from PHP.
</p>
<p>
    Sadly (but also logically if you think about it) not every thinkable C++ class can be directly 
    exported to PHP. It takes a little more work (although not so much). For a
    start, you must make sure that your class is derived from Php::Base, and 
    secondly, when you add your class to the extension object, you must also  
    specify all methods that you want to make accessible from PHP.
</p>
<p>
<pre class="language-c++"><code>
#include &lt;phpcpp.h&gt;

// actual class implementation
class Counter : public Php::Base
{
private:
    int _value = 0;

public:
    Counter() {}
    virtual ~Counter() {}
    
    Php::Value increment() { return ++_value; }
    Php::Value decrement() { return --_value; }
    Php::Value value() const { return _value; }
};

extern "C" {
    PHPCPP_EXPORT void *get_module() {
        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>
    Let's talk about programming conventions first - I always use capitals for 
    the first letter of a classname, and my member variables always start with
    an underscore. Every class always has a destructor, and it always is virtual.
    That's just a convention - my convention - and you do not 
    have to follow that.
</p>
<p>
    On topic. The example shows a very simple Counter class with three methods:
    increment(), decrement() and value(). The two update methods return the value 
    of the counter after the operation, the value() method returns the current value.
</p>
<p>
    If you want to make a class method that is accessible from PHP, you must
    ensure that is has one of the eight supported signatures (which are the same
    signatures that <a href="functions">exportable plain functions</a> can have),
    plus their const variant.
</p>
<p>
<pre class="language-c++"><code>
void YourClass::example1();
void YourClass::example2(Php::Parameters &amp;params);
Php::Value YourClass::example3();
Php::Value YourClass::example4(Php::Parameters &amp;params);
void YourClass::example5() const;
void YourClass::example6(Php::Parameters &amp;params) const;
Php::Value YourClass::example7() const;
Php::Value YourClass::example8(Php::Parameters &amp;params) const;
</code></pre>
</p>
<p>
    In the example we have used the third and seventh method forms, methods that do
    not accept any parameters, and that return a Php::Value object. Methods
    work exactly the same as <a href="functions">regular functions</a>, with the 
    difference that in the methods you have (of course) access to the member
    variables of the object (and in C++ you you do not have to use "this->"
    explicitly to access members).
</p>
<p>
    To make the class accessible from PHP, you must add it to the extension
    object inside the get_module() function. The Php::Class template class can be 
    be used for that. The template parameter should be your 
    implementation class, so that the Php::Class object internally knows which 
    class to instantiate the moment the "new" operator is used inside a PHP script.
</p>
<p>
    The Php::Class constructor receives a string parameter, with the name of 
    the class in PHP. After you've created an instance of the Php::Class object,
    you should specify all methods that you want to make accessible from PHP,
    and finally, when all methods have been registered, you should add the 
    class to your extension object so that it will be accessible from PHP.
    Notice that in our example we have used the C++11 std::move() function for this, so
    that the class object is actually <i>moved</i> into the extension object,
    which is a more efficient operation than copying.
</p>
<h2>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 
    parameters of a function</a>, you can specify method parameters too.
</p>
<p>
<pre class="language-c++"><code>
#include &lt;phpcpp.h&gt;

// actual class implementation
class Counter : public Php::Base
{
private:
    int _value = 0;

public:
    Counter() {}
    virtual ~Counter() {}
    
    Php::Value increment(Php::Parameters &params) 
    { 
        return _value += params.size() > 0 ? (int)params[0] : 1; 
    }
    
    Php::Value decrement(Php::Parameters &params) 
    { 
        return _value -= params.size() > 0 ? (int)params[0] : 1; 
    }
    
    Php::Value value() const 
    { 
        return _value; 
    }
};

extern "C" {
    PHPCPP_EXPORT void *get_module() {
        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");
        
        // register the increment method, and specify its parameters
        counter.method("increment", &Counter::increment, { 
            Php::ByVal("change", Php::Type::Numeric, false) 
        });
        
        // register the decrement, and specify its parameters
        counter.method("decrement", &Counter::decrement, { 
            Php::ByVal("change", Php::Type::Numeric, false) 
        });
        
        // register the value method
        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>
    In the code above we have modified our first example. The increment and
    decrement method now get an optional 'change' parameter, which is a numeric
    value that holds the change that should be applied to the counter. Note that
    this parameter is optional - so inside the method implementation we 
    check if the number of parameters is bigger than zero to prevent nasty 
    segmentation faults.
</p>
<p>
<pre class="language-php"><code>
&lt;?php
$counter = new Counter();
$counter->increment(5);
$counter->increment();
$counter->decrement(3);
echo($counter->value()."\n");
?&gt;
</code></pre>
</p>
<p>
    The code above shows a PHP script that uses the native Counter class.
    The output of above script is (as you had of course expected) 3.
</p>
<p>
    In the example code we have not shown how to use the Php::ByRef class, but
    that works exaclty the same as in methods, so we thought that an example 
    was not really necessary.
</p>
<h2>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 
    flags parameter when you add the method to the Php::Class object. Image that
    you want to make the increment and decrement methods in our previous example
    protected, then you can simply add a flag:
</p>
<p>
<pre class="language-c++"><code>
extern "C" {
    PHPCPP_EXPORT void *get_module() {
        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");
        
        // register the increment method, and specify its parameters
        counter.method("increment", &Counter::increment, Php::Protected, { 
            Php::ByVal("change", Php::Type::Numeric, false) 
        });
        
        // register the decrement, and specify its parameters
        counter.method("decrement", &Counter::decrement, Php::Protected, { 
            Php::ByVal("change", Php::Type::Numeric, false) 
        });
        
        // register the value method
        counter.method("value", &Counter::value, Php::Public | Php::Final);
        
        // add the class to the extension
        myExtension.add(std::move(counter));
        
        // return the extension
        return myExtension;
    }
}
</code></pre>
</p>
<p>
    By default, every method (and every property too, but we deal with that later) 
    is public. You can pass in an additional Php::Protected or Php::Private flag
    if you want to mark a method as being either protected or private. The flag
    parameter can be bitwise-or'ed with Php::Abstract or Php::Final if you also 
    want to mark your method as being either abstract or final. We did this with
    the value() method, so that it becomes impossible to override this method in a
    derived class.
</p>
<p>
    Remember that the exported methods in your C++ class must always be public - even
    when you've marked them as being private or protected in PHP. This makes sense,
    because after all, your methods are called by the PHP-CPP library, and if you make
    them private, the becomes invisible for the library.
</p>
<h2>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
    class abstract or final, you can do so by using Php::FinalClass or 
    Php::AbstractClass instead of Php::Class.
</p>
<p>
<pre class="language-c++"><code>
extern "C" {
    PHPCPP_EXPORT void *get_module() {
        static Php::Extension myExtension("my_extension", "1.0");
        
        // description of the class so that PHP knows which methods are accessible
        Php::FinalClass&lt;Counter&gt; counter("Counter");
        
        // register methods
        ...
        
        // return the extension
        return myExtension;
    }
}
</code></pre>
</p>
<p>
    It may seem strange that you have to pass in the address of a real C++ method
    when you mark a method as being abstract. Abstract methods do normally not 
    have an implementation, so what do you need this C++ implementation for?
    Luckily, there also is a different way for registering abstract methods.
</p>
<p>
<pre class="language-c++"><code>
extern "C" {
    PHPCPP_EXPORT void *get_module() {
        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");
        
        // register an abstract method
        counter.method("myAbstractMethod", { Php::ByVal("value", Php::Type::String, true) });
        
        // register other methods
        ...
        
        // return the extension
        return myExtension;
    }
}
</code></pre>
</p>
<p>
    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>
<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 
    destructors</a>.
</p>