
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:
- /* Compile this 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
- */
- /*
- * This simple program is a quick introduction on how to embed and start
- * experimenting with the PH7 engine without having to do a lot of tedious
- * reading and configuration.
- *
- * For an introduction to the PH7 C/C++ interface, please refer to this page
- * http://ph7.symisc.net/api_intro.html
- * For the full C/C++ API reference guide, please refer to this page
- * http://ph7.symisc.net/c_api.html
- */
- /*
- * The following is the PHP program to execute.
- * <?php
- * 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 program 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 02:08:44
- * and you are running Microsoft Windows 7 localhost 6.1 build 7600 x86
- *
- */
- #define PHP_PROG "<?php "\
- "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();"\
- "?>"
- /* Make sure you have the latest release of the PH7 engine
- * from:
- * http://ph7.symisc.net/downloads.html
- */
- #include <stdio.h>
- #include <stdlib.h>
- /* Make sure this header file is available.*/
- #include "ph7.h"
- /*
- * Display an error message and exit.
- */
- static void Fatal(const char *zMsg)
- {
- puts(zMsg);
- /* Shutdown the library */
- ph7_lib_shutdown();
- /* Exit immediately */
- exit(0);
- }
- /*
- * VM output consumer callback.
- * Each time the virtual machine generates some outputs, the following
- * function gets called by the underlying virtual machine to consume
- * the generated output.
- * All this function does is redirecting the VM output to STDOUT.
- * This function is registered later via a call to ph7_vm_config()
- * with a configuration verb set to: PH7_VM_CONFIG_OUTPUT.
- */
- static int Output_Consumer(const void *pOutput, unsigned int nOutputLen, void *pUserData /* Unused */)
- {
- /*
- * Note that it's preferable to use the write() system call to display the output
- * rather than using the libc printf() which everybody now is extremely slow.
- */
- printf("%.*s",
- nOutputLen,
- (const char *)pOutput /* Not null terminated */
- );
- /* All done, VM output was redirected to STDOUT */
- return PH7_OK;
- }
- /*
- * Main program: Compile and execute the PHP program defined above.
- */
- int main(void)
- {
- ph7 *pEngine; /* PH7 engine */
- ph7_vm *pVm; /* Compiled PHP program */
- int rc;
- /* Allocate a new PH7 engine instance */
- rc = ph7_init(&pEngine);
- if( rc != PH7_OK ){
- /*
- * If the supplied memory subsystem is so sick that we are unable
- * to allocate a tiny chunk of memory, there is no much we can do here.
- */
- Fatal("Error while allocating a new PH7 engine instance");
- }
- /* Compile the PHP test program defined above */
- rc = ph7_compile_v2(
- pEngine, /* PH7 engine */
- PHP_PROG, /* PHP test program */
- -1 /* Compute input length automatically*/,
- &pVm, /* OUT: Compiled PHP program */
- 0 /* IN: Compile flags */
- );
- if( rc != PH7_OK ){
- if( rc == PH7_COMPILE_ERR ){
- const char *zErrLog;
- int nLen;
- /* Extract error log */
- ph7_config(pEngine,
- PH7_CONFIG_ERR_LOG,
- &zErrLog,
- &nLen
- );
- if( nLen > 0 ){
- /* zErrLog is null terminated */
- puts(zErrLog);
- }
- }
- /* Exit */
- Fatal("Compile error");
- }
- /*
- * Now we have our script compiled, it's time to configure our VM.
- * We will install the output consumer callback defined above
- * so that we can consume and redirect the VM output to STDOUT.
- */
- rc = ph7_vm_config(pVm,
- PH7_VM_CONFIG_OUTPUT,
- Output_Consumer, /* Output Consumer callback */
- 0 /* Callback private data */
- );
- if( rc != PH7_OK ){
- Fatal("Error while installing the VM output consumer callback");
- }
- /*
- * And finally, execute our program. Note that your output (STDOUT in our case)
- * should display the result.
- */
- ph7_vm_exec(pVm,0);
- /* All done, cleanup the mess left behind.
- */
- ph7_vm_release(pVm);
- ph7_release(pEngine);
- return 0;
- }
We create a new PH7 engine instance using a call to ph7_init() on line 86. 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 95 using the ph7_compile_v2() interface.
We configure our Virtual Machine on line 125 by setting a VM output consumer callback named Output_Consumer(). 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 137 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 140 and 141 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.
Next
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.
