22.9.5.8. MySQL Native Driver Plugin API

Copyright 1997-2012 the PHP Documentation Group.

Mysqlnd plugins and MySQL Proxy are different technologies using different approaches. Both are valid tools for solving a variety of common tasks such as load balancing, monitoring, and performance enhancements. An important difference is that MySQL Proxy works with all MySQL clients, whereas mysqlnd plugins are specific to PHP applications.

As a PHP Extension, a mysqlnd plugin gets installed on the PHP application server, along with the rest of PHP. MySQL Proxy can either be run on the PHP application server or can be installed on a dedicated machine to handle multiple PHP application servers.

Deploying MySQL Proxy on the application server has two advantages:

MySQL Proxy (and mysqlnd plugins) can solve problems easily which otherwise would have required changes to existing applications.

However, MySQL Proxy does have some disadvantages:

MySQL Proxy can be customized with C and Lua programming. Lua is the preferred scripting language of MySQL Proxy. For most PHP experts Lua is a new language to learn. A mysqlnd plugin can be written in C. It is also possible to write plugins in PHP using PECL/mysqlnd_uh.

MySQL Proxy runs as a daemon - a background process. MySQL Proxy can recall earlier decisions, as all state can be retained. However, a mysqlnd plugin is bound to the request-based lifecycle of PHP. MySQL Proxy can also share one-time computed results among multiple application servers. A mysqlnd plugin would need to store data in a persistent medium to be able to do this. Another daemon would need to be used for this purpose, such as Memcache. This gives MySQL Proxy an advantage in this case.

MySQL Proxy works on top of the wire protocol. With MySQL Proxy you have to parse and reverse engineer the MySQL Client Server Protocol. Actions are limited to those that can be achieved by manipulating the communication protocol. If the wire protocol changes (which happens very rarely) MySQL Proxy scripts would need to be changed as well.

Mysqlnd plugins work on top of the C API, which mirrors the libmysqlclient client and Connector/C APIs. This C API is basically a wrapper around the MySQL Client Server protocol, or wire protocol, as it is sometimes called. You can intercept all C API calls. PHP makes use of the C API, therefore you can hook all PHP calls, without the need to program at the level of the wire protocol.

Mysqlnd implements the wire protocol. Plugins can therefore parse, reverse engineer, manipulate and even replace the communication protocol. However, this is usually not required.

As plugins allow you to create implementations that use two levels (C API and wire protocol), they have greater flexibility than MySQL Proxy. If a mysqlnd plugin is implemented using the C API, any subsequent changes to the wire protocol do not require changes to the plugin itself.

Copyright 1997-2012 the PHP Documentation Group.

The mysqlnd plugin API is simply part of the MySQL Native Driver PHP extension, ext/mysqlnd. Development started on the mysqlnd plugin API in December 2009. It is developed as part of the PHP source repository, and as such is available to the public either via Git, or through source snapshot downloads.

The following table shows PHP versions and the corresponding mysqlnd version contained within.

Plugin developers can determine the mysqlnd version through accessing MYSQLND_VERSION, which is a string of the format "mysqlnd 5.0.7-dev - 091210 - $Revision: 300535", or through MYSQLND_VERSION_ID, which is an integer such as 50007. Developers can calculate the version number as follows:

During development, developers should refer to the mysqlnd version number for compatibility and version tests, as several iterations of mysqlnd could occur during the lifetime of a PHP development branch with a single PHP version number.

Copyright 1997-2012 the PHP Documentation Group.

This section provides an overview of the mysqlnd plugin architecture.

MySQL Native Driver Overview

Before developing mysqlnd plugins, it is useful to know a little of how mysqlnd itself is organized. Mysqlnd consists of the following modules:

C Object Oriented Paradigm

At the code level, mysqlnd uses a C pattern for implementing object orientation.

In C you use a struct to represent an object. Members of the struct represent object properties. Struct members pointing to functions represent methods.

Unlike with other languages such as C++ or Java, there are no fixed rules on inheritance in the C object oriented paradigm. However, there are some conventions that need to be followed that will be discussed later.

The PHP Life Cycle

When considering the PHP life cycle there are two basic cycles:

When the PHP engine starts up it will call the module initialization (MINIT) function of each registered extension. This allows each module to setup variables and allocate resources that will exist for the lifetime of the PHP engine process. When the PHP engine shuts down it will call the module shutdown (MSHUTDOWN) function of each extension.

During the lifetime of the PHP engine it will receive a number of requests. Each request constitutes another life cycle. On each request the PHP engine will call the request initialization function of each extension. The extension can perform any variable setup and resource allocation required for request processing. As the request cycle ends the engine calls the request shutdown (RSHUTDOWN) function of each extension so the extension can perform any cleanup required.

How a plugin works

A mysqlnd plugin works by intercepting calls made to mysqlnd by extensions that use mysqlnd. This is achieved by obtaining the mysqlnd function table, backing it up, and replacing it by a custom function table, which calls the functions of the plugin as required.

The following code shows how the mysqlnd function table is replaced:

/* a place to store original function table */struct st_mysqlnd_conn_methods org_methods;void minit_register_hooks(TSRMLS_D) {  /* active function table */  struct st_mysqlnd_conn_methods * current_methods    = mysqlnd_conn_get_methods();  /* backup original function table */  memcpy(&org_methods, current_methods,    sizeof(struct st_mysqlnd_conn_methods);  /* install new methods */  current_methods->query = MYSQLND_METHOD(my_conn_class, query);}

Connection function table manipulations must be done during Module Initialization (MINIT). The function table is a global shared resource. In an multi-threaded environment, with a TSRM build, the manipulation of a global shared resource during the request processing will almost certainly result in conflicts.

Calling parent methods

If the original function table entries are backed up, it is still possible to call the original function table entries - the parent methods.

In some cases, such as for Connection::stmt_init(), it is vital to call the parent method prior to any other activity in the derived method.

MYSQLND_METHOD(my_conn_class, query)(MYSQLND *conn,  const char *query, unsigned int query_len TSRMLS_DC) {  php_printf("my_conn_class::query(query = %s)\n", query);  query = "SELECT 'query rewritten' FROM DUAL";  query_len = strlen(query);  return org_methods.query(conn, query, query_len); /* return with call to parent */}

Extending properties

A mysqlnd object is represented by a C struct. It is not possible to add a member to a C struct at run time. Users of mysqlnd objects cannot simply add properties to the objects.

Arbitrary data (properties) can be added to a mysqlnd objects using an appropriate function of the mysqlnd_plugin_get_plugin_<object>_data() family. When allocating an object mysqlnd reserves space at the end of the object to hold a void * pointer to arbitrary data. mysqlnd reserves space for one void * pointer per plugin.

The following table shows how to calculate the position of the pointer for a specific plugin:

If you plan to subclass any of the mysqlnd object constructors, which is allowed, you must keep this in mind!

The following code shows extending properties:

/* any data we want to associate */typedef struct my_conn_properties {  unsigned long query_counter;} MY_CONN_PROPERTIES;/* plugin id */unsigned int my_plugin_id;void minit_register_hooks(TSRMLS_D) {  /* obtain unique plugin ID */  my_plugin_id = mysqlnd_plugin_register();  /* snip - see Extending Connection: methods */}static MY_CONN_PROPERTIES** get_conn_properties(const MYSQLND *conn TSRMLS_DC) {  MY_CONN_PROPERTIES** props;  props = (MY_CONN_PROPERTIES**)mysqlnd_plugin_get_plugin_connection_data(    conn, my_plugin_id);  if (!props || !(*props)) {    *props = mnd_pecalloc(1, sizeof(MY_CONN_PROPERTIES), conn->persistent);    (*props)->query_counter = 0;  }  return props;}

The plugin developer is responsible for the management of plugin data memory.

Use of the mysqlnd memory allocator is recommended for plugin data. These functions are named using the convention: mnd_*loc(). The mysqlnd allocator has some useful features, such as the ability to use a debug allocator in a non-debug build.

You must not manipulate function tables at any time later than MINIT if it is not allowed according to the above table.

Some classes contain a pointer to the method function table. All instances of such a class will share the same function table. To avoid chaos, in particular in threaded environments, such function tables must only be manipulated during MINIT.

Other classes use copies of a globally shared function table. The class function table copy is created together with the object. Each object uses its own function table. This gives you two options: you can manipulate the default function table of an object at MINIT, and you can additionally refine methods of an object without impacting other instances of the same class.

The advantage of the shared function table approach is performance. There is no need to copy a function table for each and every object.

It is strongly recommended that you do not entirely replace a constructor. The constructors perform memory allocations. The memory allocations are vital for the mysqlnd plugin API and the object logic of mysqlnd. If you do not care about warnings and insist on hooking the constructors, you should at least call the parent constructor before doing anything in your constructor.

Regardless of all warnings, it can be useful to subclass constructors. Constructors are the perfect place for modifying the function tables of objects with non-shared object tables, such as Resultset, Network, Wire Protocol.

The destructors are the appropriate place to free properties, mysqlnd_plugin_get_plugin_<object>_data().

The listed destructors may not be equivalent to the actual mysqlnd method freeing the object itself. However, they are the best possible place for you to hook in and free your plugin data. As with constructors you may replace the methods entirely but this is not recommended. If multiple methods are listed in the above table you will need to hook all of the listed methods and free your plugin data in whichever method is called first by mysqlnd.

The recommended method for plugins is to simply hook the methods, free your memory and call the parent implementation immediately following this.

Copyright 1997-2012 the PHP Documentation Group.

The following is a list of functions provided in the mysqlnd plugin API:

There is no formal definition of what a plugin is and how a plugin mechanism works.

Components often found in plugins mechanisms are:

The mysqlnd plugin concept employs these features, and additionally enjoys an open architecture.

No Restrictions

A plugin has full access to the inner workings of mysqlnd. There are no security limits or restrictions. Everything can be overwritten to implement friendly or hostile algorithms. It is recommended you only deploy plugins from a trusted source.

As discussed previously, plugins can use pointers freely. These pointers are not restricted in any way, and can point into another plugin's data. Simple offset arithmetic can be used to read another plugin's data.

It is recommended that you write cooperative plugins, and that you always call the parent method. The plugins should always cooperate with mysqlnd itself.

In this scenario, a cache (ext/mysqlnd_cache) and a monitor (ext/mysqlnd_monitor) plugin are loaded. Both subclass Connection::query(). Plugin registration happens at MINIT using the logic shown previously. PHP calls extensions in alphabetical order by default. Plugins are not aware of each other and do not set extension dependencies.

By default the plugins call the parent implementation of the query method in their derived version of the method.

PHP Extension Recap

This is a recap of what happens when using an example plugin, ext/mysqlnd_plugin, which exposes the mysqlnd C plugin API to PHP:

Copyright 1997-2012 the PHP Documentation Group.

It is important to remember that a mysqlnd plugin is itself a PHP extension.

The following code shows the basic structure of the MINIT function that will be used in the typical mysqlnd plugin:

/* my_php_mysqlnd_plugin.c */ static PHP_MINIT_FUNCTION(mysqlnd_plugin) {  /* globals, ini entries, resources, classes */  /* register mysqlnd plugin */  mysqlnd_plugin_id = mysqlnd_plugin_register();  conn_m = mysqlnd_get_conn_methods();  memcpy(org_conn_m, conn_m,    sizeof(struct st_mysqlnd_conn_methods));  conn_m->query = MYSQLND_METHOD(mysqlnd_plugin_conn, query);  conn_m->connect = MYSQLND_METHOD(mysqlnd_plugin_conn, connect);}

/* my_mysqlnd_plugin.c */ enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, query)(/* ... */) {  /* ... */}enum_func_status MYSQLND_METHOD(mysqlnd_plugin_conn, connect)(/* ... */) {  /* ... */}

Task analysis: from C to userspace

 class proxy extends mysqlnd_plugin_connection {  public function connect($host, ...) { .. }}mysqlnd_plugin_set_conn_proxy(new proxy());

Process:

You need to carry out the following:

Userspace object methods can either be called using call_user_function() or you can operate at a level closer to the Zend Engine and use zend_call_method().

Optimization: calling methods from C using zend_call_method

The following code snippet shows the prototype for the zend_call_method function, taken from zend_interfaces.h.

 ZEND_API zval* zend_call_method(  zval **object_pp, zend_class_entry *obj_ce,  zend_function **fn_proxy, char *function_name,  int function_name_len, zval **retval_ptr_ptr,  int param_count, zval* arg1, zval* arg2 TSRMLS_DC);

Zend API supports only two arguments. You may need more, for example:

 enum_func_status (*func_mysqlnd_conn__connect)(  MYSQLND *conn, const char *host,  const char * user, const char * passwd,  unsigned int passwd_len, const char * db,  unsigned int db_len, unsigned int port,  const char * socket, unsigned int mysql_flags TSRMLS_DC);

To get around this problem you will need to make a copy of zend_call_method() and add a facility for additional parameters. You can do this by creating a set of MY_ZEND_CALL_METHOD_WRAPPER macros.

Calling PHP userspace

This code snippet shows the optimized method for calling a userspace function from C:

 /* my_mysqlnd_plugin.c */MYSQLND_METHOD(my_conn_class,connect)(  MYSQLND *conn, const char *host /* ... */ TSRMLS_DC) {  enum_func_status ret = FAIL;  zval * global_user_conn_proxy = fetch_userspace_proxy();  if (global_user_conn_proxy) {    /* call userspace proxy */    ret = MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, host, /*...*/);  } else {    /* or original mysqlnd method = do nothing, be transparent */    ret = org_methods.connect(conn, host, user, passwd,          passwd_len, db, db_len, port,          socket, mysql_flags TSRMLS_CC);  }  return ret;}

Calling userspace: simple arguments

/* my_mysqlnd_plugin.c */ MYSQLND_METHOD(my_conn_class,connect)(  /* ... */, const char *host, /* ...*/) {  /* ... */  if (global_user_conn_proxy) {    /* ... */    zval* zv_host;    MAKE_STD_ZVAL(zv_host);    ZVAL_STRING(zv_host, host, 1);    MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_host /*, ...*/);    zval_ptr_dtor(&zv_host);    /* ... */  }  /* ... */}

Calling userspace: structs as arguments

/* my_mysqlnd_plugin.c */MYSQLND_METHOD(my_conn_class, connect)(  MYSQLND *conn, /* ...*/) {  /* ... */  if (global_user_conn_proxy) {    /* ... */    zval* zv_conn;    ZEND_REGISTER_RESOURCE(zv_conn, (void *)conn, le_mysqlnd_plugin_conn);    MY_ZEND_CALL_METHOD_WRAPPER(global_user_conn_proxy, zv_retval, zv_conn, zv_host /*, ...*/);    zval_ptr_dtor(&zv_conn);    /* ... */  }  /* ... */}

The first argument of many mysqlnd methods is a C "object". For example, the first argument of the connect() method is a pointer to MYSQLND. The struct MYSQLND represents a mysqlnd connection object.

The mysqlnd connection object pointer can be compared to a standard I/O file handle. Like a standard I/O file handle a mysqlnd connection object shall be linked to the userspace using the PHP resource variable type.

From C to userspace and back

 class proxy extends mysqlnd_plugin_connection {  public function connect($conn, $host, ...) {    /* "pre" hook */    printf("Connecting to host = '%s'\n", $host);    debug_print_backtrace();    return parent::connect($conn);  }  public function query($conn, $query) {    /* "post" hook */    $ret = parent::query($conn, $query);    printf("Query = '%s'\n", $query);    return $ret;  }}mysqlnd_plugin_set_conn_proxy(new proxy());

PHP users must be able to call the parent implementation of an overwritten method.

As a result of subclassing it is possible to refine only selected methods and you can choose to have "pre" or "post" hooks.

Buildin class: mysqlnd_plugin_connection::connect()

/*  my_mysqlnd_plugin_classes.c */ PHP_METHOD("mysqlnd_plugin_connection", connect) {  /* ... simplified! ... */  zval* mysqlnd_rsrc;  MYSQLND* conn;  char* host; int host_len;  if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "rs",    &mysqlnd_rsrc, &host, &host_len) == FAILURE) {    RETURN_NULL();  }  ZEND_FETCH_RESOURCE(conn, MYSQLND* conn, &mysqlnd_rsrc, -1,    "Mysqlnd Connection", le_mysqlnd_plugin_conn);  if (PASS == org_methods.connect(conn, host, /* simplified! */ TSRMLS_CC))    RETVAL_TRUE;  else    RETVAL_FALSE;}