Writing PHP Extensions – Part 3 The Four Kinds of Functions

See Part 2 Here.

The PHP-CPP library defines four kinds of functions which your extension can have, based on the arguments that can be passed and the values that can be returned. All the public functions that you set up as part of your extension have to fall into one of these four kinds:

1. Function which takes no arguments and returns no value.
2. Function which takes in arguments and returns no value.
3. Function which takes in no arguments and returns a value.
4. Function which takes in arguments and returns a value.

The function signatures of the above types are defined as below:

1. void function();
2. void function(Php::Parameters &params);
3. Php::Value function();
4. Php::Value function(Php::Parameters &params);

As you can see there are only two types of data which are used to interact with the functions.

Php::Value and Php::Parameters

Php::Value is a class defined in PHP-CPP which has a flexible loose data-type , very similar to a php variable. So it can store numbers, strings, arrays and objects. Php::Value is used to return value from functions.

Php::Parameters is also a class defined in PHP-CPP which is basically a dynamic array or a vector which contains a list of all the parameters passed into a function. This means that using a single Php::Parameters argument type, a function can take in a variable number of arguments of different data types. As the name suggests, Php::Parameters are used to pass data into functions.

CODE

The code below shows the four kinds of functions being used in the helloworld extension. As you can see the integration part is very simple – you write the function and then use the extension.add method to make it a callable function from PHP code.

 

#include <phpcpp.h>
#include <iostream>


/**
 * Function which takes no arguments and returns no values
 *
 */
void sayHello() {
	std::cout << "Hello World \t This is my first PHP extension" << std::endl;

}

/**
 * Function which takes in arguments and returns no value
 * 
 */
 void sayHelloWithInputs(Php::Parameters &params) {
	
	std::string arg1=params[0];

	std::cout << "Hello World \t" << arg1 << std::endl;


 }

/**
 * Function which takes no arguments and returns a value
 *
 */
 Php::Value sayHelloWithReturnValue() {
	
	return "Hello World. This is a return value.\n";
 }

 /**
  * Function which takes in arguments and returns a value
  *
  */
 Php::Value sayHelloWithArgumentsAndReturnValue(Php::Parameters &params) {
	
	std::string arg1 = params[0];
	std::string retval = "Hello World \t with argument:" + arg1 + "\n";

	return retval;
 } 

/**
 *  tell the compiler that the get_module is a pure C function
 */
extern "C" {
    
    /**
     *  Function that is called by PHP right after the PHP process
     *  has started, and that returns an address of an internal PHP
     *  strucure with all the details and features of your extension
     *
     *  @return void*   a pointer to an address that is understood by PHP
     */
    PHPCPP_EXPORT void *get_module() 
    {
        // static(!) Php::Extension object that should stay in memory
        // for the entire duration of the process (that's why it's static)
        static Php::Extension extension("helloworld", "1.0");
        
        // @todo    add your own functions, classes, namespaces to the extension
        extension.add("sayHello", sayHello);
		extension.add("sayHelloWithInputs", sayHelloWithInputs);
		extension.add("sayHelloWithReturnValue", sayHelloWithReturnValue);
		extension.add("sayHelloWithArgumentsAndReturnValue", sayHelloWithArgumentsAndReturnValue);

        // return the extension
        return extension;
    }
}

To compile the extension run make and then sudo make install. (See part 2 for details on this).

Create a php file with the code below and run it from the php command line eg. php test.php

PHP TEST CODE

<?php

sayHello();
sayHelloWithInputs("This is a string");
sayHelloWithInputs(789*10); 
sayHelloWithInputs(date("Y-i-d"));
sayHelloWithInputs(strlen("this is a string"));

$arr = array();
for($i = 0; $i< 10; $i++) {
	$arr[$i] = $i;
}
sayHelloWithInputs(implode(",", $arr));

echo sayHelloWithReturnValue();

echo sayHelloWithArgumentsAndReturnValue("my parameter");

?>

EXPLANATION

In the functions , we are assuming that the arguments passed are all strings or can be converted into strings. So that is why  sayHelloWithInputs() works with all kinds of inputs: integers, arrays, strings.

If instead of sayHelloWithInputs(implode(“,”, $arr)); you write sayHelloWithInputs($arr) it will output the string “Array” since that is the string representation of an Array object.

The two functions sayHello() and sayHelloWithInputs() are defined as functions which will not return any values, but yet you can see the output on the display. That is because in these two functions , we are using the c++ function std::cout which dislays text to the default output device. It is much like using var_dump() in PHP which generates output.

So if you assign sayHello() to a variable like $x = sayHello() then $x will contain the display output from the function.

sayHelloWithReturnValue() does not generate any output in its function code but it returns a value. So if you call the function as sayHelloWithReturnValue(); in php it will not generate any display.

$x = sayHelloWithReturnValue(); will assign the return value to $x and then you can use $x as required.

 

 Next: Part 4 Function Arguments