sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-16 08:58:56 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Document new parameters in PDOStatement::fetch that allow for scrollable

Browse source 
cursors, and add an example of how to use scrollable cursors (finally!).
Add examples for the transaction functions.
Correct a typo in the constants.
Adopt more reference template goodness throughout.


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@178958 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Dan Scott 2005-02-05 18:52:58 +00:00
parent bab0381af9
commit 0c1bedcdde
9 changed files with 401 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
reference/pdo/constants.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<section id="pdo.constants">
&reftitle.constants;
@ -461,7 +461,7 @@
<listitem>
<simpara>
Create a PDOStatement object with a forward-only cursor. This may improve
the performance of your application but restricts your PROStatement object
the performance of your application but restricts your PDOStatement object
to fetching one row at a time from the result set in a forward direction.
</simpara>
</listitem>

44
reference/pdo/functions/PDO-beginTransaction.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-beginTransaction">
<refnamediv>
@ -8,8 +8,9 @@
Initiates a transaction
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PDO::beginTransaction</methodname>
<void/>
@ -21,6 +22,43 @@
autocommit mode.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Roll back a transaction</title>
<programlisting role='php'>
<![CDATA[
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();
/* Change the database schema and data */
$sth = $dbh->exec("DROP TABLE fruit");
$sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");
/* Recognize mistake and roll back changes */
$dbh->rollBack();
/* Database connection is now back in autocommit mode */
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::commit</function></member>
<member><function>PDO::rollBack</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

43
reference/pdo/functions/PDO-commit.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.1 $ -->
<!-- $Revision: 1.2 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-commit">
<refnamediv>
@ -8,8 +8,9 @@
Commits a transaction
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PDO::commit</methodname>
<void/>
@ -21,6 +22,42 @@
starts a new transaction.
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Commit a transaction</title>
<programlisting role='php'>
<![CDATA[
<?php
/* Begin a transaction, turning off autocommit */
$dbh->beginTransaction();
/* Change the database schema */
$sth = $dbh->exec("DROP TABLE fruit");
/* Commit the changes */
$dbh->commit();
/* Database connection is now back in autocommit mode */
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::beginTransaction</function></member>
<member><function>PDO::rollBack</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

8
reference/pdo/functions/PDO-construct.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<refentry id="function.PDO-construct">
<refnamediv>
<refname>PDO::__construct</refname>
@ -14,7 +14,7 @@
<methodparam><type>string</type><parameter>dsn</parameter></methodparam>
<methodparam><type>string</type><parameter>username</parameter></methodparam>
<methodparam><type>string</type><parameter>password</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>driver_opts</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>driver_options</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
<para>
@ -83,10 +83,10 @@
</para>
</listitem>
</varlistentry>
<varlistentry><term>driver_opts</term>
<varlistentry><term>driver_options</term>
<listitem>
<para>
A key =&gt; value array of driver-specific connection options.
A key=&gt;value array of driver-specific connection options.
</para>
</listitem>
</varlistentry>

45
reference/pdo/functions/PDO-prepare.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-prepare">
<refnamediv>
@ -8,11 +8,12 @@
Prepares a statement for execution and returns a statement object
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>PDOStatement</type><methodname>PDO::prepare</methodname>
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
<methodparam choice="opt"><type>array</type><parameter>driver_options</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
@ -41,6 +42,18 @@
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>driver_options</parameter></term>
<listitem>
<para>
This array holds one or more key=&gt;value pairs to set
attribute values for the PDOStatement object that this method
returns. You would most commonly use this to set the
<literal>PDO_ATTR_CURSOR</literal> value to
<literal>PDO_CURSOR_SCROLL</literal> to request a scrollable cursor.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
@ -55,26 +68,27 @@
<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Prepare an SQL statement with named parameters</title>
<programlisting role='php'>
<para>
<example><title>Prepare an SQL statement with named parameters</title>
<programlisting role='php'>
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of values */
$sth = $dbh->prepare('SELECT name, colour, calories
$sql = 'SELECT name, colour, calories
FROM fruit
WHERE calories < :calories AND colour = :colour');
WHERE calories < :calories AND colour = :colour'
$sth = $dbh->prepare($sql, array(PDO_ATTR_CURSOR, PDO_CURSOR_FWDONLY));
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
$red = $sth->fetchAll();
$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
$yellow = $sth->fetchAll();
?>
]]>
</programlisting>
</example>
<example>
<title>Prepare an SQL statement with question mark parameters</title>
<programlisting role='php'>
</programlisting>
</example>
<example>
<title>Prepare an SQL statement with question mark parameters</title>
<programlisting role='php'>
<![CDATA[
<?php
/* Execute a prepared statement by passing an array of values */
@ -87,8 +101,9 @@ $sth->execute(array(175, 'yellow'));
$yellow = $sth->fetchAll();
?>
]]>
</programlisting>
</example>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">

36
reference/pdo/functions/PDO-rollBack.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-rollBack">
<refnamediv>
@ -8,8 +8,9 @@
Rolls back a transaction
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>PDO::rollBack</methodname>
<void/>
@ -26,8 +27,13 @@
connection state to manual commit mode before issuing
<function>PDO::rollBack</function> has any effect.
</para>
<example><title>Roll back a transaction</title>
<programlisting role='php'>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Roll back a transaction</title>
<programlisting role='php'>
<![CDATA[
<?php
/* Begin a transaction, turning off autocommit */
@ -39,15 +45,27 @@ $sth = $dbh->exec("UPDATE dessert
SET name = 'hamburger'");
/* Recognize mistake and roll back changes */
$sth->rollBack();
$dbh->rollBack();
/* Database connection is now back in autocommit mode */
?>
]]>
</programlisting>
</example>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::beginTransaction</function></member>
<member><function>PDO::commit</function></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file

211
reference/pdo/functions/PDOStatement-fetch.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-fetch">
<refnamediv>
@ -8,53 +8,103 @@
Fetches the next row from a result set
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>PDOStatement::fetch</methodname>
<methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>cursor_orientation</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>cursor_offset</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
<para>
Fetches a row from a result set associated with a PDOStatement object.
</para>
<para>
<parameter>fetch_style</parameter> can be one of the following values:
<itemizedlist>
<listitem><para>
<literal>PDO_FETCH_ASSOC</literal>: returns an array indexed by column
name as returned in your result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_BOTH</literal> (default): returns an array indexed by
both column name and column number as returned in your result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_BOUND</literal>: returns &true; and assigns the
values of the columns in your result set to the PHP variables to which
they were bound with the <function>PDOStatement::bindParam</function>
method
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_LAZY</literal>: combines
<literal>PDO_FETCH_BOTH</literal> and <literal>PDO_FETCH_OBJ</literal>,
creating the object variable names as they are accessed
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_OBJ</literal>: returns an anonymous object with
property names that correspond to the column names returned in your
result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_NUM</literal>: returns an array indexed by column
number as returned in your result set, starting at column 0
</para></listitem>
</itemizedlist>
</para>
</refsect1>
<example><title>Fetching rows using different fetch styles</title>
<programlisting role="php">
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>fetch_style</parameter></term>
<listitem>
<para>
Controls how the next row will be returned to the caller. This value
must be one of the <literal>PDO_FETCH_*</literal> constants,
defaulting to <literal>PDO_FETCH_BOTH</literal>.
<itemizedlist>
<listitem><para>
<literal>PDO_FETCH_ASSOC</literal>: returns an array indexed by column
name as returned in your result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_BOTH</literal> (default): returns an array indexed by
both column name and column number as returned in your result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_BOUND</literal>: returns &true; and assigns the
values of the columns in your result set to the PHP variables to which
they were bound with the <function>PDOStatement::bindParam</function>
method
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_LAZY</literal>: combines
<literal>PDO_FETCH_BOTH</literal> and <literal>PDO_FETCH_OBJ</literal>,
creating the object variable names as they are accessed
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_OBJ</literal>: returns an anonymous object with
property names that correspond to the column names returned in your
result set
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_NUM</literal>: returns an array indexed by column
number as returned in your result set, starting at column 0
</para></listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cursor_orientation</parameter></term>
<listitem>
<para>
For a PDOStatement object representing a scrollable cursor, this
value determines which row will be returned to the caller. This value
must be one of the <literal>PDO_FETCH_ORI_*</literal> constants,
defaulting to <literal>PDO_FETCH_ORI_NEXT</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
For a PDOStatement object representing a scrollable cursor for which
the <literal>cursor_orientation</literal> parameter is set to
<literal>PDO_FETCH_ORI_ABS</literal>, this value specifies the
absolute number of the row in the result set that shall be fetched.
</para>
<para>
For a PDOStatement object representing a scrollable cursor for which
the <literal>cursor_orientation</literal> parameter is set to
<literal>PDO_FETCH_ORI_REL</literal>, this value specifies the
row to fetch relative to the cursor position before
<function>PDOStatement::fetch</function> was called.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Fetching rows using different fetch styles</title>
<programlisting role="php">
<![CDATA[
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
@ -86,10 +136,9 @@ print $result->NAME;
print("\n");
?>
]]>
</programlisting>
</example>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
PDO_FETCH_ASSOC: Return next row as an array indexed by column name
Array
@ -117,8 +166,82 @@ PDORow Object
PDO_FETCH_OBJ: Return next row as an anonymous object with column names as properties
kiwi
]]>
</screen>
</screen>
</example>
<example><title>Fetching rows with a scrollable cursor</title>
<programlisting role="php">
<![CDATA[
<?php
function readDataForwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
try {
$stmt = $dbh->prepare($sql, array(PDO_ATTR_CURSOR, PDO_CURSOR_SCROLL));
$stmt->execute();
while ($row = $stmt->fetch(PDO_FETCH_NUM, PDO_FETCH_ORI_NEXT)) {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
}
$stmt = null;
}
catch (PDOException $e) {
print $e->getMessage();
}
}
function readDataBackwards($dbh) {
$sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
try {
$stmt = $dbh->prepare($sql, array(PDO_ATTR_CURSOR, PDO_CURSOR_SCROLL));
$stmt->execute();
$row = $stmt->fetch(PDO_FETCH_NUM, PDO_FETCH_ORI_LAST);
do {
$data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
print $data;
} while ($row = $stmt->fetch(PDO_FETCH_NUM, PDO_FETCH_ORI_PRIOR));
$stmt = null;
}
catch (PDOException $e) {
print $e->getMessage();
}
}
print "Reading forwards:\n";
readDataForwards($conn);
print "Reading backwards:\n";
readDataBackwards($conn);
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Reading forwards:
21 10 5
16 0 5
19 20 10
Reading backwards:
19 20 10
16 0 5
21 10 5
]]>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::query</function></member>
<member><function>PDOStatement::fetchAll</function></member>
<member><function>PDOStatement::fetchSingle</function></member>
<member><function>PDOStatement::prepare</function></member>
<member><function>PDOStatement::setFetchMode</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

64
reference/pdo/functions/PDOStatement-fetchAll.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-fetchAll">
<refnamediv>
@ -8,22 +8,41 @@
Returns an array containing all of the result set rows
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>array</type><methodname>PDOStatement::fetchAll</methodname>
<methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>fetch_style</parameter></term>
<listitem>
<para>
Controls the contents of the returned array as documented in
<function>PDOStatement::fetch</function>. Defaults to
<literal>PDO_FETCH_BOTH</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>PDOStatement::fetchAll</function> returns an array containing
all of the remaining rows in the result set. The array represents each
row as either an array of column values or an object with properties
corresponding to each column name. <parameter>fetch_style</parameter>
controls the contents of the returned array as documented in
<function>PDOStatement::fetch</function>. <parameter>fetch_style</parameter>
defaults to <literal>PDO_FETCH_BOTH</literal>.
corresponding to each column name.
</para>
<para>
Using this method to fetch large result sets will result in a heavy
@ -33,9 +52,13 @@
SORT BY clauses in SQL to restrict results before retrieving and
processing them with PHP.
</para>
</refsect1>
<example><title>Fetch all remaining rows in a result set</title>
<programlisting role="php">
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Fetch all remaining rows in a result set</title>
<programlisting role="php">
<![CDATA[
<?php
$sth = $dbh->prepare("SELECT name, colour FROM fruit");
@ -47,9 +70,9 @@ $result = $sth->fetchAll();
print_r($result);
?>
]]>
</programlisting>
&example.outputs;
<screen>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
Fetch all of the remaining rows in the result set:
Array
@ -72,9 +95,22 @@ Array
)
]]>
</screen>
</example>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::query</function></member>
<member><function>PDOStatement::fetch</function></member>
<member><function>PDOStatement::fetchSingle</function></member>
<member><function>PDOStatement::prepare</function></member>
<member><function>PDOStatement::setFetchMode</function></member>
</simplelist>
</para>
</refsect1>
</refentry>

57
reference/pdo/functions/PDOStatement-fetchSingle.xml
View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-fetchSingle">
<refnamediv>
@ -8,25 +8,35 @@
Returns the first column in the next row of a result set
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>PDOStatement::fetchSingle</methodname>
<void/>
</methodsynopsis>
&warn.experimental.func;
<para>
<function>PDOStatement::fetchSingle</function> returns the first column
in the next row of a result set as a <literal>string</literal> value.
</para>
<warning>
<para>
There is no way to return the second or subsequent columns from a row
if you use this method to retrieve data.
</para>
</warning>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<function>PDOStatement::fetchSingle</function> returns the first column
in the next row of a result set as a <literal>string</literal> value.
</para>
<warning>
<para>
There is no way to return the second or subsequent columns from a row
if you use this method to retrieve data.
</para>
</warning>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example><title>Return first column of the next row</title>
<programlisting role="php">
<![CDATA[
@ -44,16 +54,29 @@ print("$result\n");
?>
]]>
</programlisting>
</example>
&example.outputs;
<screen>
&example.outputs;
<screen>
<![CDATA[
Fetch the first column from the next row in the result set:
lemon
orange
]]>
</screen>
</screen>
</example>
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>PDO::query</function></member>
<member><function>PDOStatement::fetch</function></member>
<member><function>PDOStatement::fetchAll</function></member>
<member><function>PDOStatement::prepare</function></member>
<member><function>PDOStatement::setFetchMode</function></member>
</simplelist>
</para>
</refsect1>
</refentry>