Core PHP

API functions within the PHP Core are always available without the need for additional include files. Some of these methods provide unique functionality, while others simply serve as PHPized mappings to underlying Zend API functions.

Output

int php_printf(const char *format, ...);
int php_write(void *buf, uint size TSRMLS_DC);
int PHPWRITE(void *buf, uint size);
void php_html_puts(const char *buf, uint size TSRMLS_DC)

Generates output. These three methodsPHPWRITE() being identical to php_write()pump data into the current output buffer. The last version of these methods, php_html_puts(), performs additional work by escaping HTML entities and encoding other special characters such as tabs and newlines to ensure that non-HTML formatted data looks consistent when used with HTML-driven SAPIs.

Argument	Purpose
buf	Pointer to arbitrary data to be output
size	Length of data pointed to by buf measured in bytes
format	sprintf() style formatting string

Arguments	Purpose
...	Type-specific arguments corresponding to the format specifier

int php_start_ob_buffer(zval *output_handler, uint chunk_size,
 zend_bool erase TSRMLS_DC);
int php_start_ob_buffer_named(const char *handler_name,
 uint chunk_size, zend_bool erase TSRMLS_DC);

Initializes a new output buffer. Note that output buffers can be stacked; therefore any data produced by this new output buffer will be re-buffered by any previously initialized output buffer. These methods have the same meaning and use as their userspace counterpart: ob_start().

Argument	Purpose
output_handler	Universal callback value. Name of the function or method to be invoked with a single IS_STRING parameter when output is generated for this buffer. This callback function does not need to handle the actual work of buffering; it's just an opportunity to modify content prior to display. The callback should return an IS_STRING value.
chunk_size	Size of buffer chucks to use, in bytes.
erase	Set to a nonzero value if the buffers should be erased as they are consumed.
handler_name	php_start_ob_buffer_named() is a convenience wrapper that loads handler_name into a zval and then dispatches to php_start_ob_buffer() with all other arguments unmodified.

void php_end_ob_buffer(zend_bool send_buffer,
 zend_bool just_flush TSRMLS_DC);

Terminates or flushes the active output buffer. Despite the name, this function will not necessarily bring the current output buffer to an end.

Argument	Purpose
send_buffer	Pass the contents of the current buffer to the next buffer down, ultimately resulting in output.
just_flush	If set to a nonzero value, the current output buffer will remain in place ready to process additional data; otherwise it will terminate and the next lower output buffer will become active.

void php_end_ob_buffers(zend_bool send_buffer TSRMLS_DC);

Ends all output buffering, optionally discarding still-buffered data on the way if send_buffer is set to zero. When this method has finished, no output buffer will be active and all further output will go directly to the SAPI's output mechanism.

int php_ob_get_buffer(zval *p TSRMLS_DC);
int php_ob_get_length(zval *p TSRMLS_DC);

Copies the contents of the currently buffered dataor length thereofinto an allocated, but uninitialized zval. Note that this operation does not consume the contents of the buffer; it simply makes a passive copy.

void php_start_implicit_flush(TSRMLS_D);
void php_end_implicit_flush(TSRMLS_D);

Toggles implicit flush mode. Calling php_start_implicit_flush() is equivalent to setting implicit_flush in php.ini.

const char *php_get_output_start_filename(TSRMLS_D);
int php_get_output_start_lineno(TSRMLS_D);

Retrieves the filename and line number where the current request began outputting non-header data. This is typically used in error messages when attempting to use the userspace header() function after already starting body output, but might be invoked by extensions or SAPIs to perform other tasks

Error Reporting

void php_set_error_handling(error_handling_t error_handling,
 zend_class_entry *exception_class TSRMLS_DC)

Switches the current error handling mode. By default, all internally generated errors are raised as traditional, non-exception errors. Calling this method with EH_THROW will cause noncritical errors (E_CORE_ERROR, E_COMPILE_ERROR, E_PARSE) and nontrivial errors (E_NOTICE, E_USER_NOTICE), to be thrown as instances of the specified exception class instead.

Argument	Purpose
error_handling	One of the three error handling constants: EH_NORMAL, EH_SUPRESS, or EH_THROW.
exception_class	Specific exception class to instantiate as an error exception when a throwable error occurs. Typically zend_get_error_exception().

void php_log_err(char *log_message TSRMLS_DC);

Sends an error message to the PHP error logging facility. This message will be appended to the logfile specified in php.ini, or shuttled to the SAPI's log_message callback as discussed in Chapter 20, "Advanced Embedding."

void php_error(int type, const char *format, ...);
void php_error_docref(const char *docref TSRMLS_DC,
 int type, const char *format, ...);
void php_error_docref0(const char *docref TSRMLS_DC,
 int type, const char *format, ...);
void php_error_docref1(const char *docref TSRMLS_DC, const char *param1,
 int type, const char *format, ...);
void php_error_docref2(const char *docref TSRMLS_DC,
 const char *param1, const char *param2,
 int type, const char *format, ...);
void php_verror(const char *docref, const char *params,
 int type, const char *format, va_list args TSRMLS_DC) ;

Produces a standard PHP error message. Note that all forms of this method ultimately dispatch via php_verror().

Arguments	Purpose
docref	Manual section fragment, or full URL where help on the error topic can be found. For example, if the error being thrown relates to the core function mysql_connect(), specify a docref of function.mysql-connect. For third-party extensions, use a complete URL such as http://myext.example.com/doc/myext_foo.html.
params	Comma-separated list of parameters as they were passed to the function. Take care not to reveal sensitive information as the error might be displayed in a browser.
param1,param2	In methods that expect these parameters, they will be concatenated together with a comma to form a single parameter list that is then passed on to php_verror() as the params argument.
type	Type of error being raised. Can be any of the E_* constants. Typically set to one of: E_ERROR, E_WARNING, or E_NOTICE.
format	sprintf() style format specifier.
...	Variable argument list corresponding to the type specifiers given by format.
args	Compiled variable argument object as produced by va_start().

 

Startup, Shutdown, and Execution

int php_request_startup(TSRMLS_D);
void php_request_shutdown(void *dummy);

Startup or shutdown a script request. This will almost exclusively be done by a SAPI or host application using the embed SAPI. The dummy parameter is completely unused and might be passed a NULL value.

int php_register_extensions(zend_module_entry **list, int count TSRMLS_DC);
int php_register_extension(zend_module_entry *ptr);

Registers one or more additional extensions manually.

Argument	Purpose
count	Number of extensions to register
list	Vector of count extension entries
ptr	Pointer to a single zend_module_entry struct, provided as a convenience wrapper for initializing a single extension at a time

int php_execute_script(zend_file_handle *primary_file TSRMLS_DC);
int php_lint_script(zend_file_handle *file TSRMLS_DC);

Compiles and (optionally) execute a script file. Both methods process the named script through the lexer to produce tokens, and assemble those tokens into opcodes using the parser. Only php_execute_script() however, dispatches the compiled opcodes to the executor. Refer to Chapter 19, "Setting Up a Host Environment," for details on how to populate a zend_file_handle structure.

Note

As a side effect of compilation, any functions or classes contained in the target file will be loaded into the current process space, even if the compiled file is not executed. Appendix C, "Extending and Embedding Cookbook," shows an example of how to overcome this typically undesired behavior.

 

Safe Mode and Open Basedir

char *php_get_current_user(void);

Resolves the name of the owner of the currently running script.

int php_checkuid(const char *filename, char *fopen_mode, int check_mode);
int php_checkuid_ex(const char *filename, char *fopen_mode,
 int check_mode, int flags);

Applies safe_mode restrictions to the named file to ensure that the owner of the currently running script has the rights to access the filename.

Argument	Purpose
filename	Filename to check safe_mode access right to
fopen_mode	How the calling scope plans to subsequently open the file, if other access checks succeed
check_mode	Exactly one of the following: CHECKUID_DISALLOW_FILE_NOT_EXISTS, CHECKUID_ALLOW_FILE_NOT_EXISTS, CHECKUID_CHECK_FILE_AND_DIR, CHECKUID_ALLOW_ONLY_DIR, CHECKUID_CHECK_MODE_PARAM, or CHECKUID_ALLOW_ONLY_FILE
flags	Can optionally be set to CHECKUID_NO_ERRORS to prevent the raising of php_error() messages

int php_check_open_basedir(const char *path TSRMLS_DC);
int php_check_open_basedir_ex(const char *path, int warn TSRMLS_DC);

Checks that the file referred to by path is within the allowed path specified by the php.ini option open_basedir. If warn is set to a nonzero value, a php_error() will be raised in the event that path is not within an allowed base directory. php_check_open_basedir() is a convenience wrapper for calling php_check_open_basedir_ex() with warn set to 1. These methods return zero if the file is in a permissible location, or nonzero if access is prohibited by php.ini settings.

String Formatting

int spprintf( char **pbuf, size_t max_len, const char *format, ...);
int vspprintf(char **pbuf, size_t max_len, const char *format, va_list ap);

Similar to snprintf() and vsnprintf(), with the exception that these methods handle allocating a non-persistent buffer of an appropriate size. Remember to either assign these strings to a zval, or manually free them using PHP's efree() deallocator in order to avoid leaks. Refer to the string handling section in the Extension APIs later in this chapter for more string manipulation functions.

Reentrancy Safety

struct tm *php_localtime_r(const time_t *const timep, struct tm *p_tm);
char *php_ctime_r(const time_t *clock, char *buf);
char *php_asctime_r(const struct tm *tm, char *buf);
struct tm *php_gmtime_r(const time_t *const timep, struct tm *p_tm);
int php_rand_r(unsigned int *seed);
char *php_strtok_r(char *s, const char *delim, char **last);

These functions follow the prototype of their POSIX counterparts with added reentrancy safety. Use of these variants is always recommended in the interest of maintaining thread safety. Refer to their man pages for the meaning and purpose of their fields.

Miscellaneous

int php_register_info_logo(char *logo_string, char *mimetype,
 unsigned char *data, int size);
int php_unregister_info_logo(char *logo_string);

These two methods allow an extension or SAPI to declare a logo or "Easter egg" content. When a PHP page is requested from a server that has the expose_php option enabled, where the query string is =logo_string, the content pointed to by data will be served up rather than the otherwise requested page. This is the mechanism used by the PHP Credits page (logo_string=PHPB8B5F2A0-3C92-11d3-A3A9-4C7B08C10000), the Easter Egg image (logo_string=PHPE9568F36-D428-11d2-A769-00AA001ACF42), and a collection of other embedded content.

Argument	Purpose
logo_string	Unique label for this special content. Traditionally, this is a GUID, though any unique string will work.
mimetype	Mime-type string to be sent as a header when outputting data.
data	The arbitrary data associated with logo_string. Note that data is not copied by the registration process, only the pointer to its location; therefore this pointer must remain valid until PHP shuts down or the logo_string identifier is unregistered.
size	Size of content pointed to by data in bytes.

void php_add_tick_function(void (*func)(int));
void php_remove_tick_function(void (*func)(int));

Adds or removes a tick function to be used with the userspace directive declare(ticks=count). Note that multiple tick handlers can be registered and will be called in the order they were added.