reference/mysqli/mysqli_stmt/prepare.xml
63b99082ef83eade08151f8cb528246fded81db9
...
...
@@ -4,34 +4,35 @@
4
4
<refnamediv>
5
5
<refname>mysqli_stmt::prepare</refname>
6
6
<refname>mysqli_stmt_prepare</refname>
7
-
<refpurpose>Prepare an SQL statement for execution</refpurpose>
7
+
<refpurpose>Prepares an SQL statement for execution</refpurpose>
8
8
</refnamediv>
9
9

10
10
<refsect1 role="description">
11
11
&reftitle.description;
12
12
<para>&style.oop;</para>
13
-
<methodsynopsis role="oop">
14
-
<type>mixed</type><methodname>mysqli_stmt::prepare</methodname>
13
+
<methodsynopsis role="mysqli_stmt">
14
+
<modifier>public</modifier> <type>bool</type><methodname>mysqli_stmt::prepare</methodname>
15
15
<methodparam><type>string</type><parameter>query</parameter></methodparam>
16
16
</methodsynopsis>
17
17
<para>&style.procedural;</para>
18
18
<methodsynopsis>
19
19
<type>bool</type><methodname>mysqli_stmt_prepare</methodname>
20
-
<methodparam><type>mysqli_stmt</type><parameter>stmt</parameter></methodparam>
20
+
<methodparam><type>mysqli_stmt</type><parameter>statement</parameter></methodparam>
21
21
<methodparam><type>string</type><parameter>query</parameter></methodparam>
22
22
</methodsynopsis>
23
23
<para>
24
-
Prepares the SQL query pointed to by the null-terminated string query.
24
+
Prepares a statement for execution.
25
+
The query must consist of a single SQL statement.
25
26
</para>
26
27
<para>
28
+
The statement template can contain zero or more question mark
29
+
(<literal>?</literal>) parameter markers⁠—also called placeholders.
27
30
The parameter markers must be bound to application variables using
28
-
<function>mysqli_stmt_bind_param</function> and/or
29
-
<function>mysqli_stmt_bind_result</function> before executing the
30
-
statement or fetching rows.
31
+
<function>mysqli_stmt_bind_param</function> before executing the statement.
31
32
</para>
32
33
<note>
33
34
<para>
34
-
In the case where you pass a statement to
35
+
In the case where a statement is passed to
35
36
<function>mysqli_stmt_prepare</function> that is longer than
36
37
<literal>max_allowed_packet</literal> of the server, the returned
37
38
error codes are different depending on whether you are using MySQL
...
...
@@ -75,31 +76,20 @@
75
76
The query, as a string. It must consist of a single SQL statement.
76
77
</para>
77
78
<para>
78
-
You can include one or more parameter markers in the SQL statement by
79
-
embedding question mark (<literal>?</literal>) characters at the
80
-
appropriate positions.
79
+
The SQL statement may contain zero or more parameter markers
80
+
represented by question mark (<literal>?</literal>) characters
81
+
at the appropriate positions.
81
82
</para>
82
83
<note>
83
-
<para>
84
-
You should not add a terminating semicolon or <literal>\g</literal>
85
-
to the statement.
86
-
</para>
87
-
</note>
88
-
<note>
84
+
<!-- Copied from https://dev.mysql.com/doc/c-api/8.0/en/mysql-stmt-prepare.html -->
89
85
<para>
90
86
The markers are legal only in certain places in SQL statements.
91
-
For example, they are allowed in the VALUES() list of an INSERT statement
92
-
(to specify column values for a row), or in a comparison with a column in
93
-
a WHERE clause to specify a comparison value.
94
-
</para>
95
-
<para>
96
-
However, they are not allowed for identifiers (such as table or column names),
97
-
in the select list that names the columns to be returned by a SELECT statement),
98
-
or to specify both operands of a binary operator such as the <literal>=</literal>
99
-
equal sign. The latter restriction is necessary because it would be impossible
100
-
to determine the parameter type. In general, parameters are legal only in Data
101
-
Manipulation Language (DML) statements, and not in Data Definition Language
102
-
(DDL) statements.
87
+
For example, they are permitted in the <literal>VALUES()</literal>
88
+
list of an <literal>INSERT</literal> statement (to specify column
89
+
values for a row), or in a comparison with a column in a
90
+
<literal>WHERE</literal> clause to specify a comparison value.
91
+
However, they are not permitted for identifiers (such as table or
92
+
column names).
103
93
</para>
104
94
</note>
105
95
</listitem>
...
...
@@ -115,91 +105,71 @@
115
105
</para>
116
106
</refsect1>
117
107

108
+
<refsect1 role="errors">
109
+
&reftitle.errors;
110
+
&mysqli.conditionalexception;
111
+
</refsect1>
112
+

118
113
<refsect1 role="examples">
119
114
&reftitle.examples;
120
115
<example>
121
-
<title>&style.oop;</title>
116
+
<title><methodname>mysqli_stmt::prepare</methodname> example</title>
117
+
<para>&style.oop;</para>
122
118
<programlisting role="php">
123
119
<![CDATA[
124
120
<?php
125
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
126
121

127
-
/* check connection */
128
-
if (mysqli_connect_errno()) {
129
-
printf("Connect failed: %s\n", mysqli_connect_error());
130
-
exit();
131
-
}
122
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
123
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
132
124

133
125
$city = "Amersfoort";
134
126

135
127
/* create a prepared statement */
136
-
$stmt = $mysqli->stmt_init();
137
-
if ($stmt->prepare("SELECT District FROM City WHERE Name=?")) {
128
+
$stmt = $mysqli->stmt_init();
129
+
$stmt->prepare("SELECT District FROM City WHERE Name=?");
138
130

139
-
/* bind parameters for markers */
140
-
$stmt->bind_param("s", $city);
131
+
/* bind parameters for markers */
132
+
$stmt->bind_param("s", $city);
141
133

142
-
/* execute query */
143
-
$stmt->execute();
134
+
/* execute query */
135
+
$stmt->execute();
144
136

145
-
/* bind result variables */
146
-
$stmt->bind_result($district);
137
+
/* bind result variables */
138
+
$stmt->bind_result($district);
147
139

148
-
/* fetch value */
149
-
$stmt->fetch();
140
+
/* fetch value */
141
+
$stmt->fetch();
150
142

151
-
printf("%s is in district %s\n", $city, $district);
152
-

153
-
/* close statement */
154
-
$stmt->close();
155
-
}
156
-

157
-
/* close connection */
158
-
$mysqli->close();
159
-
?>
143
+
printf("%s is in district %s\n", $city, $district);
160
144
]]>
161
145
</programlisting>
162
-
</example>
163
-
<example>
164
-
<title>&style.procedural;</title>
146
+
<para>&style.procedural;</para>
165
147
<programlisting role="php">
166
148
<![CDATA[
167
149
<?php
168
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
169
150

170
-
/* check connection */
171
-
if (mysqli_connect_errno()) {
172
-
printf("Connect failed: %s\n", mysqli_connect_error());
173
-
exit();
174
-
}
151
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
152
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
175
153

176
154
$city = "Amersfoort";
177
155

178
156
/* create a prepared statement */
179
157
$stmt = mysqli_stmt_init($link);
180
-
if (mysqli_stmt_prepare($stmt, 'SELECT District FROM City WHERE Name=?')) {
181
-

182
-
/* bind parameters for markers */
183
-
mysqli_stmt_bind_param($stmt, "s", $city);
158
+
mysqli_stmt_prepare($stmt, "SELECT District FROM City WHERE Name=?");
184
159

185
-
/* execute query */
186
-
mysqli_stmt_execute($stmt);
160
+
/* bind parameters for markers */
161
+
mysqli_stmt_bind_param($stmt, "s", $city);
187
162

188
-
/* bind result variables */
189
-
mysqli_stmt_bind_result($stmt, $district);
163
+
/* execute query */
164
+
mysqli_stmt_execute($stmt);
190
165

191
-
/* fetch value */
192
-
mysqli_stmt_fetch($stmt);
166
+
/* bind result variables */
167
+
mysqli_stmt_bind_result($stmt, $district);
193
168

194
-
printf("%s is in district %s\n", $city, $district);
169
+
/* fetch value */
170
+
mysqli_stmt_fetch($stmt);
195
171

196
-
/* close statement */
197
-
mysqli_stmt_close($stmt);
198
-
}
199
-

200
-
/* close connection */
201
-
mysqli_close($link);
202
-
?>
172
+
printf("%s is in district %s\n", $city, $district);
203
173
]]>
204
174
</programlisting>
205
175
&examples.outputs;
...
...
@@ -227,7 +197,6 @@ Amersfoort is in district Utrecht
227
197
</refsect1>
228
198

229
199
</refentry>
230
-

231
200
<!-- Keep this comment at the end of the file
232
201
Local variables:
233
202
mode: sgml
234
203