reference/pdo/pdo/prepare.xml
082ddc19f53e6e254010de1a1fbbe485ff744ec1
082ddc19f53e6e254010de1a1fbbe485ff744ec1
...
...
@@ -9,15 +9,15 @@
9
9
</refnamediv>
10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
-
<methodsynopsis>
13
-
<modifier>public</modifier> <type>PDOStatement</type><methodname>PDO::prepare</methodname>
14
-
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
15
-
<methodparam choice="opt"><type>array</type><parameter>driver_options</parameter><initializer>array()</initializer></methodparam>
12
+
<methodsynopsis role="PDO">
13
+
<modifier>public</modifier> <type class="union"><type>PDOStatement</type><type>false</type></type><methodname>PDO::prepare</methodname>
14
+
<methodparam><type>string</type><parameter>query</parameter></methodparam>
15
+
<methodparam choice="opt"><type>array</type><parameter>options</parameter><initializer>[]</initializer></methodparam>
16
16
</methodsynopsis>
17
17
18
18
<para>
19
19
Prepares an SQL statement to be executed by the
20
-
<function>PDOStatement::execute</function> method. The statement template can
20
+
<methodname>PDOStatement::execute</methodname> method. The statement template can
21
21
contain zero or more named (:name) or question mark (?) parameter markers
22
22
for which real values will be substituted when the statement is executed.
23
23
Both named and question mark parameter markers cannot be used within the same
...
...
@@ -27,7 +27,7 @@
27
27
</para>
28
28
<para>
29
29
You must include a unique parameter marker for each value you wish to pass
30
-
in to the statement when you call <function>PDOStatement::execute</function>.
30
+
in to the statement when you call <methodname>PDOStatement::execute</methodname>.
31
31
You cannot use a named parameter marker of the same name more than once in a prepared
32
32
statement, unless emulation mode is on.
33
33
</para>
...
...
@@ -40,12 +40,12 @@
40
40
</para>
41
41
</note>
42
42
<para>
43
-
Calling <function>PDO::prepare</function> and
44
-
<function>PDOStatement::execute</function> for statements that will be
43
+
Calling <methodname>PDO::prepare</methodname> and
44
+
<methodname>PDOStatement::execute</methodname> for statements that will be
45
45
issued multiple times with different parameter values optimizes the
46
46
performance of your application by allowing the driver to negotiate
47
-
client and/or server side caching of the query plan and meta information. Also, calling <function>PDO::prepare</function> and
48
-
<function>PDOStatement::execute</function> helps to prevent SQL injection attacks by eliminating the need to
47
+
client and/or server side caching of the query plan and meta information. Also, calling <methodname>PDO::prepare</methodname> and
48
+
<methodname>PDOStatement::execute</methodname> helps to prevent SQL injection attacks by eliminating the need to
49
49
manually quote and escape the parameters.
50
50
</para>
51
51
<para>
...
...
@@ -66,13 +66,18 @@
66
66
which is natively supported by the driver.
67
67
</simpara>
68
68
</note>
69
+
<para>
70
+
As of PHP 7.4.0, question marks can be escaped by doubling them. That means that
71
+
the <literal>??</literal> string will be translated to <literal>?</literal>
72
+
when sending the query to the database.
73
+
</para>
69
74
</refsect1>
70
75
<refsect1 role="parameters">
71
76
&reftitle.parameters;
72
77
<para>
73
78
<variablelist>
74
79
<varlistentry>
75
-
<term><parameter>statement</parameter></term>
80
+
<term><parameter>query</parameter></term>
76
81
<listitem>
77
82
<para>
78
83
This must be a valid SQL statement template for the target database server.
...
...
@@ -80,7 +85,7 @@
80
85
</listitem>
81
86
</varlistentry>
82
87
<varlistentry>
83
-
<term><parameter>driver_options</parameter></term>
88
+
<term><parameter>options</parameter></term>
84
89
<listitem>
85
90
<para>
86
91
This array holds one or more key=>value pairs to set
...
...
@@ -101,21 +106,25 @@
101
106
&reftitle.returnvalues;
102
107
<para>
103
108
If the database server successfully prepares the statement,
104
-
<function>PDO::prepare</function> returns a
109
+
<methodname>PDO::prepare</methodname> returns a
105
110
<classname>PDOStatement</classname> object.
106
111
If the database server cannot successfully prepare the statement,
107
-
<function>PDO::prepare</function> returns &false; or emits
108
-
<classname>PDOException</classname> (depending on <link
109
-
linkend="pdo.error-handling">error handling</link>).
112
+
<methodname>PDO::prepare</methodname> returns &false; or emits
113
+
<classname>PDOException</classname> (depending on <link linkend="pdo.error-handling">error handling</link>).
110
114
</para>
111
115
<note>
112
116
<para>
113
117
Emulated prepared statements does not communicate with the database server
114
-
so <function>PDO::prepare</function> does not check the statement.
118
+
so <methodname>PDO::prepare</methodname> does not check the statement.
115
119
</para>
116
120
</note>
117
121
</refsect1>
118
122
123
+
<refsect1 role="errors">
124
+
&reftitle.errors;
125
+
&pdo.errors;
126
+
</refsect1>
127
+
119
128
<refsect1 role="examples">
120
129
&reftitle.examples;
121
130
<para>
...
...
@@ -127,10 +136,11 @@
127
136
$sql = 'SELECT name, colour, calories
128
137
FROM fruit
129
138
WHERE calories < :calories AND colour = :colour';
130
-
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
131
-
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
139
+
$sth = $dbh->prepare($sql, [PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY]);
140
+
$sth->execute(['calories' => 150, 'colour' => 'red']);
132
141
$red = $sth->fetchAll();
133
-
$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
142
+
/* Array keys can be prefixed with colons ":" too (optional) */
143
+
$sth->execute([':calories' => 175, ':colour' => 'yellow']);
134
144
$yellow = $sth->fetchAll();
135
145
?>
136
146
]]>
...
...
@@ -145,14 +155,29 @@ $yellow = $sth->fetchAll();
145
155
$sth = $dbh->prepare('SELECT name, colour, calories
146
156
FROM fruit
147
157
WHERE calories < ? AND colour = ?');
148
-
$sth->execute(array(150, 'red'));
158
+
$sth->execute([150, 'red']);
149
159
$red = $sth->fetchAll();
150
-
$sth->execute(array(175, 'yellow'));
160
+
$sth->execute([175, 'yellow']);
151
161
$yellow = $sth->fetchAll();
152
162
?>
153
163
]]>
154
164
</programlisting>
155
165
</example>
166
+
<example>
167
+
<title>SQL statement template with question mark escaped</title>
168
+
<programlisting role="php">
169
+
<![CDATA[
170
+
<?php
171
+
/* note: this is only valid on PostgreSQL databases */
172
+
$sth = $dbh->prepare('SELECT * FROM issues WHERE tag::jsonb ?? ?');
173
+
$sth->execute(['feature']);
174
+
$featureIssues = $sth->fetchAll();
175
+
$sth->execute(['performance']);
176
+
$performanceIssues = $sth->fetchAll();
177
+
?>
178
+
]]>
179
+
</programlisting>
180
+
</example>
156
181
</para>
157
182
</refsect1>
158
183
...
...
@@ -160,14 +185,13 @@ $yellow = $sth->fetchAll();
160
185
&reftitle.seealso;
161
186
<para>
162
187
<simplelist>
163
-
<member><function>PDO::exec</function></member>
164
-
<member><function>PDO::query</function></member>
165
-
<member><function>PDOStatement::execute</function></member>
188
+
<member><methodname>PDO::exec</methodname></member>
189
+
<member><methodname>PDO::query</methodname></member>
190
+
<member><methodname>PDOStatement::execute</methodname></member>
166
191
</simplelist>
167
192
</para>
168
193
</refsect1>
169
194
</refentry>
170
-
171
195
<!-- Keep this comment at the end of the file
172
196
Local variables:
173
197
mode: sgml
174
198