Symisc PH7 Engine
An Embeddable PHP5 Engine

PH7 C/C++ API Reference - List Of Objects.

This is a list of all abstract objects and datatypes used by the PH7 library. There are seven objects in total, but the two most important objects are: An engine handle ph7 and a virtual machine object ph7_vm.


ph7

ph7_vm

ph7_value

ph7_context

ph7_int64

ph7_io_stream

ph7_vfs


PH7 Engine Handle

typedef struct ph7 ph7;


Each active PH7 engine is represented by a pointer to an instance of the opaque structure named "ph7". It is useful to think of an ph7 pointer as an object. The ph7_init() interface is its constructor and ph7_release() is its destructor. There is also the ph7_config() interface which is used to configure a working ph7 engine and the most important interfaces are the compile interfaces: ph7_compile(), ph7_compile_v2() and ph7_compile_file(). That is, these interfaces takes as their input a PHP program to compile and produce PH7 bytecode program represented by an opaque pointer to the ph7_vm structure (see below for more information on this structure).

PH7 Virtual Machine Object

typedef struct ph7_vm ph7_vm;


An instance of this object represents a compiled PHP program. this structure hold the PH7 bytecode program resulting from successful compilation of the target PHP script using one of the ph7_compile(), ph7_compile_v2() or ph7_compile_file() interfaces.

The life of a ph7 virtual machine goes something like this:

  1. Compile your PHP script using one of the ph7_compile(), ph7_compile_v2() or ph7_compile_file() interfaces. On successful compilation, the PH7 engine will automatically create an instance of this structure (ph7_vm) and a pointer to this structure is made available to the caller.

  2. When something goes wrong while compiling the PHP script due to a compile-time error, the caller must discard this pointer and fix its erroneous PHP code. Compile-time error messages can be extracted via a call to ph7_config().

  3. Configure the virtual machine using the ph7_vm_config() interface with it's many configuration verbs, but the most important option is set via the PH7_VM_CONFIG_OUTPUT verb which is used to register a VM output consumer callback. That is, an user defined function responsible of consuming the VM output such as redirecting it [i.e: the VM output] to the standard output (STDOUT) or sending it back to the connected peer and so on.

  4. Optionally, register one or more foreign functions or constants using the ph7_create_function() or ph7_create_constant() interfaces.

  5. Execute the compiled PHP program by calling ph7_vm_exec() one or more times.

  6. Reset the virtual machine using ph7_vm_reset() then go back to step 5. Do this zero or more times.

  7. Destroy the virtual machine using ph7_vm_release().

    Dynamically Typed Value Object

    typedef struct ph7_value ph7_value;


    PH7 uses the ph7_value object to represent all values that can be stored in a PHP variable. Since PHP uses dynamic typing for the values it stores. Values stored in ph7_value objects can be integers, floating point values, strings, arrays, class instances (object in the PHP jargon) and so on.

    Internally, the PH7 virtual machine manipulates nearly all PHP values as ph7_values structures. Each ph7_value may cache multiple representations (string, integer, etc.) of the same value.

    The ph7_value object is heavily used in the interaction between the PH7 virtual machine and the host-application especially in the implementation of application-defined foreign functions and/or constant expansion callbacks.

    There are a dozens of interfaces that allow host-application to extract and manipulates ph7_value cleanly, these includes ph7_value_to_int(), ph7_value_to_string(), ph7_value_compare(), ph7_value_int64(), ph7_value_bool(), ph7_value_is_null(), ph7_value_is_float(), ph7_value_is_callable(), ph7_value_string_format() and many more. Refer to the C/C++ Interfaces documentation for additional information.

    Foreign Function Context Object

    typedef struct ph7_context ph7_context;


    The context in which a foreign function executes is stored in a ph7_context object. A pointer to a ph7_context object is always first parameter to application-defined foreign functions. The application-defined foreign function implementation will pass this pointer through into calls to dozens of interfaces, these includes ph7_result_int(), ph7_result_string(), ph7_result_value(), ph7_context_new_scalar(), ph7_context_alloc_chunk(), ph7_context_output() ph7_context_throw_error() and many more. Refer to the C/C++ Interfaces documentation for additional information.

    You can refer to the following guide for an introductory course to this interface and the foreign function mechanism in general.

    64-Bit Integer Types

    #if defined(_MSC_VER) || defined(__BORLANDC__)

    typedef signed __int64 ph7_int64;

    #else

    typedef signed long long int ph7_int64;

    #endif /* _MSC_VER */


    As an extension to the PHP programming language, PH7 introduces 64-bit integer arithmetic for all platforms. Because there is no cross-platform way to specify 64-bit integer types PH7 includes typedefs for 64-bit signed integers. The ph7_int64 type can store integer values between -9223372036854775808 and +9223372036854775807 inclusive. Some of the interface that manipulates 64-bit integers are ph7_value_int64(), ph7_result_int64(), ph7_value_to_int64().

    PH7 IO Stream

    typedef struct ph7_io_stream ph7_io_stream;

    struct ph7_io_stream

    {

       const char *zName; /* Underlying stream name [i.e: file/http/zip/php,..] */

       int iVersion; /* IO stream structure version [default 1]*/

       int (*xOpen)(const char *,int,ph7_value *,void **); /* Open handle*/

       int (*xOpenDir)(const char *,ph7_value *,void **); /* Open directory handle */

       void (*xClose)(void *); /* Close file handle */

       void (*xCloseDir)(void *); /* Close directory handle */

       ph7_int64 (*xRead)(void *,void *,ph7_int64); /* Read from the open stream */

       int (*xReadDir)(void *,ph7_context *); /* Read entry from directory handle */

       ph7_int64 (*xWrite)(void *,const void *,ph7_int64); /* Write to the open stream */

       int (*xSeek)(void *,ph7_int64,int); /* Seek on the open stream */

       int (*xLock)(void *,int); /* Lock/Unlock the open stream */

       void (*xRewindDir)(void *); /* Rewind directory handle */

       ph7_int64 (*xTell)(void *); /* Current position of the stream read/write pointer */

       int (*xTrunc)(void *,ph7_int64); /* Truncates the open stream to a given length */

       int (*xSync)(void *); /* Flush open stream data */

       int (*xStat)(void *,ph7_value *,ph7_value *); /* Stat an open stream handle */

    };


    An instance of the ph7_io_stream object defines the interface between the PH7 core and the underlying stream device.

    A stream is a smart mechanism for generalizing file, network, data compression and other IO operations which share a common set of functions using an abstracted unified interface.

    A stream device is additional code which tells the stream how to handle specific protocols/encodings. For example, the http device knows how to translate a URL into an HTTP/1.1 request for a file on a remote server. PH7 come with two built-in IO streams device. The file:// stream which perform very efficient disk IO and the php:// stream which is a special stream that allow access various I/O streams (See the PHP official documentation for more information on this stream).

    A stream is referenced as: scheme://target

    IO stream devices are registered using a call to ph7_vm_config() with a configuration verb set to PH7_VM_CONFIG_IO_STREAM.

    Currently the PH7 development team is working on the implementation of the http:// and ftp:// IO stream protocols. These devices will be available in the next release of the PH7 engine.

    Developers wishing to implement their own IO stream devices must understand and follow The PH7 IO Stream C/C++ Specification Manual.

    PH7 Virtual File Systems (VFS)

    typedef struct ph7_vfs ph7_vfs;

    struct ph7_vfs

    {

    const char *zName; /* Underlying VFS name [i.e: FreeBSD/Linux/Windows...] */

    int iVersion; /* Current VFS structure version [default 2] */

    /* Directory functions */

    int (*xChdir)(const char *); /* Change directory */

    int (*xChroot)(const char *); /* Change the root directory */

    int (*xGetcwd)(ph7_context *); /* Get the current working directory */

    int (*xMkdir)(const char *,int,int); /* Make directory */

    int (*xRmdir)(const char *); /* Remove directory */

    int (*xIsdir)(const char *); /* Tells whether the filename is a directory */

    int (*xRename)(const char *,const char *); /* Renames a file or directory */

    int (*xRealpath)(const char *,ph7_context *); /* Return canonicalized absolute pathname*/

    /* Systems functions */

    int (*xSleep)(unsigned int); /* Delay execution in microseconds */

    int (*xUnlink)(const char *); /* Deletes a file */

    int (*xFileExists)(const char *); /* Checks whether a file or directory exists */

    int (*xChmod)(const char *,int); /* Changes file mode */

    int (*xChown)(const char *,const char *); /* Changes file owner */

    int (*xChgrp)(const char *,const char *); /* Changes file group */

    ph7_int64 (*xFreeSpace)(const char *); /* Available space on filesystem or disk partition */

    ph7_int64 (*xTotalSpace)(const char *); /* Total space on filesystem or disk partition */

    ph7_int64 (*xFileSize)(const char *); /* Gets file size */

    ph7_int64 (*xFileAtime)(const char *); /* Gets last access time of file */

    ph7_int64 (*xFileMtime)(const char *); /* Gets file modification time */

    ph7_int64 (*xFileCtime)(const char *); /* Gets inode change time of file */

    int (*xStat)(const char *,ph7_value *,ph7_value *); /* Gives information about a file */

    int (*xlStat)(const char *,ph7_value *,ph7_value *); /* Gives information about a file */

    int (*xIsfile)(const char *); /* Tells whether the filename is a regular file */

    int (*xIslink)(const char *); /* Tells whether the filename is a symbolic link */

    int (*xReadable)(const char *); /* Tells whether a file exists and is readable */

    int (*xWritable)(const char *); /* Tells whether the filename is writable */

    int (*xExecutable)(const char *); /* Tells whether the filename is executable */

    int (*xFiletype)(const char *,ph7_context *); /* Gets file type [i.e: fifo,dir,file..] */

    int (*xGetenv)(const char *,ph7_context *); /* Gets the value of an environment variable */

    int (*xSetenv)(const char *,const char *); /* Sets the value of an environment

    variable */

    int (*xTouch)(const char *,ph7_int64,ph7_int64); /* Sets access and modification time

    * of file */

    int (*xMmap)(const char *,void **,ph7_int64 *); /* Read-only memory map of the whole file */

    void (*xUnmap)(void *,ph7_int64); /* Unmap a memory view */

    int (*xLink)(const char *,const char *,int); /* Create hard or symbolic link */

    int (*xUmask)(int); /* Change the current umask */

    void (*xTempDir)(ph7_context *); /* Get path of the temporary directory */

    unsigned int (*xProcessId)(void); /* Get running process ID */

    int (*xUid)(void); /* user ID of the process */

    int (*xGid)(void); /* group ID of the process */

    void (*xUsername)(ph7_context *); /* Running username */

    int (*xExec)(const char *,ph7_context *); /* Execute an external program */

    };


    An instance of the ph7_vfs object defines the interface between the PH7 core and the underlying operating system. The "vfs" in the name of the object stands for "virtual file system". The vfs is used to implement PHP system functions such as mkdir(), chdir(), stat(), get_user_name() and many more.

    The value of the iVersion field is initially 2 but may be larger in future versions of PH7. Additional fields may be appended to this object when the iVersion value is increased.

    Only a single vfs can be registered within the PH7 core. Vfs registration is done using the ph7_lib_config() interface with a configuration verb set to PH7_LIB_CONFIG_VFS.

    Note that Windows and UNIX (Linux, FreeBSD, Solaris, MacOS X, etc.) users does not have to worry about registering and installing their own vfs, now PH7 come with a built-in vfs that implements most the methods defined above.

    Host applications running on exotic systems (ie: Other than Windows and UNIX systems) must register their own vfs in order to be able to use and call PHP system function. Also note that the ph7_compile_file() interface depends on the xMmap() method of the underlying vfs which mean that this method must be available (Always the case using the built-in VFS) in order to use this interface.

    Developers wishing to implement their own vfs must contact Symisc Systems inorder to obtain the PH7 VFS C/C++ Specification Manual.



    Symisc Systems
    Copyright © Symisc Systems