php-doc-en/reference/mysqlnd_uh/book.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<book xml:id="book.mysqlnd-uh" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Mysqlnd user handler plugin</title>
 <titleabbrev>mysqlnd_uh</titleabbrev>

 <preface xml:id="intro.mysqlnd-uh">
  &reftitle.intro;
  <para>
   The mysqlnd user handler plugin (<literal>mysqlnd_uh</literal>)
   allows users to set hooks for most internal calls of the
   MySQL native driver for PHP
   (<literal><link linkend="book.mysqlnd">mysqlnd</link></literal>).
   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 (<link linkend="ref.mysqli">mysqli</link>,
   <link linkend="ref.mysql">mysql</link>,
   <link linkend="ref.pdo-mysql">PDO_MYSQL</link>) are compiled to
   use <literal>mysqlnd</literal> this can be used for:
   <itemizedlist>
    <listitem>
     <para>
      Monitoring
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         Queries run by any of the PHP MySQL extensions
        </para>
       </listitem>
       <listitem>
        <para>
         Prepared statements run by any of the PHP MySQL extensions
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      Auditing
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         Detection of databases uses
        </para>
       </listitem>
       <listitem>
        <para>
         SQL Injection protection using black-/whitelists
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
    <listitem>
     <para>
      Assorted
     </para>
     <para>
      <itemizedlist>
       <listitem>
        <para>
         Load Balancing connections
        </para>
       </listitem>
      </itemizedlist>
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   As of version PHP 5.3.3 the MySQL native driver for PHP
   (<literal>mysqlnd</literal>)
   features an internal plugin C API. C plugins, such as the mysqlnd
   user handler plugin, can extend the functionality of
   <link linkend="book.mysqlnd">mysqlnd</link>. PECL/mysqlnd_uh
   makes parts of the internal plugin C API available to the
   PHP user for plugin development with PHP.
  </para>
  <para>
   The MySQL native driver for PHP is a C library which ships together with
   PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
   MySQL Client Library (AKA libmysql/libmysqlclient). As of PHP 5.4.0, mysqlnd is
   the compile time default library used by all PHP MySQL extensions.
  </para>

  <section xml:id="mysqlnd-uh.security">
   <title>Security considerations</title>
   <para>
    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 <literal>PHP_INI_SYSTEM</literal> configuration setting
    <literal><link linkend="ini.mysqlnd-uh.enable">mysqlnd_uh.enable</link></literal>
    can be used to prevent users from hooking mysqlnd calls.
   </para>
   <para>
    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 <link linkend="ini.auto-prepend-file">auto_prepend_file</link>.
   </para>
  </section>

  <section xml:id="mysqlnd-uh.docs_note">
   <title>Documentation note</title>
   <para>
    Many of the extensions functions are described very briefly.
    This is done intentionally to avoid content duplication.
    The <link linkend="ref.mysqli">mysqli</link> extension is often
    only a thin abstraction layer on top of the MySQL C API, which
    the <literal>mysqlnd</literal> library provides. Therefore,
    the corresponding <link linkend="ref.mysqli">mysqli</link> documentation
    respectively the MySQL reference manual can be consulted
    to get more information on a particular function.
   </para>
  </section>

  <section xml:id="mysqlnd-uh.name">
   <title>On the name</title>
   <para>
    The shortcut <literal>mysqlnd_uh</literal> stands for
    <literal>mysqlnd user handler</literal>. There may be better names.
    However, this was the initial choice when development started.
    Meanwhile, non speaking names have almost become a tradition.
   </para>
   <note>
    <para>
     The mysqlnd user handler plugin is in alpha status.
     Take appropriate care before using it in production environments.
    </para>
   </note>
  </section>
 </preface>

 &reference.mysqlnd-uh.quickstart;
 &reference.mysqlnd-uh.setup;
 &reference.mysqlnd-uh.constants;
 &reference.mysqlnd-uh.reference;
 &reference.mysqlnd-uh.changes;

</book>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->