php-doc-en/reference/mysqlnd_memcache/quickstart.xml

<?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
-->