reference/pdo/pdostatement/execute.xml
082ddc19f53e6e254010de1a1fbbe485ff744ec1
082ddc19f53e6e254010de1a1fbbe485ff744ec1
...
...
@@ -1,4 +1,4 @@
1
-
<?xml version="1.0" encoding="UTF-8"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
3
<refentry xml:id="pdostatement.execute" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
...
...
@@ -9,18 +9,22 @@
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<type>bool</type><methodname>PDOStatement::execute</methodname>
14
-
<methodparam choice="opt"><type>array</type><parameter>input_parameters</parameter></methodparam>
12
+
<methodsynopsis role="PDOStatement">
13
+
<modifier>public</modifier> <type>bool</type><methodname>PDOStatement::execute</methodname>
14
+
<methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>params</parameter><initializer>&null;</initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
Execute the prepared statement. If the prepared statement included
18
-
parameter markers, you must either:
17
+
Execute the <link linkend="pdo.prepared-statements">prepared
18
+
statement</link>. If the prepared statement included parameter markers, either:
19
19
<itemizedlist>
20
-
<listitem><para>call <function>PDOStatement::bindParam</function> to bind PHP variables
21
-
to the parameter markers: bound variables pass their value as input and receive the
22
-
output value, if any, of their associated parameter markers</para></listitem>
23
-
<listitem><para>or pass an array of input-only parameter values</para></listitem>
20
+
<listitem><para><methodname>PDOStatement::bindParam</methodname> and/or
21
+
<methodname>PDOStatement::bindValue</methodname> has to be called to bind either variables or
22
+
values (respectively) to the parameter markers. Bound variables pass
23
+
their value as input and receive the output value, if any, of their
24
+
associated parameter markers</para></listitem>
25
+
<listitem>
26
+
<para>or an array of input-only parameter values has to be passed</para>
27
+
</listitem>
24
28
</itemizedlist>
25
29
</para>
26
30
</refsect1>
...
...
@@ -30,7 +34,7 @@
30
34
<para>
31
35
<variablelist>
32
36
<varlistentry>
33
-
<term><parameter>input_parameters</parameter></term>
37
+
<term><parameter>params</parameter></term>
34
38
<listitem>
35
39
<para>
36
40
An array of values with as many elements as there are bound
...
...
@@ -38,13 +42,13 @@
38
42
All values are treated as <constant>PDO::PARAM_STR</constant>.
39
43
</para>
40
44
<para>
41
-
You cannot bind multiple values to a single parameter; for example,
42
-
you cannot bind two values to a single named parameter in an IN()
45
+
Multiple values cannot be bound to a single parameter; for example,
46
+
it is not allowed to bind two values to a single named parameter in an IN()
43
47
clause.
44
48
</para>
45
49
<para>
46
-
You cannot bind more values than specified; if more keys exist in
47
-
<parameter>input_parameters</parameter> than in the SQL specified
50
+
Binding more values than specified is not possible; if more keys exist in
51
+
<parameter>params</parameter> than in the SQL specified
48
52
in the <methodname>PDO::prepare</methodname>, then the statement will
49
53
fail and an error is emitted.
50
54
</para>
...
...
@@ -61,52 +65,33 @@
61
65
</para>
62
66
</refsect1>
63
67
64
-
<refsect1 role="changelog">
65
-
&reftitle.changelog;
66
-
<para>
67
-
<informaltable>
68
-
<tgroup cols="2">
69
-
<thead>
70
-
<row>
71
-
<entry>&Version;</entry>
72
-
<entry>&Description;</entry>
73
-
</row>
74
-
</thead>
75
-
<tbody>
76
-
<row>
77
-
<entry>5.2.0</entry>
78
-
<entry>
79
-
The keys from <parameter>input_parameters</parameter> must match the ones
80
-
declared in the SQL. Before PHP 5.2.0 this was silently ignored.
81
-
</entry>
82
-
</row>
83
-
</tbody>
84
-
</tgroup>
85
-
</informaltable>
86
-
</para>
68
+
<refsect1 role="errors">
69
+
&reftitle.errors;
70
+
&pdo.errors;
87
71
</refsect1>
88
72
89
73
<refsect1 role="examples">
90
74
&reftitle.examples;
91
-
<example><title>Execute a prepared statement with bound variables</title>
75
+
<example><title>Execute a prepared statement with a bound variable and value</title>
92
76
<programlisting role="php">
93
77
<![CDATA[
94
78
<?php
95
-
/* Execute a prepared statement by binding PHP variables */
79
+
/* Execute a prepared statement by binding a variable and value */
96
80
$calories = 150;
97
-
$colour = 'red';
81
+
$colour = 'gre';
98
82
$sth = $dbh->prepare('SELECT name, colour, calories
99
83
FROM fruit
100
-
WHERE calories < :calories AND colour = :colour');
101
-
$sth->bindParam(':calories', $calories, PDO::PARAM_INT);
102
-
$sth->bindParam(':colour', $colour, PDO::PARAM_STR, 12);
84
+
WHERE calories < :calories AND colour LIKE :colour');
85
+
$sth->bindParam('calories', $calories, PDO::PARAM_INT);
86
+
/* Names can be prefixed with colons ":" too (optional) */
87
+
$sth->bindValue(':colour', "%$colour%");
103
88
$sth->execute();
104
89
?>
105
90
]]>
106
91
</programlisting>
107
92
</example>
108
93
109
-
<example><title>Execute a prepared statement with an array of insert values (named parameters)</title>
94
+
<example><title>Execute a prepared statement with an array of named values</title>
110
95
<programlisting role="php">
111
96
<![CDATA[
112
97
<?php
...
...
@@ -116,13 +101,15 @@ $colour = 'red';
116
101
$sth = $dbh->prepare('SELECT name, colour, calories
117
102
FROM fruit
118
103
WHERE calories < :calories AND colour = :colour');
104
+
$sth->execute(array('calories' => $calories, 'colour' => $colour));
105
+
/* Array keys can be prefixed with colons ":" too (optional) */
119
106
$sth->execute(array(':calories' => $calories, ':colour' => $colour));
120
107
?>
121
108
]]>
122
109
</programlisting>
123
110
</example>
124
111
125
-
<example><title>Execute a prepared statement with an array of insert values (placeholders)</title>
112
+
<example><title>Execute a prepared statement with an array of positional values</title>
126
113
<programlisting role="php">
127
114
<![CDATA[
128
115
<?php
...
...
@@ -138,7 +125,7 @@ $sth->execute(array($calories, $colour));
138
125
</programlisting>
139
126
</example>
140
127
141
-
<example><title>Execute a prepared statement with question mark placeholders</title>
128
+
<example><title>Execute a prepared statement with variables bound to positional placeholders</title>
142
129
<programlisting role="php">
143
130
<![CDATA[
144
131
<?php
...
...
@@ -195,17 +182,16 @@ $sth->execute($params);
195
182
&reftitle.seealso;
196
183
<para>
197
184
<simplelist>
198
-
<member><function>PDO::prepare</function></member>
199
-
<member><function>PDOStatement::bindParam</function></member>
200
-
<member><function>PDOStatement::fetch</function></member>
201
-
<member><function>PDOStatement::fetchAll</function></member>
202
-
<member><function>PDOStatement::fetchColumn</function></member>
185
+
<member><methodname>PDO::prepare</methodname></member>
186
+
<member><methodname>PDOStatement::bindParam</methodname></member>
187
+
<member><methodname>PDOStatement::fetch</methodname></member>
188
+
<member><methodname>PDOStatement::fetchAll</methodname></member>
189
+
<member><methodname>PDOStatement::fetchColumn</methodname></member>
203
190
</simplelist>
204
191
</para>
205
192
</refsect1>
206
193
207
194
</refentry>
208
-
209
195
<!-- Keep this comment at the end of the file
210
196
Local variables:
211
197
mode: sgml
212
198