Basic documentation for two new functions that will come with 1.1.0

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317159 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Ulf Wendel 2011-09-22 16:45:37 +00:00
parent f491b6b95e
commit e1c761d673
4 changed files with 395 additions and 2 deletions

View file

@ -0,0 +1,238 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 310337 $ -->
<refentry xml:id="function.mysqlnd-ms-get-last-used-connection" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_ms_get_last_used_connection</refname>
<refpurpose>Returns an array which describes the last used connection</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>mixed</type>
<methodname>mysqlnd_ms_get_last_used_connection</methodname>
<methodparam><type>mixed</type><parameter>connection</parameter></methodparam>
</methodsynopsis>
<para>
Returns an array which describes the last used connection from the plugins
connection pool currently pointed to by the user connection handle. If using the
plugin, a user connection handle represents a pool of database connections.
It is not possible to tell from the user connection handles properties to which
database server from the pool the user connection handle points.
</para>
<para>
The function can be used to debug or monitor PECL mysqlnd_ms.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>connection</parameter></term>
<listitem>
<para>
A MySQL connection handle obtained from any of the
connect functions of the <link linkend="ref.mysqli">mysqli</link>,
<link linkend="ref.mysql">mysql</link> or
<link linkend="ref.pdo-mysql">PDO_MYSQL</link> extensions.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<literal>FALSE</literal> on error. Otherwise, an
array which describes the connection used to
execute the last statement on.
</para>
<para>
Array which describes the connection.
</para>
<informaltable>
<tgroup cols="3">
<colspec colwidth="10%"/>
<colspec colwidth="70%"/>
<colspec colwidth="20%"/>
<thead>
<row>
<entry>Property</entry>
<entry>Description</entry>
<entry>Version</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>scheme</literal>
</entry>
<entry>
Connection scheme. Either <literal>tcp://host:port</literal>
or <literal>unix://host:socket</literal>. If you want to
distinguish connections from each other use a combination
of <literal>scheme</literal> and <literal>thread_id</literal> as a unique
key. Neither <literal>scheme</literal> nor <literal>thread_id</literal>
alone are sufficient to distinguish two connections from each other.
Two servers may assign the same <literal>thread_id</literal> to two
different connections. Thus, connections in the pool may have the same
<literal>thread_id</literal>. Also, do not rely on uniqueness of
<literal>scheme</literal> in a pool. Your QA engineers may use the
same MySQL server instance for two distinct logical roles and add it
multiple times to the pool. This hack is used, for example,
in the test suite.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>host</literal>
</entry>
<entry>
Database server host used with the connection.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>port</literal>
</entry>
<entry>
Database server port used with the connection.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>thread_id</literal>
</entry>
<entry>
Connection thread id.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>last_message</literal>
</entry>
<entry>
Info message obtained from the
MySQL C API function mysql_info(). Pleae, see
<link linkend="mysqli.info"><function>mysqli_info</function></link> for
a description.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>errno</literal>
</entry>
<entry>
Error code.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>error</literal>
</entry>
<entry>
Error message.
</entry>
<entry>Since 1.1.0.</entry>
</row>
<row>
<entry>
<literal>sqlstate</literal>
</entry>
<entry>
Error SQLstate code.
</entry>
<entry>Since 1.1.0.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1>
&reftitle.notes;
<note>
<para>
<function>mysqlnd_ms_get_last_used_connection</function> requires
PHP &gt;= 5.4.0 and PECL mysqlnd_ms &gt;> 1.1.0. Internally, it is using
a <literal>mysqlnd</literal> function not available with PHP 5.3.
</para>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
The example assumes that <literal>myapp</literal> refers to a
plugin configuration file section and represents a connection pool.
</para>
<para>
<example>
<title><function>mysqlnd_ms_get_last_used_connection</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
$link = new mysqli("myapp", "user", "password", "database");
$res = $link->query("SELECT 1 FROM DUAL");
var_dump(mysqlnd_ms_get_last_used_connection($link));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
object(stdClass)#4 (9) {
["scheme"]=>
string(22) "unix:///tmp/mysql.sock"
["host"]=>
string(0) ""
["port"]=>
int(3306)
["thread_id"]=>
int(18739)
["last_message"]=>
string(0) ""
["errno"]=>
int(0)
["error"]=>
string(0) ""
["sqlstate"]=>
string(5) "00000"
}
]]>
</screen>
</example>
</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
-->

View file

@ -0,0 +1,139 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 311948 $ -->
<refentry xml:id="function.mysqlnd-ms-match-wild" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>mysqlnd_ms_match_wild</refname>
<refpurpose>Finds whether a table name matches a wildcard pattern or not</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type>
<methodname>mysqlnd_ms_match_wild</methodname>
<methodparam><type>string</type><parameter>table_name</parameter></methodparam>
<methodparam><type>string</type><parameter>wildcard</parameter></methodparam>
</methodsynopsis>
<para>
Finds whether a table name matches a wildcard pattern or not.
</para>
<para>
This function is not of much practical relevance with PECL mysqlnd_ms 1.1.0
because the plugin does not support MySQL replication table filtering yet.
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
<varlistentry>
<term><parameter>table_name</parameter></term>
<listitem>
<para>
The table name to check if it is matched by the wildcard.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>wildcard</parameter></term>
<listitem>
<para>
The wildcard pattern to check against the table name.
The wildcard pattern supports the same placeholders as
MySQL Replication filters do.
</para>
<para>
MySQL replication filters
can be configured by using the MySQL Server configuration
options <literal>--replicate-wild-do-table</literal> and
<literal>--replicate-wild-do-db</literal>. Please, consult
the MySQL Reference Manual to learn more about this MySQL
Server feature.
</para>
<para>
The supported placeholders are:
<itemizedlist>
<listitem>
<simpara>
<literal>%</literal> - zero or more literals
</simpara>
</listitem>
<listitem>
<simpara>
<literal>%</literal> - one literal
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
Placeholders can be escaped using <literal>\</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns <literal>TRUE</literal> <literal>table_name</literal> is
matched by <literal>wildcard</literal>.
Otherwise, returns <literal>FALSE</literal>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>mysqlnd_ms_match_wild</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
var_dump(mysqlnd_ms_match_wild("schema_name.table_name", "schema%"));
var_dump(mysqlnd_ms_match_wild("abc", "_"));
var_dump(mysqlnd_ms_match_wild("table1", "table_"));
var_dump(mysqlnd_ms_match_wild("asia_customers", "%customers"));
var_dump(mysqlnd_ms_match_wild("funny%table","funny\%table"));
var_dump(mysqlnd_ms_match_wild("funnytable", "funny%table"));
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(false)
bool(true)
bool(true)
bool(true)
bool(true)
]]>
</screen>
</example>
</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
-->

View file

@ -85,6 +85,19 @@
</para>
</refsect1>
<refsect1>
&reftitle.notes;
<note>
<para>
<function>mysqlnd_ms_set_user_pick_server</function> is available
with PECL mysqlnd_ms &lt; 1.1.0. It has been replaced by the
<literal>user</literal> filter. Please, check the
<link linkend="mysqlnd-ms.changes_one_one">Change History</link>
for upgrade notes.
</para>
</note>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>

View file

@ -6,9 +6,12 @@
<versions>
<!-- Functions -->
<function name='mysqlnd_ms_set_user_pick_server' from='PECL mysqlnd_ms &gt;= 1.0.0'/>
<function name='mysqlnd_ms_query_is_select' from='PECL mysqlnd_ms &gt;= 1.0.0'/>
<function name='mysqlnd_ms_get_last_used_connection' from='PHP &gt;= 5.4.0, PECL mysqlnd_ms &gt;= 1.1.0'/>
<function name='mysqlnd_ms_get_stats' from='PECL mysqlnd_ms &gt;= 1.0.0'/>
<function name='mysqlnd_ms_match_wild' from='PECL mysqlnd_ms &gt;= 1.1.0'/>
<function name='mysqlnd_ms_query_is_select' from='PECL mysqlnd_ms &gt;= 1.0.0'/>
<function name='mysqlnd_ms_set_user_pick_server' from='PECL mysqlnd_ms &lt; 1.1.0'/>
</versions>
<!-- Keep this comment at the end of the file