Slight rewording, and fixed a few typos

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@323933 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Philip Olson 2012-03-06 02:07:32 +00:00
parent debc49412f
commit 3506814b9b

View file

@ -209,8 +209,8 @@ Localhost via UNIX socket
</para>
<para>
Depending on the connection function used, assorted parameters
can be omitted. If a parameter is not given the extension attempts to
use defaults values set in the PHP configuration file.
can be omitted. If a parameter is not provided, then the extension attempts to
use the default values that are set in the PHP configuration file.
</para>
<para>
<example>
@ -228,29 +228,29 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
The resulting parameter values are then passed to the client library
used by the extension. If the client library detects empty or unset
parameters, it may default to library built-in values.
that is used by the extension. If the client library detects empty or unset
parameters, then it may default to the library built-in values.
</para>
<para>
<emphasis role="bold">Built-in connection library defaults</emphasis>
</para>
<para>
If the host value is unset or empty, the client library will
default to a Unix socket connection on <literal>localhost</literal>.
If socket is unset or empty and a Unix socket connection is requested,
a connection to the default socket on <literal>/tmp/mysql.sock</literal>
If the host value is unset or empty, then the client library will
default to a Unix socket connection on <literal>localhost</literal>.
If socket is unset or empty, and a Unix socket connection is requested,
then a connection to the default socket on <literal>/tmp/mysql.sock</literal>
is attempted.
</para>
<para>
On Windows systems the host name <literal>.</literal> is interpreted
On Windows systems, the host name <literal>.</literal> is interpreted
by the client library as an attempt to open a Windows named pipe based
connection. In this case the socket parameter is interpreted as the pipes
name. If not given or empty, the socket (here: pipe name) defaults to
connection. In this case the socket parameter is interpreted as the pipe
name. If not given or empty, then the socket (pipe name) defaults to
<literal>\\.\pipe\MySQL</literal>.
</para>
<para>
If neither a Unix domain socket based not a Windows named pipe based connection
is to be bestablished and the port parameter value is unset, the library
is to be be established and the port parameter value is unset, the library
will default to port <literal>3306</literal>.
</para>
<para>
@ -261,16 +261,16 @@ mysqli.default_socket=/tmp/mysql.sock
<emphasis role="bold">Connection options</emphasis>
</para>
<para>
Various connection options are available, for example, to set
init commands which are executed upon connect or, for requesting use of
Connection options are available to, for example, set
init commands which are executed upon connect, or for requesting use of
a certain charset. Connection options must be set before a network
connection is established.
</para>
<para>
For setting a connection option the connect operation has to be
For setting a connection option, the connect operation has to be
performed in three steps: creating a connection handle with
<function>mysqli_init</function>, setting the requested options using
<function>mysqli_options</function> and establishing the network
<function>mysqli_options</function>, and establishing the network
connection with <function>mysqli_real_connect</function>.
</para>
<para>
@ -278,7 +278,7 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
The mysqli extension supports persistent database connections, which
are a special kind of pooled connections. By default every database
are a special kind of pooled connections. By default, every database
connection opened by a script is either explicitly closed by the user during
runtime or released automatically at the end of the script. A persistent
connection is not. Instead it is put into a pool for later reuse, if
@ -287,7 +287,7 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
Every PHP process is using its own mysqli connection pool.
Depending on the web server deployment model a PHP process may serve
Depending on the web server deployment model, a PHP process may serve
one or multiple requests. Therefore, a pooled connection may be used
by one or more scripts subsequently.
</para>
@ -295,9 +295,9 @@ mysqli.default_socket=/tmp/mysql.sock
<emphasis role="bold">Persistent connection</emphasis>
</para>
<para>
If no unused persistent connection for a given combination of host, username,
password, socket, port and default database can be found in the connection pool,
mysqli opens a new connection. The use of persistent connections can be
If a unused persistent connection for a given combination of host, username,
password, socket, port and default database can not be found in the connection pool,
then mysqli opens a new connection. The use of persistent connections can be
enabled and disabled using the PHP directive <literal>mysqli.allow_persistent</literal>.
The total number of connections opened by a script can be limited with
<literal>mysqli.max_links</literal>. The maximum number of persistent connections
@ -306,7 +306,7 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
A common complain about persistent connections is that their state is
not reset before reuse. For example, open, unfinished transactions are not
not reset before reuse. For example, open and unfinished transactions are not
automatically rolled back. But also, authorization changes which happened
in the time between putting the connection into the pool and reusing it
are not reflected. This may be seen as an unwanted side-effect. On the contrary,
@ -315,11 +315,11 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
The mysqli extension supports both interpretations of a persistent connection:
state persisted and state reset before reuse. The default is reset.
state persisted, and state reset before reuse. The default is reset.
Before a persistent connection is reused, the mysqli extension implicitly
calls <function>mysqli_change_user</function> to reset the state. The
persistent connection appears to the user as if it was just opened. No
artefacts from previous usages are visible.
artifacts from previous usages are visible.
</para>
<para>
The <function>mysqli_change_user</function> function is an expensive operation.
@ -327,10 +327,9 @@ mysqli.default_socket=/tmp/mysql.sock
compile flag <literal>MYSQLI_NO_CHANGE_USER_ON_PCONNECT</literal> being set.
</para>
<para>
It is left to the user to choose between safe behaviour and best performance.
Both are valid optimization goals. For ease of use, the safe behaviour has
been made the default at the expense of maximum performance. Please, run your
own benchmarks to measure the performance impact for your work load.
It is left to the user to choose between safe behavior and best performance.
Both are valid optimization goals. For ease of use, the safe behavior has
been made the default at the expense of maximum performance.
</para>
<para>
<emphasis role="bold">See also</emphasis>
@ -351,11 +350,11 @@ mysqli.default_socket=/tmp/mysql.sock
<section xml:id="mysqli.quickstart.statements">
<title>Executing statements</title>
<para>
Statements can be executed by help of the
Statements can be executed with the
<function>mysqli_query</function>, <function>mysqli_real_query</function>
and <function>mysqli_multi_query</function> function.
and <function>mysqli_multi_query</function> functions.
The <function>mysqli_query</function> function is the most
commonly used one. It combines executing statement and doing a
common, and combines the executing statement with a
buffered fetch of its result set, if any, in one call.
Calling <function>mysqli_query</function> is identical to
calling <function>mysqli_real_query</function>
@ -363,7 +362,7 @@ mysqli.default_socket=/tmp/mysql.sock
</para>
<para>
The <function>mysqli_multi_query</function> function is used
with Multiple Statements and is described elsewhere.
with multiple statements.
</para>
<para>
<example>
@ -400,7 +399,7 @@ if (!$mysqli->query("DROP TABLE IF EXISTS test") ||
</para>
<para>
PHP applications can navigate freely through buffered results.
Nagivation is fast because the result sets is hold in client memory.
Navigation is fast because the result sets are held in client memory.
Please, keep in mind that it is often easier to scale by client than
it is to scale the server.
</para>
@ -486,7 +485,7 @@ while ($row = $res->fetch_assoc()) {
<para>
The <function>mysqli_query</function>, <function>mysqli_real_query</function>
and <function>mysqli_multi_query</function> functions are used to execute
non-prepared statements. At the level of the MySQL Client Server Protocol
non-prepared statements. At the level of the MySQL Client Server Protocol,
the command <literal>COM_QUERY</literal> and the text protocol are used
for statement execution. With the text protocol, the MySQL server converts
all data of a result sets into strings before sending. This conversion is done
@ -532,7 +531,7 @@ label = a (string)
<para>
It is possible to convert integer and float columns back to PHP numbers by setting the
<literal>MYSQLI_OPT_INT_AND_FLOAT_NATIVE</literal> connection option,
if using the mysqlnd libary. If set, the mysqlnd library will
if using the mysqlnd library. If set, the mysqlnd library will
check the result set meta data column types and convert numeric SQL columns
to PHP numbers, if the PHP data type value range allows for it.
This way, for example, SQL INT columns are returned as integers.
@ -762,7 +761,7 @@ array(4) {
</para>
<para>
Also, consider the use of the MySQL multi-INSERT SQL syntax for INSERTs.
For the example, belows multi-INSERT requires less round-trips between
For the example, multi-INSERT requires less round-trips between
the server and client than the prepared statement shown above.
</para>
<para>
@ -790,7 +789,7 @@ if (!$mysqli->query("INSERT INTO test(id) VALUES (1), (2), (3), (4)")) {
strings before sending. The client libraries do not receive strings only.
Instead, they will receive binary data and try to convert the values into
appropriate PHP data types. For example, results from an SQL
<literal>INT</literal> column will be provided as PHP integer variables.
<literal>INT</literal> column will be provided as PHP integer variables.
</para>
<para>
<example>
@ -829,7 +828,7 @@ label = a (string)
</example>
</para>
<para>
This behaviour differes from non-prepared statements. By default,
This behavior differs from non-prepared statements. By default,
non-prepared statements return all results as strings.
This default can be changed using a connection option.
If the connection option is used, there are no differences.
@ -839,7 +838,7 @@ label = a (string)
</para>
<para>
Results from prepared statements can either be retrieved by
binding output variables or by requesting a mysqli_result object.
binding output variables, or by requesting a mysqli_result object.
</para>
<para>
Output variables must be bound after statement execution.
@ -961,7 +960,7 @@ array(1) {
</example>
</para>
<para>
Using the mysqli_result interface this has the additional benefit of
Using the mysqli_result interface offers the additional benefit of
flexible client-side result set navigation.
</para>
<para>
@ -1032,13 +1031,13 @@ array(2) {
<para>
Bound variables will be escaped automatically by the server. The server
inserts their escaped values at the appropriate places into the statement
template before execution. Users must hint the server about the type of the
bound variable for appropriate conversion,
see <function>mysqli_stmt_bind_param</function>.
template before execution. A hint must be provided to the server for the type of
bound variable, to create an appropriate conversion.
See the <function>mysqli_stmt_bind_param</function> function for more information.
</para>
<para>
The automatic escaping of values within the server is sometimes considered
as a security feature to prevent SQL injection. The same degree of security
a security feature to prevent SQL injection. The same degree of security
can be achieved with non-prepared statements, if input values are
escaped correctly.
</para>
@ -1046,13 +1045,13 @@ array(2) {
<emphasis role="bold">Client-side prepared statement emulation</emphasis>
</para>
<para>
The API does not include a client-side prepared statement emulation.
The API does not include emulation for client-side prepared statement emulation.
</para>
<para>
<emphasis role="bold">Quick prepared - non-prepared statement comparison</emphasis>
</para>
<para>
The below table gives a quick comparison on server-side prepared and non-prepared statements.
The table below compares server-side prepared and non-prepared statements.
</para>
<informaltable>
<tgroup cols="3">
@ -1086,49 +1085,49 @@ array(2) {
</row>
<row>
<entry>Input parameter binding API</entry>
<entry>yes, automatic input escaping</entry>
<entry>no, manual input escaping</entry>
<entry>Yes, automatic input escaping</entry>
<entry>No, manual input escaping</entry>
</row>
<row>
<entry>Output variable binding API</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Supports use of mysqli_result API</entry>
<entry>yes, use <function>mysqli_stmt_get_result</function></entry>
<entry>yes</entry>
<entry>Yes, use <function>mysqli_stmt_get_result</function></entry>
<entry>Yes</entry>
</row>
<row>
<entry>Buffered result sets</entry>
<entry>
yes, use <function>mysqli_stmt_get_result()</function> or
Yes, use <function>mysqli_stmt_get_result()</function> or
binding with <function>mysqli_stmt_store_result</function>
</entry>
<entry>yes, default of <function>mysqli_query</function></entry>
<entry>Yes, default of <function>mysqli_query</function></entry>
</row>
<row>
<entry>Unbuffered result sets</entry>
<entry>yes, use output binding API</entry>
<entry>Yes, use output binding API</entry>
<entry>
yes, use <function>mysqli_real_query</function> with
Yes, use <function>mysqli_real_query</function> with
<function>mysqli_use_result</function>
</entry>
</row>
<row>
<entry>MySQL Client Server protocol data transfer flavour</entry>
<entry>binary protocol</entry>
<entry>text protocol</entry>
<entry>Binary protocol</entry>
<entry>Text protocol</entry>
</row>
<row>
<entry>Result set values SQL data types</entry>
<entry>preserved when fetching</entry>
<entry>converted to string or preserved when fetching</entry>
<entry>Preserved when fetching</entry>
<entry>Converted to string or preserved when fetching</entry>
</row>
<row>
<entry>Supports all SQL statements</entry>
<entry>Recent MySQL versions support most but not all</entry>
<entry>yes</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
@ -1479,7 +1478,7 @@ do {
<para>
Multiple statements or multi queries must be executed
with <function>mysqli_multi_query</function>. The individual statements
of the statement string are seperated by semicolon.
of the statement string are separated by semicolon.
Then, all result sets returned by the executed statements must be fetched.
</para>
<para>
@ -1555,7 +1554,7 @@ array(1) {
</para>
<para>
<example>
<title>SQL ijnection</title>
<title>SQL Injection</title>
<programlisting role="php">
<![CDATA[
<?php
@ -1570,7 +1569,9 @@ if (!$res) {
&example.outputs;
<screen>
<![CDATA[
Error executing query: (1064) You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'DROP TABLE mysq.user' at line 1
Error executing query: (1064) You have an error in your SQL syntax;
check the manual that corresponds to your MySQL server version for the right syntax
to use near 'DROP TABLE mysql.user' at line 1
]]>
</screen>
</example>
@ -1597,13 +1598,13 @@ Error executing query: (1064) You have an error in your SQL syntax; check the ma
<title>API support for transactions</title>
<para>
The MySQL server supports transactions depending on the storage engine used.
Since MySQL [TODO]x.y[TODO] the default storage engine is InnoDB.
Since MySQL 5.5, the default storage engine is InnoDB.
InnoDB has full ACID transaction support.
</para>
<para>
Transactions can either be controlled using SQL or API calls.
It is recommended to use API calls for enabling and disabling the
auto commit mode and for comitting and rolling back transactions.
auto commit mode and for committing and rolling back transactions.
</para>
<para>
<example>
@ -1675,7 +1676,7 @@ $mysqli->commit();
A MySQL result set contains metadata. The metadata describes the columns
found in the result set. All metadata send by MySQL is accessible
through the <literal>mysqli</literal> interface.
The extension performs no or negliable changes to the
The extension performs no or negligible changes to the
information it receives.
Differences between MySQL server versions are not aligned.
</para>