php-doc-en/reference/mysqlnd_qc/constants.xml

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

<appendix xml:id="mysqlnd-qc.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.constants;
 &extension.constants;
 <para>
  <emphasis role="bold">SQL hint related</emphasis>
 </para>
 <para>
  <example>
   <title>Using SQL hint constants</title>
   <para>
    The query cache is controlled by SQL hints. SQL hints are used to enable and
    disable caching. SQL hints can be used to set the
    <literal>TTL</literal> of a query.
   </para>
   <para>
    The SQL hints recognized by the query cache can be manually changed at
    compile time. This makes it possible to use
    <literal>mysqlnd_qc</literal> in environments in which the default
    SQL hints are already taken and interpreted by other systems. Therefore
    it is recommended to use the SQL hint string constants instead of
    manually adding the default SQL hints to the query string.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Use constants for maximum portability */
$query = "/*" . MYSQLND_QC_ENABLE_SWITCH . "*/SELECT id FROM test";

/* Valid but less portable: default TTL */
$query = "/*qc=on*/SELECT id FROM test";

/* Valid but less portable: per statement TTL */
$query = "/*qc=on*//*qc_ttl=5*/SELECT id FROM test";

printf("MYSQLND_QC_ENABLE_SWITCH: %s\n", MYSQLND_QC_ENABLE_SWITCH);
printf("MYSQLND_QC_DISABLE_SWITCH: %s\n", MYSQLND_QC_DISABLE_SWITCH);
printf("MYSQLND_QC_TTL_SWITCH: %s\n", MYSQLND_QC_TTL_SWITCH);
?>
]]>
   </programlisting>
   &examples.outputs;
   <screen>
<![CDATA[
MYSQLND_QC_ENABLE_SWITCH: qc=on
MYSQLND_QC_DISABLE_SWITCH: qc=off
MYSQLND_QC_TTL_SWITCH: qc_ttl=

]]>
   </screen>

  </example>
 </para>

 <para>
  <variablelist>
   <varlistentry xml:id="constant.mysqlnd-qc-enable-switch">
    <term>
     <constant>MYSQLND_QC_ENABLE_SWITCH</constant>
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      SQL hint used to enable caching of a query.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.mysqlnd-qc-disable-switch">
    <term>
     <constant>MYSQLND_QC_DISABLE_SWITCH</constant>
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      SQL hint used to disable caching of a query if
      <literal>mysqlnd_qc.cache_by_default = 1</literal>.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.mysqlnd-qc-ttl-switch">
    <term>
     <constant>MYSQLND_QC_TTL_SWITCH</constant>
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      SQL hint used to set the TTL of a result set.
     </simpara>
    </listitem>
   </varlistentry>
   <varlistentry xml:id="constant.mysqlnd-qc-server-id">
    <term>
     <constant>MYSQLND_QC_SERVER_ID_SWITCH</constant>
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      This SQL hint should not be used in general.
     </simpara>
     <simpara>
      It is needed by <link linkend="book.mysqlnd-ms">PECL/mysqlnd_ms</link>
      to group cache entries for one statement
      but originating from different physical connections. If the
      hint is used connection settings such as user, hostname and charset
      are not considered for generating a cache key of a query.
      Instead the given value and the query string are used as input
      to the hashing function that generates the key.
     </simpara>
     <simpara>
      PECL/mysqlnd_ms may, if instructed, cache results from
      MySQL Replication slaves. Because it can hold many connections
      to the slave the cache key shall not be formed from the user,
      hostname or other settings that may vary for the various slave
      connections. Instead, PECL/mysqlnd_ms provides an identifier
      which refers to the group of slave connections that shall be enabled
      to share cache entries no matter which physical slave connection was
      to generate the cache entry.
     </simpara>
     <simpara>
      Use of this feature outside of PECL/mysqlnd_ms is not recommended.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
 <para>
  <emphasis role="bold"><function>mysqlnd_qc_set_cache_condition</function> related</emphasis>
 </para>
 <para>
  <example>
   <title>Example <function>mysqlnd_qc_set_cache_condition</function> usage</title>
   <para>
    The function <function>mysqlnd_qc_set_cache_condition</function> allows setting conditions
    for automatic caching of statements which don't begin with the SQL hints
    necessary to manually enable caching.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Cache all accesses to tables with the name "new%" in schema/database "db_example" for 1 second */
if (!mysqlnd_qc_set_cache_condition(MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN, "db_example.new%", 1)) {
  die("Failed to set cache condition!");
}

$mysqli = new mysqli("host", "user", "password", "db_example", "port");
/* cached although no SQL hint given  */
$mysqli->query("SELECT id, title FROM news");

$pdo_mysql = new PDO("mysql:host=host;dbname=db_example;port=port", "user", "password");
/* not cached: no SQL hint, no pattern match */
$pdo_mysql->query("SELECT id, title FROM latest_news");
/* cached: TTL 1 second, pattern match */
$pdo_mysql->query("SELECT id, title FROM news");
?>
]]>
   </programlisting>
  </example>
 </para>
 <para>
  <variablelist>
   <varlistentry xml:id="constant.mysqlnd-qc-condition-meta-schema-pattern">
    <term>
     <constant>MYSQLND_QC_CONDITION_META_SCHEMA_PATTERN</constant>
     (<type>int</type>)
    </term>
    <listitem>
     <simpara>
      Used as a parameter of <function>mysqlnd_qc_set_cache_condition</function>
      to set conditions for schema based automatic caching.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
 <para>
  <emphasis role="bold">Other</emphasis>
 </para>
 <para>
  The plugin version number can be obtained using either
  <constant>MYSQLND_QC_VERSION</constant>, which is the string representation 
  of the numerical version number, or <constant>MYSQLND_QC_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_QC_VERSION_ID</entry>
      <entry>10000</entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </para>
 <para>
  <variablelist>
   <varlistentry xml:id="constant.mysqlnd-qc-version">
    <term>
     <constant>MYSQLND_QC_VERSION</constant>
     (<type>string</type>)
    </term>
    <listitem>
     <simpara>
      Plugin version string, for example, <quote>1.0.0-prototype</quote>.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
 <para>
  <variablelist>
   <varlistentry xml:id="constant.mysqlnd-qc-version-id">
    <term>
     <constant>MYSQLND_QC_VERSION_ID</constant>
     (<type>int</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
-->