Small updates for 1.5 and fixes for 1.4

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@329439 c90b9560-bf6c-de11-be94-00142212c4b1

reference/mysqlnd_ms/book.xml

@@ -238,6 +238,29 @@
        </itemizedlist>
       </para>
      </listitem>
+
+     <listitem>
+      <para>
+       Partitioning and sharding
+      </para>
+      <para>
+       <itemizedlist>
+        <listitem>
+         <para>
+          Servers of a replication cluster can be organized in groups.
+          Queries can be manually directed to to a specific group using a SQL hint.
+          Grouping can be used to partition (shard) data, or to cure the issue of
+          hotspots in update anywhere setups.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          MySQL Replication filter are supported through the table filter.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
     </itemizedlist>
    </para>
   </section>

reference/mysqlnd_ms/changes.xml

@@ -66,6 +66,21 @@
       both client and server support.
      </para>
     </listitem>
+    <listitem>
+    <para>
+      Extended configuration file validation during PHP startup (RINIT).
+      A warning will be thrown if the configuration file can not be read, is empty
+      or parsing the JSON failed. Please note, execution is not halted.
+      Warnings may appear in log files only depending on your PHP deployment.
+      Distributions that aim to provide a pre-configured setup including a
+      configuration file stub are asked to put <literal>{}</literal> into
+      the configuration file to prevent any warnings about an invalid
+      configuration.
+     </para>
+     <para>
+      Code examples from the source distribution have been updated.
+     </para>
+    </listitem>
    </itemizedlist>
   </para>
  </section>

reference/mysqlnd_ms/ini.xml

@@ -95,6 +95,10 @@
       MySQL connection attempt, matches a section name from the plugin configuration
       file. If not, the connection attempt is blocked.
      </para>
+     <para>
+      This setting is not only useful to restrict PHP to certain servers but also
+      to debug configuration file problems.
+     </para>
     </listitem>
    </varlistentry>
 

reference/mysqlnd_ms/quickstart.xml

@@ -48,7 +48,7 @@
     <programlisting role="ini">
 <![CDATA[
 mysqlnd_ms.enable=1
-mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
+mysqlnd_ms.config_file=/path/to/mysqlnd_ms_plugin.ini
 ]]>
     </programlisting>
     </example>
@@ -56,14 +56,18 @@ mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
   <para>
    The plugin uses its own configuration file. Use the PHP
    configuration directive
-   <link linkend="ini.mysqlnd-ms.ini-file">mysqlnd_ms.ini_file</link>
+   <link linkend="ini.mysqlnd-ms.config-file">mysqlnd_ms.config_file</link>
    to set the full file path to the plugin-specific configuration file.
    This file must be readable by PHP (e.g., the web server user).
+   Please note, the configuration directive <link linkend="ini.mysqlnd-ms.config-file">mysqlnd_ms.config_file</link>
+   superseeds <link linkend="ini.mysqlnd-ms.ini-file">mysqlnd_ms.ini_file</link>
+   since 1.4.0. It is a common pitfall to use the old, no longer available
+   configuration directive.
   </para>
   <para>
    Create a plugin-specific configuration file. Save the file to the path
    set by the PHP configuration directive
-   <link linkend="ini.mysqlnd-ms.ini-file">mysqlnd_ms.ini_file</link>.
+   <link linkend="ini.mysqlnd-ms.config-file">mysqlnd_ms.config_file</link>.
   </para>
   <para>
    The plugins <link linkend="mysqlnd-ms.plugin-ini-json">configuration file</link>
@@ -190,6 +194,15 @@ mysqlnd_ms.ini_file=/path/to/mysqlnd_ms_plugin.ini
     </programlisting>
     </example>
   </para>
+  <para>
+   The plugin attempts to notify you of invalid configurations. Since 1.5.0 it
+   will throw a warning during PHP startup if the configuration file cannot be read,
+   is empty or parsing the JSON failed. Depending on your PHP settings those
+   errors may appear in some log files only. Further validation is done when a connection
+   is to be established and the configuration file is searched for valid sections.
+   Setting <link linkend="ini.mysqlnd-ms.force-config-usage">mysqlnd_ms.force_config_usage</link>
+   may help debugging a faulty setup.
+  </para>
 
  </section>
 
@@ -612,7 +625,7 @@ $mysqli->close();
   <para>
    The current version of the plugin is not transaction safe by default,
    because it is not aware of running transactions in all cases. SQL transactions are
-   units of work to be run on a single server.  The plugin does not always know
+   units of work to be run on a single server. The plugin does not always know
    when the unit of work starts and when it ends. Therefore, the plugin may
    decide to switch connections in the middle of a transaction.
   </para>
@@ -793,6 +806,11 @@ $mysqli->close();
     requires PHP 5.4.0 or newer.
    </para>
   </note>
+  <para>
+   Please note the restrictions outlined in the
+   <link linkend="mysqlnd-ms.transaction">transaction handling</link> concepts
+   section.
+  </para>
  </section>
  <section xml:id="mysqlnd-ms.quickstart.qos-consistency">
   <title>Service level and consistency</title>
@@ -1713,7 +1731,9 @@ var_dump($res->fetch_assoc());
    and silent failover. Depending on the configuration, the automatic and silent failover
    will either attempt to fail over to the master before issuing and error or, try to
    connect to other slaves, given the query allowes for it, before attempting to connect
-   to a master.
+   to a master. Because <link linkend="mysqlnd-ms.failover">automatic failover</link> is
+   not fool-proof, it is not discussed in the quickstart. Instead, details are given
+   in the concepts section below.
   </para>
   <para>
    <example>

reference/mysqlnd_ms/setup.xml

@@ -49,7 +49,7 @@
   </para>
   <para>
    The PHP configuration directive
-   <link linkend="ini.mysqlnd-ms.ini-file"><literal>mysqlnd_ms.ini_file</literal></link>
+   <link linkend="ini.mysqlnd-ms.config-file"><literal>mysqlnd_ms.config_file</literal></link>
    is used to set the plugins configuration file. Please note, that
    the PHP configuration directive may not be evaluated for every web request.
    Therefore, changing the plugins configuration file name or location may