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

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<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 this 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 extension must use the <link linkend="book.mysqlnd">mysqlnd</link> library as
   because mysqlnd_memcache is a plugin for the mysqlnd library.  For additional information,
   refer to the <link linkend="memcached.installation">mysqlnd_memcache installation instructions</link>.
  </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
; Load the extension
extension=mysqlnd_memcache.so
; Enable it
mysqlnd_memcache.enable=1
]]>
    </programlisting>
    </example>
  </para>
  <para>
   Follow the instructions given in the <link xlink:href="&url.mysql.docs.memcached;">MySQL
   Reference Manual on installing the Memcache plugins</link> for the MySQL server. Activate
   the plugins and configure Memcache access for SQL tables.
  </para>
  <para>
   The examples in this quickguide assume that the following table exists, and that
   Memcache is configured with 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 via 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
-->