From 30eff69a10898dd9b2fb10ed07ae8c68458a5ad2 Mon Sep 17 00:00:00 2001 From: Emiel Bruijntjes Date: Sun, 25 Jan 2015 21:25:18 +0100 Subject: added documentation about class constants --- documentation/constants.html | 165 ++++++++++++++++++++++++++++++++++++++++++ documentation/properties.html | 8 +- 2 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 documentation/constants.html (limited to 'documentation') diff --git a/documentation/constants.html b/documentation/constants.html new file mode 100644 index 0000000..cd51224 --- /dev/null +++ b/documentation/constants.html @@ -0,0 +1,165 @@ +

Constants

+

+ In PHP scripts you can define constants - both global constants and + class level constants. This can also be done with PHP-CPP. If you want + to expose constants to user space PHP code, you can do that by adding + the constants to the Php::Extension object inside the get_module() + call. +

+

+


+#include <phpcpp.h>
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // add integer constants
+        myExtension.add(Php::Constant("MY_CONSTANT_1", 1));
+        myExtension.add(Php::Constant("MY_CONSTANT_2", 2));
+        
+        // floating point constants
+        myExtension.add(Php::Constant("MY_CONSTANT_3", 3.1415927));
+        myExtension.add(Php::Constant("MY_CONSTANT_4", 4.932843));
+        
+        // string constants
+        myExtension.add(Php::Constant("MY_CONSTANT_5", "This is a constant value"));
+        myExtension.add(Php::Constant("MY_CONSTANT_6", "Another constant value"));
+        
+        // null constants
+        myExtension.add(Php::Constant("MY_CONSTANT_7", nullptr));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+
+

+

+ It is all very straight forward. Using the constants in a PHP script is + just as easy: +

+

+


+<?php
+echo(MY_CONSTANT_1."\n");
+echo(MY_CONSTANT_2."\n");
+echo(MY_CONSTANT_3."\n");
+echo(MY_CONSTANT_4."\n");
+echo(MY_CONSTANT_5."\n");
+echo(MY_CONSTANT_6."\n");
+echo(MY_CONSTANT_7."\n");
+?>
+
+

+

+ PHP also supports the concept of class level constants. Internally, in + the Zend engine, class level constants are implemented as regular class + members, but instead of a "public" or "private" flag, a constant property + is marked with a "constant" flag. PHP-CPP exposes this too. You can + register class properties with a Php::Const flag. +

+

+ Besides this, a Php::Class instance also has a "constant" method, and + you can add instances of Php::Constant to the class. Semantically, all + these three ways to create class level constants are identical. +

+

+


+/**
+ *  The C++ class that we're going to expose
+ *
+ *  (For this example we use a completely empty class, as only examples
+ *  are given on how to use constants)
+ */
+class Dummy : public Php::Base
+{
+};
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // create a class objects
+        Php::Class<Dummy> dummy("Dummy");
+        
+        // there are many different ways to add constants, but semantically,
+        // they're all the same
+        dummy.property("MY_CONSTANT_1", 1, Php::Const);
+        dummy.property("MY_CONSTANT_2", "abcd", Php::Const);
+        dummy.constant("MY_CONSTANT_3", "xyz");
+        dummy.constant("MY_CONSTANT_4", 3.1415);
+        dummy.add(Php::Constant("MY_CONSTANT_5", "constant string"));
+        dummy.add(Php::Constant("MY_CONSTANT_5", true));
+        
+        // add the class to the extension
+        myExtension.add(std::move(dummy));
+        
+        // return the extension
+        return myExtension;
+    }
+}
+
+

+

Runtime constants

+

+ If you want to find out the value of a user space constant at runtime + from your C++ code, or when you want to find out if a constant is + defined or not, you can simply use the Php::constant() or Php::defined() + functions. To define constants at runtime, use Php::define(): +

+

+


+/**
+ *  Function that can be called from a PHP script
+ */
+void example_function()
+{
+    // check if a certain user space constant is defined
+    if (Php::defined("USER_SPACE_CONSTANT"))
+    {
+        // retrieve the value of a constant
+        Php::Value constant = Php::constant("ANOTHER_CONSTANT");
+        
+        // define other constants at runtime
+        Php::define("DYNAMIC_CONSTANT", 12345);
+    }
+}
+
+/**
+ *  Switch to C context so that the get_module() function can be
+ *  called by C programs (which the Zend engine is)
+ */
+extern "C" {
+    /**
+     *  Startup function for the extension
+     *  @return void*
+     */
+    PHPCPP_EXPORT void *get_module() {
+        static Php::Extension myExtension("my_extension", "1.0");
+        
+        // add a function to the extension
+        extension.add("example_function", example_function);
+        
+        // return the extension
+        return myExtension;
+    }
+}
+
+

diff --git a/documentation/properties.html b/documentation/properties.html index 6f3ece5..db7c44f 100644 --- a/documentation/properties.html +++ b/documentation/properties.html @@ -194,7 +194,13 @@ extern "C" {

The class constant can be accessed from PHP scripts using Example::MY_CONSTANT, - and the static properties with Example::$my_property. + and the static properties with Example::$my_property. +

+

+ Besides using the property() method, you can also + create class constants using the constant() method, or using the + Php::Constant class. More information about this can be found in our + article about constants.

Smart properties

-- cgit v1.2.3