Introduction To Embedding The PH7 PHP Engine in a C/C++ Host Application.

PH7 Engine Introduction: http://ph7.symisc.net

Introduction To Embedding PH7 PHP Engine in a C/C++ Host Application.
November 08, 2012
http://ph7.symisc.net/

Author: Mrad Chems Eddine <chm@symisc.net>

Copyright © Symisc Systems, SUARL


What is PH7
PH7 is a in-process software library that implements a highly-efficient embeddable bytecode
compiler and a virtual machine for the PHP programming language. In other words, PH7 is a
PHP engine which allow the host application to compile and execute PHP scripts in-process.
PH7 is to PHP what SQLite is to SQL.
PH7 implements most of the constructs introduced by the PHP 5.3 release such as heredoc,
nowdoc, gotos, classes, anonymous functions, closures and so on and introduces very powerful
extensions to the PHP programming language such as:

• Function & Method Overloading.
• Full Type Hinting.
• Introducing comma expressions.
• Introducing the eq and ne operators for strict string comparison.
• Improved operators precedences.
• Powerful OO subsystem.
• Function arguments can take any complex expressions as their default values.
• 64-bit integer arithmetic for all platforms.
• Native UTF-8 support.
• PH7 is 100% hand-coded, written in ANSI C, compile and run unmodified in any
platform including restricted embedded devices with a C compiler.
• Amalgamation: All C source code for PH7 are combined into a single source file.
• Built with more 470 function including an XML parser (with namespace support), INI
processor, CSV reader/writer, UTF-8 encoder/decoder, zip archive extractor, JSON
encoder/decoder, random number/strings generator, native and efficient File IO for
Windows and UNIX systems and many more without the need of any external library to
link with.
• PH7 is an Open-Source product.
Refer to the feature page for a detailed description.

PH7 is the ideal library for enhancing your application (i.e: SCM, Server, CMS, Control panel,
Search engine, etc.) or device (i.e: router, set-top box, etc.) with dynamic web interfaces, with
all benefits and power of the PHP(5) programming language without the overhead uncured by
the insecure CGI mechanism and it's high costs such as process creation (fork(), exec()) since
PH7 run in-process.

As an embedded interpreter, it allows multiple interpreter states to coexist in the same
program, without any interference between them. Programmatically, foreign functions in C can
be added and values can be defined in the PHP environment. Being a quite small program, it is
easy to comprehend, get to grips with, and use.

PH7 is 100% hand-coded, written in ANSI C, compiles unmodified and should run in any
platform including restricted embedded device with a C compiler.
PH7 is extensively tested on Windows and UNIX systems especially Linux, FreeBSD, Oracle
Solaris and Mac OS X.



PH7 is a compact library. With all features enabled, the library size can be less than 600KiB,
depending on compiler optimization settings. (Some compiler optimizations such as aggressive
function inlining and loop unrolling can cause the object code to be much larger.) If optional
features are omitted, the size of the PH7 library can be reduced below 220KiB. PH7 can also be
made to run in very little heap (2MB), making PH7 a popular PHP engine choice on memory
constrained gadgets such as cellphones, tablets, numeric devices and so on.

PH7 is an open-source, dual-licensed product available free of charge for open-source projects
under the term of the Symisc Public License (SPL) which is a GPL compatible license and is
equivalent to the more popular Sleepycat license (An OSI approved license). See the
licensing page for additional information.

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.

<?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 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.

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.
PH7 Engine Homepage: http://ph7.symisc.net/


Introduction To Embedding The PH7 PHP Engine in a C/C++ Host Application.

More Related Content

What's hot (20)

Similar to Introduction To Embedding The PH7 PHP Engine in a C/C++ Host Application. (20)

Recently uploaded (20)

Introduction To Embedding The PH7 PHP Engine in a C/C++ Host Application.