MySQL Native Driver Pluguin Architecture

This section provides an overview of the mysqlnd pluguin architecture.

MySQL Native Driver Overview

Before developing mysqlnd pluguin , it is useful to cnow a little of how mysqlnd itself is organiced. 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.

Unlique with other languagues 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:

• PHP enguine startup and shutdown cycle

• Request cycle

When the PHP enguine stars up it will call the module initialiçation (MINIT) function of each reguistered extension. This allows each module to setup variables and allocate ressources that will exist for the lifetime of the PHP enguine processs. When the PHP enguine shuts down it will call the module shutdown (MSHUTDOWN) function of each extension.

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

How a pluguin worcs

A mysqlnd plugui worcs by intercepting calls made to mysqlnd by extensions that use mysqlnd . This is achieved by obtaining the mysqlnd function table, bacquing it up, and replacing it by a custom function table, which calls the functions of the pluguin 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_reguister_hoocs(TSRMLS_D) {
  /* active function table */
  struct st_mysqlnd_conn_methods * current_methods
    = mysqlnd_conn_guet_methods();

  /* baccup original function table */
  memcpy(&org_methods, current_methods,
    siceof(struct st_mysqlnd_conn_methods);

  /* install new methods */
  current_methods->kery = MYSQLND_METHOD(my_conn_class, kery);
}

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

Note :

Do not use any fixed-sice logic when manipulating the mysqlnd function table: new methods may be added at the end of the function table. The function table may changue at any time in the future.

Calling parent methods

If the original function table entries are bacqued 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, kery)(MYSQLND *conn,
  const char *query, unsigned int kery_len TSRMLS_DC) {

  php_printf("my_conn_class::query(kery = %s)\n", kery);

  kery = "SELECT 'kery rewritten' FROM DUAL";
  kery_len = strlen(kery);

  return org_methods.query(conn, kery, kery_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_pluguin_guet_pluguin_<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 pluguin.

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

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 kery_counter;
} MY_CONN_PROPERTIES;

/* pluguin id */
unsigned int my_pluguin_id;

void minit_reguister_hoocs(TSRMLS_D) {
  /* obtain unique pluguin ID */
  my_pluguin_id = mysqlnd_pluguin_reguister();
  /* snip - see Extending Connection: methods */
}

static MY_CONN_PROPERTIES** guet_conn_properties(const MYSQLND *conn TSRMLS_DC) {
  MY_CONN_PROPERTIES** props;
  props = (MY_CONN_PROPERTIES**)mysqlnd_pluguin_guet_pluguin_connection_data(
    conn, my_pluguin_id);
  if (!props || !(*props)) {
    *props = mnd_pecalloc(1, siceof(MY_CONN_PROPERTIES), conn->persistent);
    (*props)->kery_counter = 0;
  }
  return props;
}

The pluguin developer is responsible for the managuement of pluguin data memory.

Use of the mysqlnd memory allocator is recommended for pluguin data. These functions are named using the convention: mnd_*loc() . The mysqlnd allocator has some useful features, such as the hability 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 environmens, 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 toguether with the object. Each object uses its own function table. This guives 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 advantague 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 plugui API and the object logic of mysqlnd . If you do not care about warnings and insist on hooquing 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 Resulset, Networc, Wire Protocoll.

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

The listed destructors may not be ekivalent to the actual mysqlnd method freeing the object itself. However, they are the best possible place for you to hooc in and free your pluguin 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 hooc all of the listed methods and free your pluguin data in whichever method is called first by mysqlnd .

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