<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <title>The mysqlnd plugin API</title> </head> <body><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd.plugin.architecture.html">MySQL Native Driver Plugin Architecture</a></div> <div class="next" style="text-align: right; float: right;"><a href="mysqlnd.plugin.developing.html">Getting started building a mysqlnd plugin</a></div> <div class="up"><a href="mysqlnd.plugin.html">MySQL Native Driver Plugin API</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div><hr /><div id="mysqlnd.plugin.api" class="section"> <h2 class="title">The mysqlnd plugin API</h2> <p class="para"> The following is a list of functions provided in the <em>mysqlnd</em> plugin API: </p> <ul class="itemizedlist"> <li class="listitem"> <p class="para"> mysqlnd_plugin_register() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_count() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_get_plugin_connection_data() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_get_plugin_result_data() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_get_plugin_stmt_data() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_get_plugin_net_data() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_plugin_get_plugin_protocol_data() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_conn_get_methods() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_result_get_methods() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_result_meta_get_methods() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_stmt_get_methods() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_net_get_methods() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_protocol_get_methods() </p> </li> </ul> <p class="para"> There is no formal definition of what a plugin is and how a plugin mechanism works. </p> <p class="para"> Components often found in plugins mechanisms are: </p> <ul class="itemizedlist"> <li class="listitem"> <p class="para"> A plugin manager </p> </li> <li class="listitem"> <p class="para"> A plugin API </p> </li> <li class="listitem"> <p class="para"> Application services (or modules) </p> </li> <li class="listitem"> <p class="para"> Application service APIs (or module APIs) </p> </li> </ul> <p class="para"> The <em>mysqlnd</em> plugin concept employs these features, and additionally enjoys an open architecture. </p> <p class="para"> <em class="emphasis"> No Restrictions </em> </p> <p class="para"> A plugin has full access to the inner workings of <em>mysqlnd</em>. 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. </p> <p class="para"> 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. </p> <p class="para"> It is recommended that you write cooperative plugins, and that you always call the parent method. The plugins should always cooperate with <em>mysqlnd</em> itself. </p> <table class="doctable table"> <caption><strong>Issues: an example of chaining and cooperation</strong></caption> <tbody class="tbody"> <tr> <td>Extension</td> <td>mysqlnd.query() pointer</td> <td>call stack if calling parent</td> </tr> <tr> <td>ext/mysqlnd</td> <td>mysqlnd.query()</td> <td>mysqlnd.query</td> </tr> <tr> <td>ext/mysqlnd_cache</td> <td>mysqlnd_cache.query()</td> <td><ol type="1"> <li class="listitem"> <p class="para"> mysqlnd_cache.query() </p> </li> <li class="listitem"> <p class="para"> mysqlnd.query </p> </li> </ol></td> </tr> <tr> <td>ext/mysqlnd_monitor</td> <td>mysqlnd_monitor.query()</td> <td><ol type="1"> <li class="listitem"> <p class="para"> mysqlnd_monitor.query() </p> </li> <li class="listitem"> <p class="para"> mysqlnd_cache.query() </p> </li> <li class="listitem"> <p class="para"> mysqlnd.query </p> </li> </ol></td> </tr> </tbody> </table> <p class="para"> In this scenario, a cache (<em>ext/mysqlnd_cache</em>) and a monitor (<em>ext/mysqlnd_monitor</em>) plugin are loaded. Both subclass <em>Connection::query()</em>. Plugin registration happens at <em>MINIT</em> 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. </p> <p class="para"> By default the plugins call the parent implementation of the query method in their derived version of the method. </p> <p class="para"> <em class="emphasis"> PHP Extension Recap </em> </p> <p class="para"> This is a recap of what happens when using an example plugin, <em>ext/mysqlnd_plugin</em>, which exposes the <em>mysqlnd</em> C plugin API to PHP: </p> <ul class="itemizedlist"> <li class="listitem"> <p class="para"> Any PHP MySQL application tries to establish a connection to 192.168.2.29 </p> </li> <li class="listitem"> <p class="para"> The PHP application will either use <em>ext/mysql</em>, <em>ext/mysqli</em> or <em>PDO_MYSQL</em>. All three PHP MySQL extensions use <em>mysqlnd</em> to establish the connection to 192.168.2.29. </p> </li> <li class="listitem"> <p class="para"> <em>Mysqlnd</em> calls its connect method, which has been subclassed by <em>ext/mysqlnd_plugin</em>. </p> </li> <li class="listitem"> <p class="para"> <em>ext/mysqlnd_plugin</em> calls the userspace hook <em>proxy::connect()</em> registered by the user. </p> </li> <li class="listitem"> <p class="para"> The userspace hook changes the connection host IP from 192.168.2.29 to 127.0.0.1 and returns the connection established by <em>parent::connect()</em>. </p> </li> <li class="listitem"> <p class="para"> <em>ext/mysqlnd_plugin</em> performs the equivalent of <em>parent::connect(127.0.0.1)</em> by calling the original <em>mysqlnd</em> method for establishing a connection. </p> </li> <li class="listitem"> <p class="para"> <em>ext/mysqlnd</em> establishes a connection and returns to <em>ext/mysqlnd_plugin</em>. <em>ext/mysqlnd_plugin</em> returns as well. </p> </li> <li class="listitem"> <p class="para"> 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. </p> </li> </ul> </div><hr /><div class="manualnavbar" style="text-align: center;"> <div class="prev" style="text-align: left; float: left;"><a href="mysqlnd.plugin.architecture.html">MySQL Native Driver Plugin Architecture</a></div> <div class="next" style="text-align: right; float: right;"><a href="mysqlnd.plugin.developing.html">Getting started building a mysqlnd plugin</a></div> <div class="up"><a href="mysqlnd.plugin.html">MySQL Native Driver Plugin API</a></div> <div class="home"><a href="index.html">PHP Manual</a></div> </div></body></html>