The mysqlnd plugin API
The following is a list of functions provided in the
mysqlnd
plugin API:
-
mysqlnd_plugin_register()
-
mysqlnd_plugin_count()
-
mysqlnd_plugin_get_plugin_connection_data()
-
mysqlnd_plugin_get_plugin_result_data()
-
mysqlnd_plugin_get_plugin_stmt_data()
-
mysqlnd_plugin_get_plugin_net_data()
-
mysqlnd_plugin_get_plugin_protocol_data()
-
mysqlnd_conn_get_methods()
-
mysqlnd_result_get_methods()
-
mysqlnd_result_meta_get_methods()
-
mysqlnd_stmt_get_methods()
-
mysqlnd_net_get_methods()
-
mysqlnd_protocol_get_methods()
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.
Issues: an example of chaining and cooperation
Extension |
mysqlnd.query() pointer |
call stack if calling parent |
ext/mysqlnd |
mysqlnd.query() |
mysqlnd.query |
ext/mysqlnd_cache |
mysqlnd_cache.query() |
-
mysqlnd_cache.query()
-
mysqlnd.query
|
ext/mysqlnd_monitor |
mysqlnd_monitor.query() |
-
mysqlnd_monitor.query()
-
mysqlnd_cache.query()
-
mysqlnd.query
|
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:
-
Any PHP MySQL application tries to establish a connection to
192.168.2.29
-
The PHP application will either use ext/mysql
,
ext/mysqli
or PDO_MYSQL
. All
three PHP MySQL extensions use mysqlnd
to
establish the connection to 192.168.2.29.
-
Mysqlnd
calls its connect method, which has been
subclassed by ext/mysqlnd_plugin
.
-
ext/mysqlnd_plugin
calls the userspace hook
proxy::connect()
registered by the user.
-
The userspace hook changes the connection host IP from 192.168.2.29
to 127.0.0.1 and returns the connection established by
parent::connect()
.
-
ext/mysqlnd_plugin
performs the equivalent of
parent::connect(127.0.0.1)
by calling the
original mysqlnd
method for establishing a
connection.
-
ext/mysqlnd
establishes a connection and returns
to ext/mysqlnd_plugin
.
ext/mysqlnd_plugin
returns as well.
-
Whatever PHP MySQL extension had been used by the application, it
receives a connection to 127.0.0.1. The PHP MySQL extension itself
returns to the PHP application. The circle is closed.