From 0550673f7eaf4b1b46d544fbcfd4642493c37d2d Mon Sep 17 00:00:00 2001
From: Ulf Wendel <uw@php.net>
Date: Wed, 28 Sep 2011 10:44:35 +0000
Subject: [PATCH] Some of the most pressing fixes proposed by Johannes. More to
 come next week.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317434 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/mysqlnd_ms/concepts.xml             | 19 +++++++++++++------
 reference/mysqlnd_ms/configure.xml            |  9 ++++-----
 .../mysqlnd-ms-get-last-used-connection.xml   |  8 ++++----
 reference/mysqlnd_ms/quickstart.xml           | 16 +++++++++-------
 reference/mysqlnd_ms/setup.xml                | 17 ++++++++++-------
 5 files changed, 40 insertions(+), 29 deletions(-)

diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index c77216d223..9c55dbc4cd 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/reference/mysqlnd_ms/concepts.xml
@@ -74,7 +74,7 @@
    <link linkend="ref.mysqli">mysqli</link>,
    <link linkend="ref.mysql">mysql</link>,
    <link linkend="ref.pdo-mysql">PDO_MYSQL</link> connection
-   handle and a MySQL wire connection. If using the plugin a
+   handle and a MySQL network connection. If using the plugin a
    <link linkend="ref.mysqli">mysqli</link>,
    <link linkend="ref.mysql">mysql</link>,
    <link linkend="ref.pdo-mysql">PDO_MYSQL</link> connection
@@ -121,7 +121,7 @@
     </listitem>
     <listitem>
      <simpara>
-      Session system variables and session user variables
+      The current database set using <literal>USE</literal>
      </simpara>
     </listitem>
     <listitem>
@@ -197,6 +197,7 @@
        <function>mysql_db_query</function>,
        <function>mysql_list_fields</function>,
        <function>mysqli_select_db</function>.
+       Note, that SQL <literal>USE</literal> is not monitored.
       </entry>
       <entry>Since 1.0.0.</entry>
      </row>
@@ -208,6 +209,7 @@
        Called by the following user API calls:
        <function>mysql_set_charset</function>.
        <function>mysqli_set_charset</function>.
+       Note, that SQL <literal>SET NAMES</literal> is not monitored.
       </entry>
       <entry>Since 1.0.0.</entry>
      </row>
@@ -245,7 +247,7 @@
       <entry>
         Called by the following user API calls:
         <function>mysqli_autocommit</function>,
-        <function>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)</function>.
+        <literal>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)</literal>.
       </entry>
       <entry>Since 1.0.0. PHP &gt;= 5.4.0.</entry>
      </row>
@@ -382,7 +384,7 @@
     mode.
     The library function <literal>set_autocommit()</literal> is called by the
     <function>mysqli_autocommit</function> and
-    <function>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)</function> user API calls.
+    <literal>PDO::setAttribute(PDO::ATTR_AUTOCOMMIT)</literal> user API calls.
   </para>
   <para>
     The experimental pluging configuration option
@@ -463,7 +465,11 @@
    the SQL hint <literal>/*ms=slave*/</literal> or a slave had been chosen for
    running the previous query and the query starts with the SQL hint
    <literal>/*ms=last_used*/</literal>. In all other cases the query will
-   be send to the MySQL replication master server.
+   be send to the MySQL replication master server. It is recommended to
+   use the constants <literal>MYSQLND_MS_SLAVE_SWITCH</literal>,
+   <literal>MYSQLND_MS_MASTER_SWITCH</literal> and <literal>MYSQLND_MS_LAST_USED_SWITCH</literal>
+   instead of <literal>/*ms=slave*/</literal>. Please see,
+   <link linkend="mysqlnd-ms.constants">constants</link>.
   </para>
   <para>
    SQL hints are a special kind of standard compliant SQL comments. The plugin
@@ -476,7 +482,8 @@
   </para>
   <para>
    The built-in read-write splitter can be replaced by a user-defined one, see also
-   <function>mysqlnd_ms_set_user_pick_server</function>.
+   <link linkend="ini.mysqlnd-ms-plugin-config-v2.filter_user"><literal>user</literal></link>
+   filter.
   </para>
   <para>
     A user-defined read-write splitter can ask the built-in logic to make
diff --git a/reference/mysqlnd_ms/configure.xml b/reference/mysqlnd_ms/configure.xml
index 38dcb297da..9b48b32dd7 100755
--- a/reference/mysqlnd_ms/configure.xml
+++ b/reference/mysqlnd_ms/configure.xml
@@ -5,11 +5,10 @@
  &reftitle.install;
 
  <note>
-   <para>
-    The mysqlnd replication and load balancing plugin is in alpha status.
-    It is not feature complete.
-   </para>
-  </note>
+  <para>
+   The mysqlnd replication and load balancing plugin is in beta status.
+  </para>
+ </note>
 
  <para>
   &pecl.moved;
diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-last-used-connection.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-last-used-connection.xml
index 3570dada8a..8f19bef9bb 100644
--- a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-last-used-connection.xml
+++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-last-used-connection.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 310337 $ --> 
+<!-- $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>
@@ -120,7 +120,7 @@
       </entry>
       <entry>
        Info message obtained from the
-       MySQL C API function mysql_info(). Pleae, see 
+       MySQL C API function mysql_info(). Pleae, see
        <link linkend="mysqli.info"><function>mysqli_info</function></link> for
        a description.
       </entry>
@@ -164,7 +164,7 @@
    <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.
+    a <literal>mysqlnd</literal> library C call not available with PHP 5.3.
    </para>
   </note>
  </refsect1>
@@ -213,7 +213,7 @@ object(stdClass)#4 (9) {
    </example>
   </para>
  </refsect1>
- 
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/mysqlnd_ms/quickstart.xml b/reference/mysqlnd_ms/quickstart.xml
index ea85a15df7..11cfc00539 100755
--- a/reference/mysqlnd_ms/quickstart.xml
+++ b/reference/mysqlnd_ms/quickstart.xml
@@ -43,7 +43,7 @@
    configuration directive
    <link linkend="ini.mysqlnd-ms.ini-file">mysqlnd_ms.ini_file</link>
    to set the full path to the plugin-specific configuration file.
-   This file must be readable by PHP.
+   his file must be readable by PHP (i.e. the web server user).
   </para>
   <para>
    <example>
@@ -71,7 +71,7 @@ mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
   <para>
     A section must at least list the MySQL replication master server and set
     a list of slaves. The plugin supports using only one master server per section.
-    Multi-master MySQL replication setups are not supported.
+    Multi-master MySQL replication setups are not yet fully supported.
     Use the configuration setting
     <link linkend="ini.mysqlnd-ms-plugin-config-v2.master">master</link>
     to set the hostname and the port or socket of the MySQL master server.
@@ -152,7 +152,7 @@ mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
    will be described later in the quickstart guide.
   </para>
   <para>
-   It is responsibility of the application to handle potential issues caused
+   It is the responsibility of the application to handle potential issues caused
    by connection switches. By always configuring a master and at lease one slave
    server you can be sure to detect issues early because switches become
    possible.
@@ -257,8 +257,10 @@ $mysql = mysql_connect("myapp", "username", "password");
    The plugin will send read-only statements to the MySQL slave server with the
    IP <literal>192.168.2.27</literal> and listening on port <literal>3306</literal>
    for MySQL client connection. All other statements will be directed to the
-   MySQL master server running on the host <literal>localhost</literal> accepting
-   MySQL client connection on the Unix domain socket <literal>/tmp/mysql.sock</literal>.
+   MySQL master server running on the host <literal>localhost</literal>. If on Unix like
+   operating systems, the master on <literal>localhost</literal> will be accepting
+   MySQL client connection on the Unix domain socket <literal>/tmp/mysql.sock</literal>,
+   on Windows the default TCP/IP port will be used.
    The plugin will use the user name <literal>username</literal> and the password
    <literal>password</literal> to connect to any of the MySQL servers listed in
    the section <literal>myapp</literal> of the plugins configuration file. Upon
@@ -488,7 +490,7 @@ $mysqli->close();
 <![CDATA[
 <?php
 $mysqli = new mysqli("myapp", "username", "password", "database");
-if (!$mysqli)
+if (mysqli_connect_errno())
   /* Of course, your error handling is nicer... */
   die(sprintf("[%d] %s\n", mysqli_connect_errno(), mysqli_connect_error()));
 
@@ -548,7 +550,7 @@ if (!$mysqli->query(sprintf("/*%s*/SELECT critical_data FROM important_table", M
    </example>
   </para>
   <para>
-   use case may include the creation of tables on a slave.
+   Use case may include the creation of tables on a slave.
    If no SQL hint is given, the plugin will send <literal>CREATE</literal>
    and <literal>INSERT</literal> statements to the master. Use the
    SQL hint <constant>MYSQLND_MS_SLAVE_SWITCH</constant> if you want to
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index 133cf66257..73a10ef60b 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/reference/mysqlnd_ms/setup.xml
@@ -11,7 +11,7 @@
   </para>
   <para>
    The <literal>mysqlnd_ms</literal> replication and load balancing
-   plugin supports all PHP applications and all availablePHP MySQL extensions
+   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>).
@@ -45,10 +45,11 @@
    is used to set the plugins configuration file.
   </para>
   <para>
-   As of mysqlnd 1.1.0-beta <literal>JSON</literal> format is used
-   for the plugins configuration file. <literal>JSON</literal> structures
-   are fast to parse by the plugin, thanks PHPs JSON support.
-   The <literal>JSON</literal>  format makes it easy to define hierarchical
+   As of mysqlnd 1.1.0-beta JavaScript Object Notation (<literal>JSON</literal>)
+   format is used for the plugins configuration file.
+   <literal>JSON</literal> structures are fast to parse by the plugin,
+   thanks PHPs JSON support. The <literal>JSON</literal> format makes it easy
+   to define hierarchical
    data structures. Hierachical data structures are used, for example,
    to allow definition of chained filters. Expressing hierarchical data structures
    with the standard <literal>php.ini</literal> format is much more inconvenient.
@@ -194,6 +195,9 @@ $mysqli = new mysqli("localhost", "username", "password", "database");
    MySQL queries following the rules from the <literal>localhost</literal>
    configuration section. This way you can load balance queries from
    an application without changing the applications source code.
+   Please keep in mind, that such a configuration may not contribute
+   to overall readability of your applications source code. Using section names
+   that can be mixed up with host names should be seen as a last resort.
   </para>
   <para xml:id="mysqlnd-ms.plugin-ini-json.server_list_syntax">
    Each configuration section contains at least a list of master servers
@@ -1646,8 +1650,7 @@ slave[] = mysql_slave_2
   <title xmlns="http://docbook.org/ns/docbook">Testing</title>
   <note>
    <para>
-    The section applies to the development tree (1.1.0-beta) but not the
-    1.0 series.
+    The section applies to myslqnd_ms 1.1.0 or newer, not the 1.0 series.
    </para>
   </note>
   <para>