reference/pdo/pdo/prepare.xml
082ddc19f53e6e254010de1a1fbbe485ff744ec1
...
...
@@ -9,25 +9,25 @@
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 SQL statement 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
-
You cannot use both named and question mark parameter markers within the same
24
-
SQL statement; pick one or the other parameter style.
23
+
Both named and question mark parameter markers cannot be used within the same
24
+
statement template; only one or the other parameter style.
25
25
Use these parameters to bind any user-input, do not include the user-input
26
26
directly in the query.
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,13 +40,13 @@
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,
48
-
and helps to prevent SQL injection attacks by eliminating the need to
49
-
manually quote the parameters.
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
+
manually quote and escape the parameters.
50
50
</para>
51
51
<para>
52
52
PDO will emulate prepared statements/bound parameters for drivers that do
...
...
@@ -54,13 +54,30 @@
54
54
style parameter markers to something more appropriate, if the driver
55
55
supports one style but not the other.
56
56
</para>
57
+
<note>
58
+
<simpara>
59
+
The parser used for emulated prepared statements and for
60
+
rewriting named or question mark style parameters supports the non standard
61
+
backslash escapes for single- and double quotes. That means that terminating
62
+
quotes immediately preceeded by a backslash are not recognized as such, which
63
+
may result in wrong detection of parameters causing the prepared statement to
64
+
fail when it is executed. A work-around is to not use emulated prepares for
65
+
such SQL queries, and to avoid rewriting of parameters by using a parameter style
66
+
which is natively supported by the driver.
67
+
</simpara>
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>
57
74
</refsect1>
58
75
<refsect1 role="parameters">
59
76
&reftitle.parameters;
60
77
<para>
61
78
<variablelist>
62
79
<varlistentry>
63
-
<term><parameter>statement</parameter></term>
80
+
<term><parameter>query</parameter></term>
64
81
<listitem>
65
82
<para>
66
83
This must be a valid SQL statement template for the target database server.
...
...
@@ -68,7 +85,7 @@
68
85
</listitem>
69
86
</varlistentry>
70
87
<varlistentry>
71
-
<term><parameter>driver_options</parameter></term>
88
+
<term><parameter>options</parameter></term>
72
89
<listitem>
73
90
<para>
74
91
This array holds one or more key=&gt;value pairs to set
...
...
@@ -76,7 +93,7 @@
76
93
returns. You would most commonly use this to set the
77
94
<literal>PDO::ATTR_CURSOR</literal> value to
78
95
<literal>PDO::CURSOR_SCROLL</literal> to request a scrollable cursor.
79
-
Some drivers have driver specific options that may be set at
96
+
Some drivers have driver-specific options that may be set at
80
97
prepare-time.
81
98
</para>
82
99
</listitem>
...
...
@@ -89,25 +106,29 @@
89
106
&reftitle.returnvalues;
90
107
<para>
91
108
If the database server successfully prepares the statement,
92
-
<function>PDO::prepare</function> returns a
109
+
<methodname>PDO::prepare</methodname> returns a
93
110
<classname>PDOStatement</classname> object.
94
111
If the database server cannot successfully prepare the statement,
95
-
<function>PDO::prepare</function> returns &false; or emits
96
-
<classname>PDOException</classname> (depending on <link
97
-
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>).
98
114
</para>
99
115
<note>
100
116
<para>
101
117
Emulated prepared statements does not communicate with the database server
102
-
so <function>PDO::prepare</function> does not check the statement.
118
+
so <methodname>PDO::prepare</methodname> does not check the statement.
103
119
</para>
104
120
</note>
105
121
</refsect1>
106
122

123
+
<refsect1 role="errors">
124
+
&reftitle.errors;
125
+
&pdo.errors;
126
+
</refsect1>
127
+

107
128
<refsect1 role="examples">
108
129
&reftitle.examples;
109
130
<para>
110
-
<example><title>Prepare an SQL statement with named parameters</title>
131
+
<example><title>SQL statement template with named parameters</title>
111
132
<programlisting role="php">
112
133
<![CDATA[
113
134
<?php
...
...
@@ -115,17 +136,18 @@
115
136
$sql = 'SELECT name, colour, calories
116
137
FROM fruit
117
138
WHERE calories < :calories AND colour = :colour';
118
-
$sth = $dbh->prepare($sql, array(PDO::ATTR_CURSOR => PDO::CURSOR_FWDONLY));
119
-
$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']);
120
141
$red = $sth->fetchAll();
121
-
$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
142
+
/* Array keys can be prefixed with colons ":" too (optional) */
143
+
$sth->execute([':calories' => 175, ':colour' => 'yellow']);
122
144
$yellow = $sth->fetchAll();
123
145
?>
124
146
]]>
125
147
</programlisting>
126
148
</example>
127
149
<example>
128
-
<title>Prepare an SQL statement with question mark parameters</title>
150
+
<title>SQL statement template with question mark parameters</title>
129
151
<programlisting role="php">
130
152
<![CDATA[
131
153
<?php
...
...
@@ -133,14 +155,29 @@ $yellow = $sth->fetchAll();
133
155
$sth = $dbh->prepare('SELECT name, colour, calories
134
156
FROM fruit
135
157
WHERE calories < ? AND colour = ?');
136
-
$sth->execute(array(150, 'red'));
158
+
$sth->execute([150, 'red']);
137
159
$red = $sth->fetchAll();
138
-
$sth->execute(array(175, 'yellow'));
160
+
$sth->execute([175, 'yellow']);
139
161
$yellow = $sth->fetchAll();
140
162
?>
141
163
]]>
142
164
</programlisting>
143
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>
144
181
</para>
145
182
</refsect1>
146
183

...
...
@@ -148,14 +185,13 @@ $yellow = $sth->fetchAll();
148
185
&reftitle.seealso;
149
186
<para>
150
187
<simplelist>
151
-
<member><function>PDO::exec</function></member>
152
-
<member><function>PDO::query</function></member>
153
-
<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>
154
191
</simplelist>
155
192
</para>
156
193
</refsect1>
157
194
</refentry>
158
-

159
195
<!-- Keep this comment at the end of the file
160
196
Local variables:
161
197
mode: sgml
162
198



Tools (Spanish Manual)