1# The embed SAPI 2 3A server application programming interface (SAPI) is the entry point into the Zend Engine. The embed SAPI is a lightweight SAPI for calling into the Zend Engine from C or other languages that have C bindings. 4 5## Basic Example 6 7Below is a basic example in C that uses the embed SAPI to boot up the Zend Engine, start a request, and print the number of functions loaded in the function table. 8 9```c 10/* embed_sapi_basic_example.c */ 11 12#include <sapi/embed/php_embed.h> 13 14int main(int argc, char **argv) 15{ 16 /* Invokes the Zend Engine initialization phase: SAPI (SINIT), modules 17 * (MINIT), and request (RINIT). It also opens a 'zend_try' block to catch 18 * a zend_bailout(). 19 */ 20 PHP_EMBED_START_BLOCK(argc, argv) 21 22 php_printf( 23 "Number of functions loaded: %d\n", 24 zend_hash_num_elements(EG(function_table)) 25 ); 26 27 /* Close the 'zend_try' block and invoke the shutdown phase: request 28 * (RSHUTDOWN), modules (MSHUTDOWN), and SAPI (SSHUTDOWN). 29 */ 30 PHP_EMBED_END_BLOCK() 31} 32``` 33 34To compile this, we must point the compiler to the PHP header files. The paths to the header files are listed from `php-config --includes`. 35 36We must also point the linker and the runtime loader to the `libphp.so` shared lib for linking PHP (`-lphp`) which is located at `$(php-config --prefix)/lib`. So the complete command to compile ends up being: 37 38```bash 39$ gcc \ 40 $(php-config --includes) \ 41 -L$(php-config --prefix)/lib \ 42 embed_sapi_basic_example.c \ 43 -lphp \ 44 -Wl,-rpath=$(php-config --prefix)/lib 45``` 46 47> :memo: The embed SAPI is disabled by default. In order for the above example to compile, PHP must be built with the embed SAPI enabled. To see what SAPIs are installed, run `php-config --php-sapis`. If you don't see `embed` in the list, you'll need to rebuild PHP with `./configure --enable-embed`. The PHP shared library `libphp.so` is built when the embed SAPI is enabled. 48 49If all goes to plan you should be able to run the program. 50 51```bash 52$ ./a.out 53Number of functions loaded: 1046 54``` 55 56## Function call example 57 58The following example calls `mt_rand()` and `var_dump()`s the return value. 59 60```c 61#include <main/php.h> 62#include <ext/standard/php_var.h> 63#include <sapi/embed/php_embed.h> 64 65int main(int argc, char **argv) 66{ 67 PHP_EMBED_START_BLOCK(argc, argv) 68 69 zval retval = {0}; 70 zend_fcall_info fci = {0}; 71 zend_fcall_info_cache fci_cache = {0}; 72 73 zend_string *func_name = zend_string_init(ZEND_STRL("mt_rand"), 0); 74 ZVAL_STR(&fci.function_name, func_name); 75 76 fci.size = sizeof fci; 77 fci.retval = &retval; 78 79 if (zend_call_function(&fci, &fci_cache) == SUCCESS) { 80 php_var_dump(&retval, 1); 81 } 82 83 zend_string_release(func_name); 84 85 PHP_EMBED_END_BLOCK() 86} 87``` 88 89## Execute a PHP script example 90 91```php 92<?php 93 94# example.php 95 96echo 'Hello from userland!' . PHP_EOL; 97``` 98 99```c 100#include <sapi/embed/php_embed.h> 101 102int main(int argc, char **argv) 103{ 104 PHP_EMBED_START_BLOCK(argc, argv) 105 106 zend_file_handle file_handle; 107 zend_stream_init_filename(&file_handle, "example.php"); 108 109 if (php_execute_script(&file_handle) == FAILURE) { 110 php_printf("Failed to execute PHP script.\n"); 111 } 112 113 PHP_EMBED_END_BLOCK() 114} 115``` 116 117## INI defaults 118 119The default value for 'error_prepend_string' is 'NULL'. The following example sets the INI default for 'error_prepend_string' to 'Embed SAPI error:'. 120 121```c 122#include <sapi/embed/php_embed.h> 123 124/* This callback is invoked as soon as the configuration hash table is 125 * allocated so any INI settings added via this callback will have the lowest 126 * precedence and will allow INI files to overwrite them. 127 */ 128static void example_ini_defaults(HashTable *configuration_hash) 129{ 130 zval ini_value; 131 ZVAL_NEW_STR(&ini_value, zend_string_init(ZEND_STRL("Embed SAPI error:"), /* persistent */ 1)); 132 zend_hash_str_update(configuration_hash, ZEND_STRL("error_prepend_string"), &ini_value); 133} 134 135int main(int argc, char **argv) 136{ 137 php_embed_module.ini_defaults = example_ini_defaults; 138 139 PHP_EMBED_START_BLOCK(argc, argv) 140 141 zval retval; 142 143 /* Generates an error by accessing an undefined variable '$a'. */ 144 if (zend_eval_stringl(ZEND_STRL("var_dump($a);"), &retval, "example") == FAILURE) { 145 php_printf("Failed to eval PHP.\n"); 146 } 147 148 PHP_EMBED_END_BLOCK() 149} 150``` 151 152After compiling and running, you should see: 153 154``` 155Embed SAPI error: 156Warning: Undefined variable $a in example on line 1 157NULL 158``` 159 160This default value is overwritable from INI files. We'll update one of the INI files (which can be found by running `$ php --ini`), and set `error_prepend_string="Oops!"`. We don't have to recompile the program, we can just run it again and we should see: 161 162``` 163Oops! 164Warning: Undefined variable $a in example on line 1 165NULL 166``` 167
