Symisc PH7 Engine
An Embeddable PHP5 Engine

PH7 in 5 minutes or less

Here is what you do to start experimenting with the PH7 engine without having to do a lot of tedious reading and configuration:

download The Code

Get a copy of the last public release of the PH7 engine. Visit the download page for more information.

Write Programs That Use PH7

Below is a simple C program that demonstrates how to use the C/C++ interface to PH7. This program compile and execute the following PHP script.

   echo 'Welcome guest'.PHP_EOL;
   echo 'Current system time is: '.date('Y-m-d H:i:s').PHP_EOL;
   echo 'and you are running '.php_uname();

That is, this simple PHP script when running should display a greeting message, the current system time and the host operating system. A typical output of this program would look like this:

Welcome guest

Current system time is: 2012-09-14 10:08:44

and you are running Microsoft Windows 7 localhost 6.1 build 7600 x86

Here is the C code. Note that you can get a working version of this program here:

  1. #include "ph7.h"

  2. int main(void)

  3. {

  4.   ph7 *pEngine; /* PH7 engine */

  5.   ph7_vm *pVm; /* Compiled PHP program */

  6.   int rc;

  7.   /* Allocate a new PH7 engine instance */

  8.   rc = ph7_init(&pEngine);

  9.   if( rc != PH7_OK ){

  10.    /*

  11.     * If the supplied memory subsystem is so sick that we are unable

  12.     * to allocate a tiny chunk of memory, there is no much we can do here.

  13.     */

  14.    Fatal("Error while allocating a new PH7 engine instance");

  15.   }

  16.   /* Compile the PHP test program defined above */

  17.   rc = ph7_compile_v2(

  18.       pEngine, /* PH7 engine */

  19.       PHP_PROG, /* PHP test program */

  20.       -1 /* Compute input length automatically*/,

  21.       &pVm, /* OUT: Compiled PHP program */

  22.       0 /* IN: Compile flags */

  23.    );

  24.   if( rc != PH7_OK ){

  25.     if( rc == PH7_COMPILE_ERR ){

  26.       const char *zErrLog;

  27.       int nLen;

  28.      /* Extract error log */

  29.      ph7_config(pEngine,

  30.        PH7_CONFIG_ERR_LOG,

  31.        &zErrLog,

  32.        &nLen

  33.      );

  34.    if( nLen > 0 ){

  35.      /* zErrLog is null terminated */

  36.      puts(zErrLog);

  37.     }

  38.   }

  39.   /* Exit */

  40.   Fatal("Compile error");

  41. }

  42. /*

  43.  * Now we have our script compiled, it's time to configure our VM.

  44.  * We will install an output consumer callback that redirect

  45.  * the VM output to STDOUT (download the C file to see the implementation).

  46.  */

  47. rc = ph7_vm_config(pVm,

  48.       PH7_VM_CONFIG_OUTPUT,

  49.       Output_Consumer, /* Output Consumer callback */

  50.       0 /* Callback private data */

  51.    );

  52.   if( rc != PH7_OK ){

  53.      Fatal("Error while installing the VM output consumer callback");

  54.   }

  55. /*

  56. * And finally, execute our program. Note that your output (STDOUT in our case)

  57. * should display the result.

  58. */

  59. ph7_vm_exec(pVm,0);

  60. /* All done, cleanup the mess left behind.

  61. */

  62. ph7_vm_release(pVm);

  63. ph7_release(pEngine);

  64. return 0;

  65. }

Download the C file.

We create a new PH7 engine instance using a call to ph7_init() on line 8. This is often the first PH7 API call that an application makes and is a prerequisite in order to compile PHP code using one of the compile interfaces.

We compile our PHP test program on line 17 using the ph7_compile_v2() interface.

We configure our Virtual Machine on line 47 by setting a VM output consumer callback named Output_Consumer() (Download the C file to see the implementation). All this callback does is redirecting the VM output to STDOUT using the libc printf() routine or the write() system call.

And finally we execute our PHP program on line 59 using a call to ph7_vm_exec(). You should see now the greeting message, the current date and the host operating system.

Clean-up is done on line 62 and 63 respectively via calls to ph7_vm_release() and ph7_release().

Compile the program

Compile this C file together with the PH7 engine source code to generate the executable. For example:

gcc -W -Wall -O6 -o ph7_test ph7_intro.c ph7.c

When running [./ph7_test ] you should see the greeting message, the current system time and the host operating system.

Stand-alone Interpreter For PH7

The PH7 download page includes a simple stand-alone PHP interpreter named ph7 (or ph7.exe on windows) that allows the user to enter and execute PHP files against a PH7 engine. This utility is available in prebuilt binaries forms or can be compiled from source. You can get a copy of the PH7 interpreter from the download page.

To start the ph7 program, just type "ph7" followed by the name of the PHP file to compile and execute. That is, the first argument is to the interpreter, the rest are scripts arguments, press "Enter" and the PHP code will be executed.

If something goes wrong while processing the PHP script due to a compile-time error, your error output (STDOUT) should display the compile-time error messages.

Usage example of the ph7 interpreter:

Running the interpreter

ph7 scripts/hello_world.php

Running the interpreter with script arguments

ph7 scripts/mp3_tag.php /usr/local/path/to/my_mp3s

The PH7 interpreter package includes more than 70 PHP scripts to test ranging from simple hello world programs to XML processing, zip archive extracting, MP3 tag extracting, UUID generation, JSON encoding/decoding, INI processing, Base32 encoding/decoding and many more. These scripts are available in the scripts directory from the zip archive.


Check out the Introduction To The PH7 C/C++ Interface for an introductory overview and roadmap to the dozens of PH7 interface functions.

A separate document, The PH7 C/C++ Interface, provides detailed specifications for all of the various C/C++ APIs for PH7. Once the reader understands the basic principles of operation for PH7, that document should be used as a reference guide.

Any questions, check the Frequently Asked Questions page or visit the Support Page for online community support.

Symisc Systems
Copyright © Symisc Systems