sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 00:48:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add mysqlnd_memcache docs

Browse source 
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@328533 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Johannes Schlüter 2012-11-28 14:56:42 +00:00
parent 4ebdfbb9b7
commit 7a0bf3ddab
14 changed files with 1256 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
reference/mysqlinfo/set.xml
View file

@ -503,5 +503,6 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
&reference.mysqlnd-qc.book;
&reference.mysqlnd-uh.book;
&reference.mysqlnd-mux.book;
&reference.mysqlnd-memcache.book;
</set>

150
reference/mysqlnd_memcache/book.xml Normal file
View file

@ -0,0 +1,150 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 326346 $ -->
<book xml:id="book.mysqlnd-memcache" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mysqlnd Memache plugin</title>
<titleabbrev>mysqlnd_memcache</titleabbrev>
<preface xml:id="intro.mysqlnd-memcache">
&reftitle.intro;
<para>
The mysqlnd memcache plugin (<literal>mysqlnd_memcache</literal>) is an PHP
extension for transparently translating SQL into requests for the
MySQL InnoDB Memcached Daemon Plugin (server plugin). It includes
experimental support for the MySQL Cluster Memcached Daemon. The server
plugin provides access to data stored inside MySQL InnoDB (respectively
MySQL Cluster NDB) tables using the Memcache protocol.
This PHP extension, which supports all PHP MySQL extensions that use
<link linkend="book.mysqlnd">mysqlnd</link>, will identify tables exported in
this way and will translate specific SELECT queries into Memcache requests.
</para>
<mediaobject>
<alt>mysqlnd_memcache data flow</alt>
<imageobject>
<imagedata fileref="en/reference/mysqlnd_memcache/figures/mymemflow.png"/>
</imageobject>
</mediaobject>
<note>
<para>
This plugin depends on the MySQL InnoDB Memcached Daemon Plugin. It is not
provided to be used with a stand-alone Memcached. For a generic query cache
using Memcached look at the <link linkend="book.mysqlnd-qc">mysqlnd query
cache plugin</link>. For direct Memcache access look at the
<link linkend="book.memcache">memcache</link> and
<link linkend="book.memcached">memcached</link> extensions.
</para>
</note>
<para>
The MySQL native driver for PHP is a C library that ships together with
PHP as of PHP 5.3.0. It serves as a drop-in replacement for the
MySQL Client Library (libmysql/libmysqlclient). Using mysqlnd has
several advantages: no extra downloads are required because it's bundled with PHP,
it's under the PHP license, there is lower memory consumption in certain cases, and
it contains new functionality such as asynchronous queries.
</para>
<para>
The <literal>mysqlnd_mmemcache</literal> operates, for the most part,
transparently from a user perspective. The mysqlnd memcache
plugin supports all PHP applications, and all MySQL PHP extensions.
It does not change existing APIs. Therefore, it can easily be used with
existing PHP applications.
</para>
<para>
The MySQL Memcache plugins add key-value style access method for data stored
in InnoDB resp. NDB (MySQL Cluster) SQL tables through the Memcache protocol.
This type of key-value access if often faster than using SQL.
</para>
<section xml:id="mysqlnd-memcache.key-features">
<title>Key Features</title>
<para>
The key features of PECL/mysqlnd_memcache are as follows.
</para>
<para>
<itemizedlist>
<listitem>
<para>
Possible performance benefits
</para>
<para>
<itemizedlist>
<listitem>
<para>
Client-side: light-weight protocol.
</para>
</listitem>
<listitem>
<para>
Server-side: no SQL parsing, direct access to the storage.
</para>
</listitem>
<listitem>
<para>
Please, run your own benchmarks! Actual performance results are
highly dependent on setup and hardware used.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="mysqlnd-memcache.limitations">
<title>Limitations</title>
<para>
The initial version is not binary safe. Due to the way the MySQL Memcache
plugins works there are restrictions related to separators.
</para>
<para>
Prepared statements and asynchronous queries are not supported. Result set
meta data support is limited.
</para>
<para>
The mapping information for tables accessible via Memcache is not cached
in the plugin between requests but fetched from the MySQL server each time
a MySQL connection is associated with a Memcache connection. See
<function>mysqlnd_memcache_set</function> for details.
</para>
</section>
<section xml:id="mysqlnd-memcache.name">
<title>On the name</title>
<para>
The shortcut <literal>mysqlnd_memcache</literal>
stands for <literal>mysqlnd memcache plugin</literal>.
Memcache refers to support of the MySQL Memcache plugins
for InnoDB and NDB (MySQL Cluster). The plugin is not
related to the Memcached cache server.
</para>
</section>
</preface>
&reference.mysqlnd-memcache.quickstart;
&reference.mysqlnd-memcache.setup;
&reference.mysqlnd-memcache.constants;
&reference.mysqlnd-memcache.reference;
&reference.mysqlnd-memcache.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
-->

61
reference/mysqlnd_memcache/changes.xml Normal file
View file

@ -0,0 +1,61 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 326962 $ -->
<chapter xml:id="mysqlnd-memcache.changes" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title xmlns="http://docbook.org/ns/docbook">Change History</title>
<para>
This change history is a high level summary of selected changes
that may impact applications and/or break backwards compatibility.
</para>
<para>
See also the <filename>CHANGES</filename> file in the source distribution
for a complete list of changes.
</para>
<section xml:id="mysqlnd-memcache.changes-one-o">
<title xmlns="http://docbook.org/ns/docbook">PECL/mysqlnd_memcache 1.0 series</title>
<para>
1.0.0-alpha
<itemizedlist>
<listitem>
<simpara>
Release date: TBD
</simpara>
</listitem>
<listitem>
<simpara>
Motto/theme: Basic mapping of SQL SELECT to a MySQL Memcache plugin access.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
The initial release does map basic SQL SELECT statements to a MySQL Memcache plugin
access. This bares potential performance benefits as the direct
key-value access to MySQL storage using the Memcache protocol is usually
faster than using SQL access.
</para>
</section>
</chapter>
<!-- 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
-->

42
reference/mysqlnd_memcache/configure.xml Normal file
View file

@ -0,0 +1,42 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 321157 $ -->
<section xml:id="mysqlnd-memcache.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.install;
<para>
&pecl.moved;
</para>
<para>
&pecl.info;
<link xlink:href="&url.pecl.package;mysqlnd_memcache">&url.pecl.package;mysqlnd_memcache</link>
</para>
<para>
&pecl.windows.download;
</para>
</section>
<!-- 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
-->

123
reference/mysqlnd_memcache/constants.xml Normal file
View file

@ -0,0 +1,123 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 325341 $ -->
<appendix xml:id="mysqlnd-memcache.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.constants;
&extension.constants;
<para>
<emphasis role="bold">MySQL Memcache Plugin related</emphasis>
</para>
<para>
<variablelist>
<varlistentry xml:id="constant.mysqlnd-memcache-default-regexp">
<term>
<constant>MYSQLND_MEMCACHE_DEFAULT_REGEXP</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Default regular expression (pcre style) used for matching <literal>SELECT</literal>
statements that shall be mapped into a MySQL Memcache Plugin
access, if possible.
</simpara>
<simpara>
It is possible to use a different but the defailt regular expression for pattern
matching. See also <function>mysqlnd_memcache_set</function>.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
<emphasis role="bold">Assorted</emphasis>
</para>
<para>
The plugins version number can be obtained using
<constant>MYSQLND_MEMCACHE_VERSION</constant> or
<constant>MYSQLND_MEMCACHE_VERSION_ID</constant>.
<constant>MYSQLND_MEMCACHE_VERSION</constant>
is the string representation of the numerical version number
<constant>MYSQLND_MEMCACHE_VERSION_ID</constant>, which is an integer such as 10000.
Developers can calculate the version number as follows.
</para>
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Version (part)</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>Major*10000</entry>
<entry>1*10000 = 10000</entry>
</row>
<row>
<entry>Minor*100</entry>
<entry>0*100 = 0</entry>
</row>
<row>
<entry>Patch</entry>
<entry>0 = 0</entry>
</row>
<row>
<entry>MYSQLND_MEMCACHE_VERSION_ID</entry>
<entry>10000</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
<para>
<variablelist>
<varlistentry xml:id="constant.mysqlnd-memcache-version">
<term>
<constant>MYSQLND_MEMCACHE_VERSION</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Plugin version string, for example, <quote>1.0.0-alpha</quote>.
</simpara>
</listitem>
</varlistentry>
<varlistentry xml:id="constant.mysqlnd-memcache-version-id">
<term>
<constant>MYSQLND_MEMCACHE_VERSION_ID</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
Plugin version number, for example, 10000.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>
<!-- 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
-->

32
reference/mysqlnd_memcache/figures/mymemflow.dot Normal file
View file

@ -0,0 +1,32 @@
/*
Render using
$ dot -Tpng -ofigures/mymemflow.png figures/mymemflow.dot
*/
graph mymemflow {
rankdir=LR
node [shape=box]
subgraph clusterPHP {
rankdir=LR
label="PHP"
extmysql [label="ext/mysql"]
extmysql -- mysqlnd_memcache
mysqli -- mysqlnd_memcache
pdo -- mysqlnd_memcache
subgraph clusterMysqlnd {
label=mysqlnd
mysqlnd_memcache [color=blue]
}
}
subgraph clusterMySQL {
label="MySQL Server"
color=black
sqlengine [label="SQL Engine"]
innoplugin [label="InnoDB Memcache Daemon" color=blue]
}
mysqlnd_memcache -- innoplugin [label="memcache protocol" color=blue]
mysqlnd_memcache -- sqlengine [label="MySQL Protocol"]
}

BIN
reference/mysqlnd_memcache/figures/mymemflow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 9.2 KiB

272
reference/mysqlnd_memcache/functions/mysqlnd-memcache-get-config.xml Normal file
View file

@ -0,0 +1,272 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 322131 $ -->
<refentry xml:id="function.mysqlnd-memcache-get-config" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_memcache_get_config</refname>
<refpurpose>Returns information about the plugin configuration</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type>
<methodname>mysqlnd_memcache_get_config</methodname>
<methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
</methodsynopsis>
<para>
This function returns an array containing all the mysqlnd_memcache related
configuration attached to a MySQL connection. This includes MySQL the
Memcache object provided via <function>mysqlnd_memcache_set</function>
as well as the table mapping configuration which was automatically collected
from the MySQL server.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
A handle to a MySQL server of the type
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>, <link linkend="book.mysqli">mysqli</link> or
<link linkend="book.mysql">ext/mysql</link> for which the configuration is to
be returned.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the connection is associated with a memcache connection an array will
be returned. Otherwise this function will return <literal>false</literal>.
</para>
<para>
The returned array has these elements:
</para>
<para>
<table>
<title>mysqlnd_memcache_get_config array structure</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Key</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>memcached</entry>
<entry>
Instance of Memcached associated to this MySQL connection
by <methodname>mysqlnd_memcache_set</methodname>. You can use this to
change settings of the memcache connection or directly querying the
server onthis connection.
</entry>
</row>
<row>
<entry>pattern</entry>
<entry>
Regular expression used to match an SQL query being sent to the server.
Queries matching this pattern will be further analyzed to decide whether
the query can be intercepted and sent via the memcache interface or
whether the query is sent using the general MySQL protocol to the
server. The pattern either is the default pattern,
<literal>MYSQLND_MEMCACHE_DEFAULT_REGEXP</literal> or set via
<methodname>mysqlnd_memcache_set</methodname>.
</entry>
</row>
<row>
<entry>mappings</entry>
<entry>
An associative array with a list of all configured containers as they
were discovered by this plugin. The key for these elements is the name
of the container in the MySQL configuration. The value is described
below. The contents of this field is created by querying the MySQL
server during associting a MySQL and a memcache connection using
<methodname>mysqlnd_memcache_set</methodname>.
</entry>
</row>
<row>
<entry>mapping_query</entry>
<entry>An SQL query used during
<methodname>mysqlnd_memcache_set</methodname>
to identify the available containers and mappings. The result of that
query is provided in the mappings element.
</entry>
</row>
</tbody>
</tgroup>
</table>
<table>
<title>Mapping entry structure</title>
<tgroup cols="2">
<thead>
<row>
<entry>Array Key</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>prefix</entry>
<entry>
A prefix used while accessing data via memcache. With the MySQL InnoDB
Memcache Deamon plugin this usully begins with @@ and ends with a
configurable separator. This prefix is placed in front of the key value
while using the memcache protocol.
</entry>
</row>
<row>
<entry>schema_name</entry>
<entry>
Name of the schema (database) which contains the table being accessed.
</entry>
</row>
<row>
<entry>table_name</entry>
<entry>
Name of the table which contins the data accessible via memcache
protocol.
</entry>
</row>
<row>
<entry>id_field_name</entry>
<entry>
Name of the database field (column) with the id used as key when
accessing the table vi a memcache. Often this is the database field
having a primary key.
</entry>
</row>
<row>
<entry>separator</entry>
<entry>
A seprator used to split different field values. This is needed as
memcache only provides access to a single value while MySQL can map
multiple columns to this value.
<note>
<para>
The separator, which can be set in the MySQL Server configuration
should not be part ofany value retrieved via memcache as proper
mapping can't be guranteed.
</para>
</note>
</entry>
</row>
<row>
<entry>fields</entry>
<entry>
An array with the names of all fields availle forthis mapping.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysqlnd_memcache_get_config</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc);
var_dump(mysqlnd_memcache_get_config($mysqli));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(4) {
["memcached"]=>
object(Memcached)#2 (0) {
}
["pattern"]=>
string(125) "/^\s*SELECT\s*(.+?)\s*FROM\s*`?([a-z0-9_]+)`?\s*WHERE\s*`?([a-z0-9_]+)`?\s*=\s*(?(?=["'])["']([^"']*)["']|([0-9e\.]*))\s*$/is"
["mappings"]=>
array(1) {
["mymem_test"]=>
array(6) {
["prefix"]=>
string(13) "@@mymem_test."
["schema_name"]=>
string(4) "test"
["table_name"]=>
string(10) "mymem_test"
["id_field_name"]=>
string(2) "id"
["separator"]=>
string(1) "|"
["fields"]=>
array(3) {
[0]=>
string(2) "f1"
[1]=>
string(2) "f2"
[2]=>
string(2) "f3"
}
}
}
["mapping_query"]=>
string(209) " SELECT c.name,
CONCAT('@@', c.name, (SELECT value FROM innodb_memcache.config_options WHERE name = 'table_map_delimiter')) AS key_prefix,
c.db_schema,
c.db_table,
c.key_columns,
c.value_columns,
(SELECT value FROM innodb_memcache.config_options WHERE name = 'separator') AS sep
FROM innodb_memcache.containers c"
}
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<methodname>mysqlnd_memcache_set</methodname>
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

175
reference/mysqlnd_memcache/functions/mysqlnd-memcache-set.xml Normal file
View file

@ -0,0 +1,175 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 322131 $ -->
<refentry xml:id="function.mysqlnd-memcache-set" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_memcache_set</refname>
<refpurpose>Associate a MySQL connection with a Memcache connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_memcache_set</methodname>
<methodparam><type>mixed</type><parameter>mysql_connection</parameter></methodparam>
<methodparam choice="opt"><type>Memcached</type><parameter>memcache_connection</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter>pattern</parameter></methodparam>
<methodparam choice="opt"><type>callback</type><parameter>callback</parameter></methodparam>
</methodsynopsis>
<para>
Associate <parameter>mysql_connection</parameter> with
<parameter>memcache_connection</parameter> using <parameter>pattern</parameter>
as decision Regexp and <parameter>callback</parameter> as notification
callback or unset the association of <parameter>mysql_connection</parameter>.
</para>
<para>
While associating a MySQL connection with a Memcache connection this function
will query the MySQL server for its configuration. It will automatically
detect whether the server is configured to use the InnoDB Memcache Daemon
Plugin or MySQL Cluster NDB Memcache support. It will also query the server
to automatically identify exported tables and other configuration options.
The results of this automatic configuration can be retrieved using
<function>mysqlnd_memcache_get_config</function>.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>mysql_connection</parameter></term>
<listitem>
<para>
A handle to a MySQL server of the type
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>, <link linkend="book.mysqli">mysqli</link> or
<link linkend="book.mysql">ext/mysql</link> for which the configuration is to
be set.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>memcache_connection</parameter></term>
<listitem>
<para>
A <link linkend="book.memcached">Memcached</link> instance with an
connection to the MySQL Memcache Daemon plugin. If this parameter
is ommitted <parameter>mysql_connection</parameter> will be unassociated
from any memcache connection. If a previous association exists it will be
replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>pattern</parameter></term>
<listitem>
<para>
A regular expression in <link linkend="book.pcre">Perl Compatible
Regular Expression</link> syntax used to identify potential
Memcache-queries. The query should have three sub patterns. The
first subpattern contains the requested field list, the second the name
of the ID column from the query and the third the requested value. If
this parameteris ommitted or set to &null; a default
pattern will be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>callback</parameter></term>
<listitem>
<para>
A callback which will be used whenever a query is being sent to
MySQL. The callback will receive a single &boolean; parameter
telling if a query was sent via Memcache.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If the association or disassociation succeds the function returns &true;. In
case of an error &false; is being returned.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>
<function>mysqlnd_memcache_set</function> example with
<function>var_dump</function> as simple debugging callabck.</title>
<programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc, NULL, 'var_dump');
/* This query will be intercepted and executed via Memcache protocol */
echo "Sending query for id via Memcache: ";
$mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1");
/* f1 is not configured as valid key field, this won't be sent via Memcache */
echo "Sending query for f1 via Memcache: ";
$mysqli->query("SELECT id FROM test WHERE f1 = 1");
mysqlnd_memcache_set($mysqli);
/* Now the regular MySQL protocol will be used */
echo "var_dump won't be invoked: ";
$mysqli->query("SELECT f1, f2, f3 WHERE id = 1");
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Sending query for id via Memcache: bool(true)
Sending query for f1 via Memcache: bool(false)
var_dump won't be invoked:
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member>
<function>mysqlnd_memcache_get_config</function>
</member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- 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
-->

82
reference/mysqlnd_memcache/ini.xml Normal file
View file

@ -0,0 +1,82 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 325466 $ -->
<section xml:id="mysqlnd-memcache.configuration" xmlns="http://docbook.org/ns/docbook">
&reftitle.runtime;
&extension.runtime;
<para>
<table>
<title>Mysqlnd_memcache &ConfigureOptions;</title>
<tgroup cols="4">
<thead>
<row>
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
<entry>&Changelog;</entry>
</row>
</thead>
<tbody>
<row>
<entry><link linkend="ini.mysqlnd-memcache.enable">mysqlnd_memcache.enable</link></entry>
<entry>1</entry>
<entry>PHP_INI_SYSTEM</entry>
<entry><!-- leave empty, this will be filled by an automatic script --></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
&ini.descriptions.title;
<para>
<variablelist>
<varlistentry xml:id="ini.mysqlnd-memcache.enable">
<term>
<parameter>mysqlnd_memcache.enable</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Enables or disables the plugin. If disabled, the extension will not plug
into
<link linkend="book.mysqlnd">mysqlnd</link> to proxy internal
<link linkend="book.mysqlnd">mysqlnd</link> C API calls.
<note>
<para>
This option is mostly meant to be used by developers building this
extension static into PHP. In general users are encouraged to build
this extension as shared object and unloading it completely if not
needed.
</para>
</note>
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<!-- 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
-->

187
reference/mysqlnd_memcache/quickstart.xml Normal file
View file

@ -0,0 +1,187 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 326346 $ -->
<chapter xml:id="mysqlnd-memcache.quickstart" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Quickstart and Examples</title>
<para>
The mysqlnd memcache plugin is easy to use.
This quickstart will demo typical use-cases, and provide practical advice on getting
started.
</para>
<para>
It is strongly recommended to read the reference sections in addition to the
quickstart. The quickstart tries to avoid discussing theoretical concepts
and limitations. Instead, it will link to the reference sections. It is safe
to begin with the quickstart. However, before using the plugin in mission critical
environments we urge you to read additionally the background information from the
reference sections.
</para>
<section xml:id="mysqlnd-memcache.quickstart.configuration">
<title>Setup</title>
<para>
The plugin is implemented as a PHP extension. See also the
<link linkend="mysqlnd-memcache.installation">installation instructions</link> to
install the
<link xlink:href="&url.pecl.package;mysqlnd_memcache">mysqlnd_memcache</link> extension.
</para>
<para>
Compile or configure the PHP MySQL extension (API) (<link linkend="ref.mysqli">mysqli</link>,
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>,
<link linkend="ref.mysql">mysql</link>) that you plan to use with support
for the <link linkend="book.mysqlnd">mysqlnd</link> library. mysqlnd_memcache
is a plugin for the mysqlnd library. To use the plugin with any of the PHP
MySQL extensions, the extension has to use the mysqlnd library.
</para>
<para>
The mysqlnd_memcche PHP extension depends on the
<link linkend="book.memcached">memcached</link> extension. Refer to the
according <link linkend="memcached.installation">installation
instructions</link> for installing that module.
</para>
<para>
Then, load this extension into PHP and activate the plugin in the PHP configuration
file using the PHP configuration directive named
<link linkend="ini.mysqlnd-memcache.enable">mysqlnd_memcache.enable</link>.
</para>
<para>
<example>
<title>Enabling the plugin (php.ini)</title>
<programlisting role="ini">
<![CDATA[
; On Windows the filename is php_mysqnd_memcache.dll
extension=mysqlnd_memcache.so
mysqlnd_memcache.enable=1
]]>
</programlisting>
</example>
</para>
<para>
Follow the instructions given in the MySQL Reference Manual on installing
the Memcache plugins for the MySQL server. Activate the plugins and
configure the Memcache access to SQL tables.
</para>
<para>
For all future examples it is assumed that you have created a SQL table
like the following and configured Memcache access to it.
</para>
<para>
<example>
<title>SQL table used for the Quickstart</title>
<programlisting role="sql">
<![CDATA[
CREATE TABLE test(
id CHAR(16),
f1 VARCHAR(255),
f2 VARCHAR(255),
f3 VARCHAR(255),
flags INT NOT NULL,
cas_column INT,
expire_time_column INT,
PRIMARY KEY(id)
) ENGINE=InnoDB;
INSERT INTO test (id, f1, f2, f3) VALUES (1, 'Hello', 'World', '!');
INSERT INTO test (id, f1, f2, f3) VALUES (2, 'Lady', 'and', 'the tramp');
INSERT INTO innodb_memcache.containers(
name, db_schema, db_table, key_columns, value_columns,
flags, cas_column, expire_time_column, unique_idx_name_on_key)
VALUES (
'plugin_test', 'test', 'test', 'id', 'f1,f2,f3',
'flags', 'cas_column', 'expire_time_column', 'PRIMARY KEY');
]]>
</programlisting>
</example>
</para>
</section>
<section xml:id="mysqlnd-memcache.quickstart.usage">
<title>Usage</title>
<para>
After associating a MySQL connection with a Memcache connection using
<function>mysqnd_memcache_set</function> the plugin attempts to transparently
replace SQL <literal>SELECT</literal>
statements by a memcache access. For that purpose the plugin monitors
all SQL statements executed and tries to match the statement string
against <constant>MYSQLND_MEMCACHE_DEFAULT_REGEXP</constant>.
In case of a match, the mysqlnd memcache plugin checks whether the
<literal>SELECT</literal> is accessing only columns of a mapped table and
the <literal>WHERE</literal> clause is limited to a single key lookup.
</para>
<para>
In case of the example SQL table, the plugin will use the Memcache interface
of the MySQL server to fetch results for a SQL query like
<literal>SELECT f1, f2, f3 WHERE id = n</literal>.
</para>
<para>
<example>
<title>
Basic example.</title>
<programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("host", "user", "passwd", "database");
$memc = new Memcached();
$memc->addServer("host", 11211);
mysqlnd_memcache_set($mysqli, $memc);
/*
This is a query which queries table test using id as key in the WHERE part
and is accessing fields f1, f2 and f3. Therefore mysqlnd_memcache
will intercept it and route it ia memcache.
*/
$result = $mysqli->query("SELECT f1, f2, f3 FROM test WHERE id = 1");
while ($row = $result->fetch_row()) {
print_r($row);
}
/*
This is a query which queries table test but using f1 in the WHERE clause.
Therefore mysqlnd_memcache can't intercept it. This will be executed
using the MySQL protocol
*/
$mysqli->query("SELECT id FROM test WHERE f1 = 'Lady'");
while ($row = $result->fetch_row()) {
print_r($row);
}
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
array(
[f1] => Hello
[f2] => World
[f3] => !
)
array(
[id] => 2
)
]]>
</screen>
</example>
</para>
</section>
</chapter>
<!-- 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
-->

30
reference/mysqlnd_memcache/reference.xml Normal file
View file

@ -0,0 +1,30 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 317392 $ -->
<reference xml:id="ref.mysqlnd-memcache" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Mysqlnd_memcache &Functions;</title>
&reference.mysqlnd-memcache.entities.functions;
</reference>
<!-- 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
-->

68
reference/mysqlnd_memcache/setup.xml Normal file
View file

@ -0,0 +1,68 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 326367 $ -->
<chapter xml:id="mysqlnd-memcache.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
&reftitle.setup;
<section xml:id="mysqlnd-memcache.requirements">
&reftitle.required;
<para>
This extension requires <literal>PHP 5.4.4</literal> or newer.
</para>
<para>
For accessing <literal>InnoDB</literal> tables this PHP extension requires
<literal>MySQL Server 5.6.6</literal> or newer with the InnoDB Memcache
Daemon Plugin.
</para>
<para>
For accessing <literal>MySQL Cluster NDB</literal> tables this PHP extensions
requires <literal>MySQL Cluster 7.2</literal> or newer with configured NDB
Memcache API nodes.
</para>
<para>
<literal>PHP</literal> must be compiled with support for Perl regular
expressions through the <link linkend="ref.pcre">pcre</link> extension.
PCRE is included into PHP by default.
</para>
<para>
The <link linkend="book.memcached">memcached</link> extension 2.0.x
must be loaded into <literal>PHP</literal>.
</para>
<para>
The <literal>mysqlnd_memcache</literal> memcache
plugin supports all PHP applications and all available PHP MySQL extensions
(<link linkend="ref.mysqli">mysqli</link>,
<link linkend="ref.mysql">mysql</link>,
<link linkend="ref.pdo-mysql">PDO_MYSQL</link>).
The PHP MySQL extension must be configured to use
<link linkend="book.mysqlnd">mysqlnd</link> in order to be able
to use the <literal>mysqlnd_memcache</literal> plugin for
<link linkend="book.mysqlnd">mysqlnd</link>.
</para>
</section>
&reference.mysqlnd-memcache.configure;
&reference.mysqlnd-memcache.ini;
</chapter>
<!-- 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
-->

33
reference/mysqlnd_memcache/versions.xml Normal file
View file

@ -0,0 +1,33 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 323462 $ -->
<!--
Do NOT translate this file
-->
<versions>
<!-- Functions -->
<function name='mysqlnd_memcache_get_config' from='PECL mysqlnd_memcache &gt;= 1.0.0'/>
<function name='mysqlnd_memcache_set' from='PECL mysqlnd_memcache &gt;= 1.0.0'/>
</versions>
<!-- 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
-->