API
The mysqlnd plugin API
The mysqlnd plugin API
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:
-
A plugin manager
-
A plugin API
-
Application services (or modules)
-
Application service APIs (or module APIs)
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.
Extension | mysqlnd.query() pointer | call stack if calling parent |
---|---|---|
ext/mysqlnd | mysqlnd.query() | mysqlnd.query |
ext/mysqlnd_cache | mysqlnd_cache.query() |
|
ext/mysqlnd_monitor | mysqlnd_monitor.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.