[DOC-CVS] [doc-en] master: mysqlinfo : fix XML by converting para to simpara tags via script
[email protected] (Gina Peter Banyard)
| Newsgroups | php.doc.cvs |
|---|---|
| Message-ID | <[email protected]> |
Author: Gina Peter Banyard (Girgias)
Date: 2026-01-19T03:27:07Z
Commit: https://github.com/php/doc-en/commit/7cff4d34f0324c9de72d15957e1b62e20f37dfaf
Raw diff: https://github.com/php/doc-en/commit/7cff4d34f0324c9de72d15957e1b62e20f37dfaf.diff
mysqlinfo : fix XML by converting para to simpara tags via script
Changed paths:
M reference/mysqlinfo/concepts.xml
M reference/mysqlinfo/set.xml
Diff:
diff --git a/reference/mysqlinfo/concepts.xml b/reference/mysqlinfo/concepts.xml
index a3794654d03e..9b8f11597db1 100644
--- a/reference/mysqlinfo/concepts.xml
+++ b/reference/mysqlinfo/concepts.xml
@@ -1,16 +1,16 @@
<?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision$ -->
-<chapter xml:id="mysqlinfo.concepts" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+<!-- $Revision$ -->
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="mysqlinfo.concepts">
<title>Concepts</title>
- <para>
+ <simpara>
These concepts are specific to the MySQL drivers for PHP.
- </para>
+ </simpara>
<section xml:id="mysqlinfo.concepts.buffering">
<title>Buffered and Unbuffered queries</title>
-
- <para>
- Queries are using the buffered mode by default. This means that query results are
+
+ <simpara>
+ Queries are using the buffered mode by default. This means that query results are
immediately transferred from the MySQL Server to PHP and then are kept in the memory
of the PHP process. This allows additional operations like counting the
number of rows, and moving (seeking) the current result pointer. It also allows
@@ -20,45 +20,45 @@
result set are unset or the result set was explicitly freed, which will automatically
happen during request end at the latest. The terminology "store result" is also used
for buffered mode, as the whole result set is stored at once.
- </para>
+ </simpara>
<note>
- <para>
+ <simpara>
When using libmysqlclient as library PHP's memory limit won't count the memory used
for result sets unless the data is fetched into PHP variables. With mysqlnd
the memory accounted for will include the full result set.
- </para>
+ </simpara>
</note>
-
- <para>
+
+ <simpara>
Unbuffered MySQL queries execute the query and then wait
for the data from the MySQL server to be fetched. This uses less memory
on the PHP-side, but can increase the load on the server. Unless the full result set was
fetched from the server no further queries can be sent over the same connection. Unbuffered
queries can also be referred to as "use result". Once all rows in the result set
are fetched, the result set is gone and it cannot be iterated again.
- </para>
+ </simpara>
- <para>
+ <simpara>
Following these characteristics, unbuffered queries should be used only
when a large result set is expected that will be processed sequentially.
Unbuffered queries contain a number of pitfalls that makes it more
difficult to use them, e.g. the number of rows in the result set is unknown
until the last row is fetched.
Buffered queries are the easier and more flexible way to process result sets.
- </para>
-
+ </simpara>
+
<!-- @TODO
- Add list of issues people run into with unbuffered queries
- Add list of specific use cases for when unbuffered queries are useful
- Question: Unbuffered queries still require all rows to be returned or resource free before executing another? Applies to all extensions?
- Show "free_result" functions / unset usage with buffered queries 8double-check with Andrey on mysqlnd optimizations
-->
-
- <para>
+
+ <simpara>
Because buffered queries are the default, the examples below will demonstrate how to
execute unbuffered queries with each API.
- </para>
+ </simpara>
<example>
<title>Unbuffered query example: mysqli</title>
@@ -97,23 +97,23 @@ foreach ($unbufferedResult as $row) {
<section xml:id="mysqlinfo.concepts.charset">
<title>Character sets</title>
- <para>
+ <simpara>
Ideally a proper character set will be set at the server level, and doing this is described
within the <link xlink:href="&url.mysql.charsets.config;">Character Set Configuration</link>
- section of the MySQL Server manual. Alternatively, each MySQL API offers a method to set
+ section of the MySQL Server manual. Alternatively, each MySQL API offers a method to set
the character set at runtime.
- </para>
+ </simpara>
<caution>
<title>The character set and character escaping</title>
- <para>
+ <simpara>
The character set should be understood and defined, as it has an affect on every
action, and includes security implications. For example, the escaping mechanism
(e.g., <function>mysqli_real_escape_string</function> for mysqli and <methodname>PDO::quote</methodname> for PDO_MySQL) will adhere to
this setting. It is important to realize that these functions will not use the character
set that is defined with a query, so for example the following will not have an effect
on them:
- </para>
+ </simpara>
</caution>
<example>
@@ -140,18 +140,18 @@ $mysqli->set_charset('UTF-8');
</programlisting>
</example>
- <para>
+ <simpara>
Below are examples that demonstrate how to properly alter the character set at runtime
using each API.
- </para>
-
+ </simpara>
+
<note>
<title>Possible UTF-8 confusion</title>
- <para>
- Because character set names in MySQL do not contain dashes, the string
- "utf8" is valid in MySQL to set the character set to UTF-8 (up to 3 byte UTF-8 Unicode Encoding). The string
+ <simpara>
+ Because character set names in MySQL do not contain dashes, the string
+ "utf8" is valid in MySQL to set the character set to UTF-8 (up to 3 byte UTF-8 Unicode Encoding). The string
"UTF-8" is not valid, as using "UTF-8" will fail to change the character set and will throw an error.
- </para>
+ </simpara>
</note>
<example>
diff --git a/reference/mysqlinfo/set.xml b/reference/mysqlinfo/set.xml
index aa6bea68d1c1..4d3a828e89ad 100644
--- a/reference/mysqlinfo/set.xml
+++ b/reference/mysqlinfo/set.xml
@@ -5,15 +5,15 @@
<info xml:id="mysqlinfo.info">
<abstract>
- <para>
+ <simpara>
PHP offers several MySQL drivers and plugins for accessing and
handling MySQL.
- </para>
- <para>
+ </simpara>
+ <simpara>
The differences and functionality of the MySQL extensions are described
within the overview of this section.
- </para>
- <para>
+ </simpara>
+ <simpara>
The extensions listed support the MySQL protocol.
Examples of compatible database servers are
<link xlink:href="&url.mariadb;">MariaDB Server</link>,
@@ -21,7 +21,7 @@
<link xlink:href="&url.perconaserver;">Percona Server for MySQL</link>,
and
<link xlink:href="&url.tidb;">TiDB</link>.
- </para>
+ </simpara>
</abstract>
</info>
@@ -30,13 +30,13 @@
<preface xml:id="mysqlinfo.intro">
<title>Introduction</title>
- <para>
+ <simpara>
There are several PHP APIs
for accessing the MySQL database. Users can choose between the
<link linkend="book.mysqli">mysqli</link> or
<link linkend="ref.pdo-mysql">PDO_MySQL</link> extensions.
- </para>
- <para>
+ </simpara>
+ <simpara>
This guide explains the
<link linkend="mysqlinfo.terminology">terminology</link> used to describe
each API, information about
@@ -44,56 +44,56 @@
use, and also information to help choose which MySQL
<link linkend="mysqlinfo.library.choosing">library to use</link> with
the API.
- </para>
+ </simpara>
</preface>
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="mysqlinfo.terminology">
<title>Terminology overview</title>
- <para>
+ <simpara>
This section provides an introduction to the options available to
you when developing a PHP application that needs to interact with a
MySQL database.
- </para>
+ </simpara>
- <para>
+ <simpara>
<emphasis role="bold">What is an API?</emphasis>
- </para>
+ </simpara>
- <para>
+ <simpara>
An Application Programming Interface, or API, defines the classes,
methods, functions and variables that your application will need to
call in order to carry out its desired task. In the case of PHP
applications that need to communicate with databases the necessary
APIs are usually exposed via PHP extensions.
- </para>
+ </simpara>
- <para>
+ <simpara>
APIs can be procedural or object-oriented. With a procedural API you
call functions to carry out tasks, with the object-oriented API you
instantiate classes and then call methods on the resulting objects.
Of the two, the latter is usually the preferred interface, as it is
more modern and leads to better organized code.
- </para>
+ </simpara>
- <para>
+ <simpara>
When writing PHP applications that need to connect to the MySQL
server there are several API options available. This document
discusses what is available and how to select the best solution for
your application.
- </para>
+ </simpara>
- <para>
+ <simpara>
<emphasis role="bold">What is a Connector?</emphasis>
- </para>
+ </simpara>
- <para>
+ <simpara>
In the MySQL documentation, the term <emphasis>connector</emphasis>
refers to a piece of software that allows your application to
connect to the MySQL database server. MySQL provides connectors for
a variety of languages, including PHP.
- </para>
+ </simpara>
- <para>
+ <simpara>
If your PHP application needs to communicate with a database server
you will need to write PHP code to perform such activities as
connecting to the database server, querying the database and other
@@ -103,76 +103,76 @@
possibly using other intermediate libraries where necessary. This
software is known generically as a connector, as it allows your
application to <emphasis>connect</emphasis> to a database server.
- </para>
+ </simpara>
- <para>
+ <simpara>
<emphasis role="bold">What is a Driver?</emphasis>
- </para>
+ </simpara>
- <para>
+ <simpara>
A driver is a piece of software designed to communicate with a
specific type of database server. The driver may also call a
library, such as the MySQL Client Library or the MySQL Native
Driver. These libraries implement the low-level protocol used to
communicate with the MySQL database server.
- </para>
+ </simpara>
- <para>
+ <simpara>
By way of an example, the <link linkend="mysqli.overview.pdo">PHP
Data Objects (PDO)</link> database abstraction layer may use one of
several database-specific drivers. One of the drivers it has
available is the PDO MYSQL driver, which allows it to interface with
the MySQL server.
- </para>
+ </simpara>
- <para>
+ <simpara>
Sometimes people use the terms connector and driver interchangeably,
this can be confusing. In the MySQL-related documentation the term
<quote>driver</quote> is reserved for software that provides
the database-specific part of a connector package.
- </para>
+ </simpara>
- <para>
+ <simpara>
<emphasis role="bold">What is an Extension?</emphasis>
- </para>
+ </simpara>
- <para>
+ <simpara>
In the PHP documentation, you will come across another term -
<emphasis>extension</emphasis>. The PHP code consists of a core,
with optional extensions to the core functionality. PHP's
MySQL-related extension, <literal>mysqli</literal>, is
implemented using the PHP extension framework.
- </para>
+ </simpara>
- <para>
+ <simpara>
An extension typically exposes an API to the PHP programmer, to
allow its facilities to be used programmatically. However, some
extensions which use the PHP extension framework do not expose an
API to the PHP programmer.
- </para>
+ </simpara>
- <para>
+ <simpara>
The PDO MySQL driver extension, for example, does not expose an API
to the PHP programmer, but provides an interface to the PDO layer
above it.
- </para>
+ </simpara>
- <para>
+ <simpara>
The terms API and extension should not be taken to mean the same
thing, as an extension may not necessarily expose an API to the
programmer.
- </para>
+ </simpara>
</chapter>
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="mysqlinfo.api.choosing">
<title>Choosing an API</title>
- <para>
+ <simpara>
PHP offers different APIs to connect to MySQL. Below we show
the APIs provided by the mysqli and PDO extensions. Each code snippet
creates a connection to a MySQL server running on "example.com" using
the username "user" and the password "password". And a query is run to
greet the user.
- </para>
+ </simpara>
<example>
<title>Comparing the MySQL APIs</title>
<programlisting role="php">
@@ -214,15 +214,15 @@ echo htmlentities($row['District']);
]]>
</programlisting>
</example>
- <para>
+ <simpara>
<emphasis role="bold">Feature comparison</emphasis>
- </para>
- <para>
+ </simpara>
+ <simpara>
The overall performance of both extensions is considered to be about
the same. Although the performance of the extension contributes only a
fraction of the total run time of a PHP web request. Often, the impact is
as low as 0.1%.
- </para>
+ </simpara>
<informaltable xml:id="mysqlinfo.api.choosing.changelog">
<tgroup cols="3">
<thead>
@@ -325,19 +325,19 @@ echo htmlentities($row['District']);
<chapter xmlns="http://docbook.org/ns/docbook" xml:id="mysqlinfo.library.choosing">
<title>Choosing a library</title>
- <para>
+ <simpara>
The mysqli and PDO_MySQL PHP extensions are lightweight wrappers on
top of a C client library. The extensions can either use the
<link linkend="book.mysqlnd">mysqlnd</link> library or the <literal>libmysqlclient</literal>
library. Choosing a library is a compile time decision.
- </para>
- <para>
+ </simpara>
+ <simpara>
The mysqlnd library is part of the PHP distribution. It offers
features like lazy connections and query caching, features that are not available
with libmysqlclient, so using the built-in mysqlnd library is highly recommended.
See the <link linkend="book.mysqlnd">mysqlnd documentation</link> for
additional details, and a listing of features and functionality that it offers.
- </para>
+ </simpara>
<example>
<title>Configure commands for using mysqlnd or libmysqlclient</title>
<programlisting role="shell">
@@ -353,14 +353,14 @@ $ ./configure --with-mysqli=/path/to/mysql_config --with-pdo-mysql=/path/to/mysq
]]>
</programlisting>
</example>
- <para>
+ <simpara>
<emphasis role="bold">Library feature comparison</emphasis>
- </para>
- <para>
+ </simpara>
+ <simpara>
It is recommended to use the <link linkend="book.mysqlnd">mysqlnd</link>
library instead of the MySQL Client Server library (libmysqlclient). Both
libraries are supported and constantly being improved.
- </para>
+ </simpara>
<informaltable xml:id="mysqlinfo.library.choosing.changelog">
<tgroup cols="3">
<thead>