Initializing

Initializing the object is as simple as including the code and instantiating it.

#include "php_stl.h"
...
php_stl p;

Passing true as an optional argument to the php_stl creator will enable warnings when the php object has to type cast a result returned from PHP evaluation. It is generally recommended to only turn those warnings on for debugging or if it is always an error condition for data of non-exact type to be returned by the PHP functions being called. The behavior of these type mismatch errors can also be controlled by changing error output behavior as described in the next paragraph.

The php libraries have three different classes of output:

• Operational Output - This class contains all the strings produced in PHP by such commands as echo, print, or printf. The default behavior of the php libraries is to print these strings to stdout prepended with the string ``PHP OUTPUT:''. NOTE: Due to its primary application as a hypertext processor the default behavior in PHP is to only flush the output buffer when the PHP interpreter is destroyed; to get the output flushed sooner use the PHP function ob_flush().

• Messages - This class contains all the strings which represent errors or warnings produced in the interpretation of PHP but not fatal errors for the PHP interpreter itself or the php object. Good examples are calling an undefined function in PHP or using a non-array in the PHP foreach construct. The default behavior of the php libraries is to print these strings to stderr prepended with the string ``PHP MESSAGE:.''

• Errors - This class contains all the error strings generated by the php object itself as it attempts to process the commands given. Such errors could result from improper argument passing, illegal function calling, or any generic malfunction in the core PHP interpreter code. The default behavior of the php libraries is to print this to stderr prepended with the string ``PHP ERROR:.'' NOTE: The aforementioned optional type mismatch errors fall into this class of output.

The client can alter the default behavior by providing an alternative function to handle the output:

void print_null(const char *str) {}
void print_mine(const char *str) { printf("My Output: %s", str); }
...
p.set_message_function(print_null);
p.set_output_function(print_mine);

This code directs the php object to discard all message output and prepend all operational output with the string ``My Output:'' before printing it to stdout. Default error output behavior remains in place although it could have been changed as well by passing print_null or print_mine to set_error_function. It is not a requirement to change any of output behaviors.

The final phase of initialization for most clients would be loading the PHP code into the interpreter:

if(SUCCESS != p.load("usage.php")){
  printf("load failed\n");
  exit(1);
}

This also isn't a requirement; clients could define functions just by creating strings in C++ and calling eval_string with them. In most cases the most flexible thing to do is keep that functionality in a separate file so it can be changed without having to recompile the binary. Note the check for success at the end, this is important so the program doesn't get too far before realizing the php object is broken. This check can be done after any function call to detect if the php object has gotten into a bad state.