From 001af012d75d0594cc038b35a38ae325ced01b9d Mon Sep 17 00:00:00 2001 From: Philip Olson Date: Fri, 27 Apr 2012 05:47:52 +0000 Subject: [PATCH] Some rewording, and a few typo fixes git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@325471 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqlnd_uh/book.xml | 46 ++++++++++++--------------- reference/mysqlnd_uh/changes.xml | 8 ++--- reference/mysqlnd_uh/constants.xml | 14 ++++----- reference/mysqlnd_uh/ini.xml | 6 ++-- reference/mysqlnd_uh/quickstart.xml | 48 ++++++++++++----------------- 5 files changed, 51 insertions(+), 71 deletions(-) diff --git a/reference/mysqlnd_uh/book.xml b/reference/mysqlnd_uh/book.xml index d4c43bf2d3..cf43ea2fd4 100644 --- a/reference/mysqlnd_uh/book.xml +++ b/reference/mysqlnd_uh/book.xml @@ -32,12 +32,12 @@ - Queries run by any of the PHP MySQL extensions + Queries executed by any of the PHP MySQL extensions - Prepared statements run by any of the PHP MySQL extensions + Prepared statements executing by any of the PHP MySQL extensions @@ -51,12 +51,12 @@ - Detection of databases uses + Detection of database usage - SQL Injection protection using black-/whitelists + SQL injection protection using black and white lists @@ -79,20 +79,20 @@ - As of version PHP 5.3.3 the MySQL native driver for PHP - (mysqlnd) + The MySQL native driver for PHP (mysqlnd) features an internal plugin C API. C plugins, such as the mysqlnd user handler plugin, can extend the functionality of mysqlnd. PECL/mysqlnd_uh makes parts of the internal plugin C API available to the PHP user for plugin development with PHP. - - The MySQL native driver for PHP is a C library which ships together with - PHP as of PHP 5.3.0. It serves as a drop-in replacement for the - MySQL Client Library (AKA libmysql/libmysqlclient). As of PHP 5.4.0, mysqlnd is - the compile time default library used by all PHP MySQL extensions. - + + Status + + The mysqlnd user handler plugin is in alpha status. + Take appropriate care before using it in production environments. + +
Security considerations @@ -116,14 +116,13 @@
Documentation note - Many of the extensions functions are described very briefly. - This is done intentionally to avoid content duplication. - The mysqli extension is often - only a thin abstraction layer on top of the MySQL C API, which + Many of the mysqlnd_uh functions are briefly described because + the mysqli extension is + a thin abstraction layer on top of the MySQL C API that the mysqlnd library provides. Therefore, the corresponding mysqli documentation - respectively the MySQL reference manual can be consulted - to get more information on a particular function. + (along with the MySQL reference manual) can be consulted + to receive more information about a particular function.
@@ -131,16 +130,9 @@ On the name The shortcut mysqlnd_uh stands for - mysqlnd user handler. There may be better names. - However, this was the initial choice when development started. - Meanwhile, non speaking names have almost become a tradition. + mysqlnd user handler, and has been the name + since early development. - - - The mysqlnd user handler plugin is in alpha status. - Take appropriate care before using it in production environments. - -
diff --git a/reference/mysqlnd_uh/changes.xml b/reference/mysqlnd_uh/changes.xml index 8999050024..8e83f8b471 100644 --- a/reference/mysqlnd_uh/changes.xml +++ b/reference/mysqlnd_uh/changes.xml @@ -7,12 +7,8 @@ The Change History lists major changes users need to be aware if upgrading from one version to another. It is a high level summary of selected changes that may impact applications or might even break backwards compatibility. - Please, consult the CHANGES file contained in the source - distribution for a more complete list of changes. If you are eager to learn - about all changes, even smaller ones that do not make it into the - CHANGES file, you may want to monitor PECL commit messages. - To do you, you could, for example, subscribe to the PECL commit message mailing - list. + See also the CHANGES file contained in the source + for additional changelog information. The commit history is also available.
diff --git a/reference/mysqlnd_uh/constants.xml b/reference/mysqlnd_uh/constants.xml index b1f6a53bf7..5fd9153fd3 100644 --- a/reference/mysqlnd_uh/constants.xml +++ b/reference/mysqlnd_uh/constants.xml @@ -385,7 +385,7 @@ - MySQL Client Server protocol packet: authentification. + MySQL Client Server protocol packet: authentication. @@ -529,7 +529,7 @@ - Implicity close, for example, during garbage connection. + Implicitly closed, for example, during garbage connection. @@ -619,7 +619,7 @@ - Option: wheter the MySQL compressed protocol is to be used. + Option: whether the MySQL compressed protocol is to be used. @@ -696,7 +696,7 @@ - Option: Wheter to allow LOAD DATA LOCAL INFILE use. + Option: Whether to allow LOAD DATA LOCAL INFILE use. @@ -817,7 +817,7 @@ - Option: Wheter to report data truncation. + Option: Whether to report data truncation. @@ -828,7 +828,7 @@ - Option: Wheter to reconnect automatically. + Option: Whether to reconnect automatically. @@ -949,7 +949,7 @@ - Option: default authentification method. + Option: default authentication method. diff --git a/reference/mysqlnd_uh/ini.xml b/reference/mysqlnd_uh/ini.xml index e42682ec16..1a4e8119f4 100644 --- a/reference/mysqlnd_uh/ini.xml +++ b/reference/mysqlnd_uh/ini.xml @@ -59,9 +59,9 @@ - Wheter to report wrong return value types of user hooks as error - of the type E_WARNING. It is strongly recommended - to use this setting for detecting possible issues. + Whether to report wrong return value types of user hooks as + E_WARNING level errors. This is recommended + for detecting errors. diff --git a/reference/mysqlnd_uh/quickstart.xml b/reference/mysqlnd_uh/quickstart.xml index ba210b8889..62acc5efcf 100644 --- a/reference/mysqlnd_uh/quickstart.xml +++ b/reference/mysqlnd_uh/quickstart.xml @@ -30,15 +30,15 @@ - None of the mysqlnd internal function calls has been designed - to ever by exposed to the PHP user. Manipulating their activities may + The internal mysqlnd function calls are not designed + to be exposed to the PHP user. Manipulating their activities may cause PHP to crash or leak memory. Often, this is not considered a bug. Please, keep in mind that you are accessing C library functions through PHP which are expected to take certain actions, which you may not be able to emulate in user space. Therefore, it is strongly recommended to always call the parent method implementation when subclassing MysqlndUhConnection or MysqlndUhPreparedStatement. To prevent the worst - case, the extension performs some sanity checks. Please, see also + case, the extension performs some sanity checks. Please, see also the Mysqlnd_uh &ConfigureOptions;. @@ -47,8 +47,7 @@
Setup - The plugin is implemented as a PHP extension. - Please, follow the + The plugin is implemented as a PHP extension. See the installation instructions to install the PECL/mysqlnd_uh extension. @@ -73,38 +72,32 @@ mysqlnd_uh.report_wrong_types=1
How it works - - - You can skip the following and move on to the examples for now, if you - are not interested in the inner workings. Please, get back to the - background information and read it carefully, if you plan to use - PECL/mysqlnd_uh intensively in the future. - - + This describes the background and inner workings of the mysqlnd_uh + extension. Two classes are provided by the extension: MysqlndUhConnection - and MysqlndUhPreparedStatement. The first one lets + and MysqlndUhPreparedStatement. MysqlndUhConnection lets you access almost all methods of the mysqlnd - internal connection class. The latter exposes some, selected + internal connection class. The latter exposes some selected methods of the mysqlnd internal statement class. For example, MysqlndUhConnection::connect maps to the mysqlnd library C function mysqlnd_conn__connect. - As a mysqlnd plugin, the PECL/mysqlnd_uh extensions replaces mysqlnd + As a mysqlnd plugin, the PECL/mysqlnd_uh extension replaces mysqlnd library C functions with its own functions. Whenever a - PHP MySQL extension compiled to use mysqlnd, calls + PHP MySQL extension compiled to use mysqlnd calls a mysqlnd function, the functions installed by the plugin are executed - instead of the original mysqlnd ones. If, for example, + instead of the original mysqlnd ones. For example, mysqli_connect invokes mysqlnd_conn__connect, - the connect function installed by PECL/mysqlnd_uh will be called. + so the connect function installed by PECL/mysqlnd_uh will be called. The functions installed by PECL/mysqlnd_uh are the methods of the built-in classes. The built-in PHP classes and their methods do nothing but call their - mysqlnd C library counterparts, to behave exaclty + mysqlnd C library counterparts, to behave exactly like the original mysqlnd function they replace. The code below illustrates in pseudo-code what the extension does. @@ -186,12 +179,11 @@ proxy::connect returns true By subclassing the classes you can install your own proxy to monitor mysqlnd. - Please, see How it works - for details. However, to get started you do not need to look at the details. - Copy the patterns shown in the quickstart instead. + See also the How it works + guide to learn about the inner workings of this extension. - Connections proxies are objects of the type MysqlndUhConnection. + Connection proxies are objects of the type MysqlndUhConnection. Connection proxy objects are installed by mysqlnd_uh_set_connection_proxy. If you install the built-in class MysqlndUhConnection @@ -213,7 +205,7 @@ $mysqli = new mysqli("localhost", "root", "", "test"); The PHP_INI_SYSTEM configuration setting mysqlnd_uh.enable - setting controls whether a proxy may be set. If disabled, the extension + controls whether a proxy may be set. If disabled, the extension will throw errors of type E_WARNING @@ -242,7 +234,7 @@ PHP Warning: mysqlnd_uh_set_connection_proxy(): (Mysqlnd User Handler) The plug - To monitor mysqlnd you have to write your own + To monitor mysqlnd, you have to write your own proxy object subclassing MysqlndUhConnection. Please, see the function reference for a the list of methods that can be subclassed. Alternatively, you can use reflection to inspect @@ -340,8 +332,8 @@ stmt_proxy::prepare(SELECT 'mysqlnd hacking made easy' AS _msg FROM DUAL) Combined with debug_print_backtrace it can become a powerful tool, for example, to find the origin of certain statement. This may be desired when searching for slow queries but also after database - refactorings to find code still accessing deprecated databases or - tables. The latter may be a complicated matter to do otherwise, if + refactoring to find code still accessing deprecated databases or + tables. The latter may be a complicated matter to do otherwise, especially if the application uses auto-generated queries.