svn: /phpdoc/en/trunk/reference/mysqlnd_ms/ ini.xml quickstart.xml setup.xml

uw Tue, 12 Feb 2013 13:53:16 +0000 Revision: http://svn.php.net/viewvc?view=revision&revision=329474 Log: More config file debug hints Changed paths: U phpdoc/en/trunk/reference/mysqlnd_ms/ini.xml U phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml U phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml Modified: phpdoc/en/trunk/reference/mysqlnd_ms/ini.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/ini.xml 2013-02-12 13:49:47 UTC (rev 329473) +++ phpdoc/en/trunk/reference/mysqlnd_ms/ini.xml 2013-02-12 13:53:16 UTC (rev 329474) @@ -97,8 +97,20 @@ </para> <para> This setting is not only useful to restrict PHP to certain servers but also - to debug configuration file problems. + to debug configuration file problems. The configuration file validity is checked + at two different stages. The first check is performed when PHP begins to + handle a web request. At this point the plugin reads and decodes the configuration + file. Errors thrown at this early stage in an extensions life cycle may not be + shown properly to the user. Thus, the plugin buffers the errors, if any, and + additionally displays them when establishing a connection to MySQL. + By default a buffered startup error will emit an error of type + <literal>E_WARNING</literal>. If <literal>force_config_usage</literal> is set, + the error type used is <literal>E_RECOVERABLE_ERROR</literal>. </para> + <para> + Please, see also <link linkend="mysqlnd-ms.plugin-ini-json.debug_config">configuration + file debugging notes</link>. + </para> </listitem> </varlistentry> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml 2013-02-12 13:49:47 UTC (rev 329473) +++ phpdoc/en/trunk/reference/mysqlnd_ms/quickstart.xml 2013-02-12 13:53:16 UTC (rev 329474) @@ -201,7 +201,8 @@ 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. + may help debugging a faulty setup. Please, see also + <link linkend="mysqlnd-ms.plugin-ini-json.debug_config">configuration file debugging notes</link>. </para> </section> Modified: phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml =================================================================== --- phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2013-02-12 13:49:47 UTC (rev 329473) +++ phpdoc/en/trunk/reference/mysqlnd_ms/setup.xml 2013-02-12 13:53:16 UTC (rev 329474) @@ -382,7 +382,94 @@ </programlisting> </example> </para> + <para xml:id="mysqlnd-ms.plugin-ini-json.debug_config"> + The validity of the configuration file is checked both when reading the + configuration file and later when establishing a connection. The configuration + file is read during PHP request startup. At this early stage a PHP extension + may not display error messages properly. In the worst case, no error + is shown and a connection attempt fails without an adequate error message. + This problem has been cured in version 1.5.0. + </para> <para> + <example> + <title>Common error message in case of configuration file issues (upto version 1.5.0)</title> + <programlisting role="php"> +<![CDATA[ +<?php +$mysqli = new mysqli("myapp", "username", "password", "database"); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code + +Warning: mysqli::mysqli(): (HY000/2002): php_network_getaddresses: getaddrinfo failed: Name or service not known in Command line code on line 1 + +Warning: mysqli::query(): Couldn't fetch mysqli in Command line code on line 1 + +Fatal error: Call to a member function fetch_assoc() on a non-object in Command line code on line 1 +]]> + </screen> + </example> + </para> + <para> + Since version 1.5.0 startup errors are additionally buffered and emitted when + a connection attempt is made. Use the configuration directive + <link linkend="ini.mysqlnd-ms.force-config-usage"><literal>mysqlnd_ms.force_config_usage</literal></link> + to set the error type used to display buffered errors. By default an error + of type <literal>E_WARNING</literal> will be emitted. + </para> + <para> + <example> + <title>Improved configuration file validation since 1.5.0</title> + <programlisting role="php"> +<![CDATA[ +<?php +$mysqli = new mysqli("myapp", "username", "password", "database"); +?> +]]> + </programlisting> + &example.outputs; + <screen> +<![CDATA[ +Warning: mysqli::mysqli(): (mysqlnd_ms) (mysqlnd_ms) Failed to parse config file [s1.json]. Please, verify the JSON in Command line code on line 1 +]]> + </screen> + </example> + </para> + <para> + It can be useful to set <link linkend="ini.mysqlnd-ms.force-config-usage"><literal>mysqlnd_ms.force_config_usage = 1</literal></link> + when debugging potential configuration file errors. This will not only turn the + type of buffered startup errors into <literal>E_RECOVERABLE_ERROR</literal> but also + help detecting misspelled section names. + </para> + <para> + <example> + <title>Possibly more precise error due to <literal>mysqlnd_ms.force_config_usage=1</literal></title> + <programlisting role="ini"> +<![CDATA[ +mysqlnd_ms.force_config_usage=1 +]]> + </programlisting> + <programlisting role="php"> +<![CDATA[ +<?php +$mysqli = new mysqli("invalid_section", "username", "password", "database"); +?> +]]> + </programlisting> +&example.outputs; + <screen> +<![CDATA[ +Warning: mysqli::mysqli(): (mysqlnd_ms) Exclusive usage of configuration enforced but did not find the correct INI file section (invalid_section) in Command line code on line 1 line 1 +]]> + </screen> + + </example> + </para> + <para> Here is a short explanation of the configuration directives that can be used. </para> <para>