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

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

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.

Copyright Symisc Systems, SUARL

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

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:

Copyright Symisc Systems, SUARL

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

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. }
Copyright Symisc Systems, SUARL

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

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

Copyright Symisc Systems, SUARL

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

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/

Copyright Symisc Systems, SUARL