22.9.8. Mysqlnd user handler plugin [mysqlnd_uh]22.9.8.1. Security considerations22.9.8.2. Documentation note22.9.8.3. On the name22.9.8.4. Quickstart and Examples22.9.8.5. Installing/Configuring22.9.8.6. Predefined Constants22.9.8.7. The MysqlndUhConnection class [MysqlndUhConnection]22.9.8.8. The MysqlndUhPreparedStatement class[MysqlndUhPreparedStatement]22.9.8.9. Mysqlnd_uh Functions22.9.8.10. Change History Copyright 1997-2012 the PHP Documentation Group. The mysqlnd user handler plugin [mysqlnd_uh] allows users to set hooks for most internal
calls of the MySQL native driver for PHP [mysqlnd]. Mysqlnd and its plugins, including PECL/mysqlnd_uh, operate on a layer beneath the PHP MySQL extensions. A mysqlnd plugin can be considered as a proxy between the PHP MySQL extensions and the MySQL server as part of the PHP executable on the client-side. Because the
plugins operates on their own layer below the PHP MySQL extensions, they can monitor and change application actions without requiring application changes. If the PHP MySQL extensions [mysqli,
mysql, PDO_MYSQL] are compiled to use mysqlnd this can be used for: Monitoring
Auditing Assorted
The MySQL native driver for PHP
[mysqlnd] features an internal plugin C API. C plugins, such as the mysqlnd user handler plugin, can extend the functionality of mysqlnd.
PECL/mysqlnd_uh makes parts of the internal plugin C API available to the PHP user for plugin development with PHP. Status The mysqlnd user handler plugin is in alpha status. Take appropriate care before using it in production environments. 22.9.8.1. Security considerations
Copyright 1997-2012 the PHP Documentation Group. PECL/mysqlnd_uh gives users access to MySQL user names, MySQL password used by any of the PHP MySQL extensions to connect to MySQL. It allows monitoring of all queries and prepared statements exposing the statement string to the user. Therefore, the extension should be
installed with care. The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable can be used to prevent users from hooking mysqlnd calls. Code obfuscators and similar technologies are not suitable to prevent monitoring of mysqlnd library activities if PECL/mysqlnd_uh is made available and the user can install a proxy, for example, using auto_prepend_file. 22.9.8.2. Documentation note Copyright 1997-2012 the PHP Documentation Group. Many of the mysqlnd_uh functions are briefly
described because the mysqli extension is a thin abstraction layer on top of the MySQL C API that the mysqlnd library provides. Therefore, the corresponding
mysqli documentation [along with the MySQL reference manual] can be consulted to receive more information about a particular function. 22.9.8.3. On the name
Copyright 1997-2012 the PHP Documentation Group. The shortcut mysqlnd_uh stands for mysqlnd user handler, and has been the name since early development. 22.9.8.4. Quickstart and Examples
Copyright 1997-2012 the PHP Documentation Group. The mysqlnd user handler plugin can be understood as a client-side proxy for all PHP MySQL extensions
[mysqli, mysql,
PDO_MYSQL], if they are compiled to use the mysqlnd library. The extensions use the mysqlnd library internally, at the C level,
to communicate with the MySQL server. PECL/mysqlnd_uh allows it to hook many mysqlnd calls. Therefore, most activities of the PHP MySQL extensions can be monitored. Because monitoring happens at the level of the library, at a layer below the application, it is possible to monitor applications without changing them. On the C level, the mysqlnd library is structured in modules or classes. The extension hooks almost all methods of the mysqlnd internal connection class and exposes
them through the user space class MysqlndUhConnection. Some few methods of the mysqlnd internal statement class are made available to the PHP user with the class MysqlndUhPreparedStatement. By subclassing the classes MysqlndUhConnection and MysqlndUhPreparedStatement users get access to mysqlnd internal function calls. Note The internal mysqlnd function calls are not designed to be exposed to the PHP user. Manipulating their
activities may cause PHP to crash or leak memory. Often, this is not considered a bug. Please, keep in mind that you are accessing C library functions through PHP which are expected to take certain actions, which you may not be able to emulate in user space. Therefore, it is strongly recommended to always call the parent method implementation when subclassing MysqlndUhConnection or MysqlndUhPreparedStatement. To prevent the worst case, the extension performs some sanity checks. Please, see also
the Mysqlnd_uh Configure Options. 22.9.8.4.1. Setup
Copyright 1997-2012 the PHP Documentation Group. The plugin is implemented as a PHP extension. See the installation instructions to
install the PECL/mysqlnd_uh extension. Then, load the extension into PHP and activate the plugin in the PHP configuration file using the PHP configuration directive named mysqlnd_uh.enable. The below example shows the default settings of the extension. Example
22.316. Enabling the plugin [php.ini] mysqlnd_uh.enable=1mysqlnd_uh.report_wrong_types=1 22.9.8.4.2. How it works Copyright 1997-2012 the PHP Documentation Group. This describes the background and inner workings of the mysqlnd_uh
extension. Two classes are provided by the extension: MysqlndUhConnection and MysqlndUhPreparedStatement. MysqlndUhConnection lets you access almost all methods of the mysqlnd internal connection class. The latter exposes some selected methods of the mysqlnd internal statement class. For example,
MysqlndUhConnection::connect maps to the mysqlnd library C function mysqlnd_conn__connect. As a mysqlnd plugin, the PECL/mysqlnd_uh extension replaces mysqlnd library C functions with its own functions. Whenever a PHP MySQL extension compiled to use mysqlnd calls a mysqlnd function,
the functions installed by the plugin are executed instead of the original mysqlnd ones. For example, mysqli_connect invokes mysqlnd_conn__connect, so the connect function installed by PECL/mysqlnd_uh will be called. The functions installed by PECL/mysqlnd_uh are the methods of the built-in classes. The built-in PHP classes and
their methods do nothing but call their mysqlnd C library counterparts, to behave exactly like the original mysqlnd function they replace. The code below illustrates in pseudo-code what the extension does. Example 22.317. Pseudo-code: what a built-in class does class MysqlndUhConnection { public function connect[[$conn, $host, $user, $passwd, $db, $port, $socket, $mysql_flags] { MYSQLND* c_mysqlnd_connection = convert_from_php_to_c[$conn]; ... return call_c_function[mysqlnd_conn__connect[c_mysqlnd_connection, ...]]; }} The build-in classes behave like a transparent proxy. It is possible for you to replace the proxy with your own. This is done by subclassing MysqlndUhConnection or
MysqlndUhPreparedStatement to extend the functionality of the proxy, followed by registering a new proxy object. Proxy objects are installed by mysqlnd_uh_set_connection_proxy and
mysqlnd_uh_set_statement_proxy. Example 22.318. Installing a proxy The above example will output: proxy::connect[array [ 0 => NULL, 1 => 'localhost', 2 => 'root', 3 => '', 4 => 'test', 5 => 3306, 6 => NULL, 7 => 131072,]]proxy::connect returns true 22.9.8.4.3. Installing a
proxy Copyright 1997-2012 the PHP Documentation Group. The extension provides two built-in classes: MysqlndUhConnection and MysqlndUhPreparedStatement. The classes are used for hooking mysqlnd library calls. Their methods correspond to mysqlnd internal functions. By default they act like a transparent
proxy and do nothing but call their mysqlnd counterparts. By subclassing the classes you can install your own proxy to monitor mysqlnd. See also the How it works guide to learn about the inner workings of this extension. Connection proxies are objects of the type MysqlndUhConnection.
Connection proxy objects are installed by mysqlnd_uh_set_connection_proxy. If you install the built-in class MysqlndUhConnection as a proxy, nothing happens. It behaves like a transparent proxy. Example 22.319. Proxy registration, mysqlnd_uh.enable=1
The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable controls whether a proxy may be set. If disabled, the extension will throw errors of type E_WARNING Example 22.320. Proxy installation disabled mysqlnd_uh.enable=0 The above example will output: PHP Warning: MysqlndUhConnection::__construct[]: [Mysqlnd User Handler] The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enabled = false.You must not use any of the base classes in %s on line %dPHP Warning: mysqlnd_uh_set_connection_proxy[]: [Mysqlnd User Handler] The plugin has been disabled by setting the configuration parameter mysqlnd_uh.enable = false.The proxy has not been installed in %s on line %d To monitor mysqlnd,
you have to write your own proxy object subclassing MysqlndUhConnection. Please, see the function reference for a the list of methods that can be subclassed. Alternatively, you can use reflection to inspect the built-in MysqlndUhConnection. Create a new class proxy. Derive it from the built-in class MysqlndUhConnection. Replace the MysqlndUhConnection::connect. method. Print out the host parameter value passed to the method. Make sure that you call the parent implementation of the connect method. Failing to do so may give unexpected and undesired results, including memory leaks and crashes. Register your proxy and open three connections using the PHP MySQL extensions
mysqli, mysql,
PDO_MYSQL. If the extensions have been compiled to use the mysqlnd library, the proxy::connect method will be called three times, once for each connection opened. Example 22.321. Connection proxy
|