reference/mysqli/mysqli/prepare.xml
63b99082ef83eade08151f8cb528246fded81db9
63b99082ef83eade08151f8cb528246fded81db9
...
...
@@ -4,20 +4,20 @@
4
4
<refnamediv>
5
5
<refname>mysqli::prepare</refname>
6
6
<refname>mysqli_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>mysqli_stmt</type><methodname>mysqli::prepare</methodname>
13
+
<methodsynopsis role="mysqli">
14
+
<modifier>public</modifier> <type class="union"><type>mysqli_stmt</type><type>false</type></type><methodname>mysqli::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
-
<type>mysqli_stmt</type><methodname>mysqli_prepare</methodname>
20
-
<methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
19
+
<type class="union"><type>mysqli_stmt</type><type>false</type></type><methodname>mysqli_prepare</methodname>
20
+
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
21
21
<methodparam><type>string</type><parameter>query</parameter></methodparam>
22
22
</methodsynopsis>
23
23
<para>
...
...
@@ -25,10 +25,10 @@
25
25
operations on the statement. The query must consist of a single SQL statement.
26
26
</para>
27
27
<para>
28
+
The statement template can contain zero or more question mark
29
+
(<literal>?</literal>) parameter markers—also called placeholders.
28
30
The parameter markers must be bound to application variables using
29
-
<function>mysqli_stmt_bind_param</function> and/or
30
-
<function>mysqli_stmt_bind_result</function> before executing the
31
-
statement or fetching rows.
31
+
<function>mysqli_stmt_bind_param</function> before executing the statement.
32
32
</para>
33
33
</refsect1>
34
34
...
...
@@ -41,38 +41,23 @@
41
41
<term><parameter>query</parameter></term>
42
42
<listitem>
43
43
<para>
44
-
The query, as a string.
44
+
The query, as a string. It must consist of a single SQL statement.
45
45
</para>
46
-
<note>
47
-
<para>
48
-
You should not add a terminating semicolon or <literal>\g</literal>
49
-
to the statement.
50
-
</para>
51
-
</note>
52
46
<para>
53
-
This parameter can include one or more parameter markers in the SQL
54
-
statement by embedding question mark (<literal>?</literal>) characters
47
+
The SQL statement may contain zero or more parameter markers
48
+
represented by question mark (<literal>?</literal>) characters
55
49
at the appropriate positions.
56
50
</para>
57
51
<note>
52
+
<!-- Copied from https://dev.mysql.com/doc/c-api/8.0/en/mysql-stmt-prepare.html -->
58
53
<para>
59
54
The markers are legal only in certain places in SQL statements.
60
-
For example, they are allowed in the <literal>VALUES()</literal>
55
+
For example, they are permitted in the <literal>VALUES()</literal>
61
56
list of an <literal>INSERT</literal> statement (to specify column
62
57
values for a row), or in a comparison with a column in a
63
58
<literal>WHERE</literal> clause to specify a comparison value.
64
-
</para>
65
-
<para>
66
-
However, they are not allowed for identifiers (such as table or
67
-
column names), in the select list that names the columns to be
68
-
returned by a <literal>SELECT</literal> statement, or to specify both
69
-
operands of a binary operator such as the <literal>=</literal> equal
70
-
sign. The latter restriction is necessary because it would be
71
-
impossible to determine the parameter type. It's not allowed to
72
-
compare marker with <literal>NULL</literal> by
73
-
<literal>? IS NULL</literal> too. In general, parameters are legal
74
-
only in Data Manipulation Language (DML) statements, and not in Data
75
-
Definition Language (DDL) statements.
59
+
However, they are not permitted for identifiers (such as table or
60
+
column names).
76
61
</para>
77
62
</note>
78
63
</listitem>
...
...
@@ -88,6 +73,11 @@
88
73
</para>
89
74
</refsect1>
90
75
76
+
<refsect1 role="errors">
77
+
&reftitle.errors;
78
+
&mysqli.conditionalexception;
79
+
</refsect1>
80
+
91
81
<refsect1 role="examples">
92
82
&reftitle.examples;
93
83
<example>
...
...
@@ -96,80 +86,56 @@
96
86
<programlisting role="php">
97
87
<![CDATA[
98
88
<?php
99
-
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
100
89
101
-
/* check connection */
102
-
if (mysqli_connect_errno()) {
103
-
printf("Connect failed: %s\n", mysqli_connect_error());
104
-
exit();
105
-
}
90
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
91
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
106
92
107
93
$city = "Amersfoort";
108
94
109
95
/* create a prepared statement */
110
-
if ($stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?")) {
111
-
112
-
/* bind parameters for markers */
113
-
$stmt->bind_param("s", $city);
96
+
$stmt = $mysqli->prepare("SELECT District FROM City WHERE Name=?");
114
97
115
-
/* execute query */
116
-
$stmt->execute();
98
+
/* bind parameters for markers */
99
+
$stmt->bind_param("s", $city);
117
100
118
-
/* bind result variables */
119
-
$stmt->bind_result($district);
101
+
/* execute query */
102
+
$stmt->execute();
120
103
121
-
/* fetch value */
122
-
$stmt->fetch();
104
+
/* bind result variables */
105
+
$stmt->bind_result($district);
123
106
124
-
printf("%s is in district %s\n", $city, $district);
107
+
/* fetch value */
108
+
$stmt->fetch();
125
109
126
-
/* close statement */
127
-
$stmt->close();
128
-
}
129
-
130
-
/* close connection */
131
-
$mysqli->close();
132
-
?>
110
+
printf("%s is in district %s\n", $city, $district);
133
111
]]>
134
112
</programlisting>
135
113
<para>&style.procedural;</para>
136
114
<programlisting role="php">
137
115
<![CDATA[
138
116
<?php
139
-
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
140
117
141
-
/* check connection */
142
-
if (mysqli_connect_errno()) {
143
-
printf("Connect failed: %s\n", mysqli_connect_error());
144
-
exit();
145
-
}
118
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
119
+
$link = mysqli_connect("localhost", "my_user", "my_password", "world");
146
120
147
121
$city = "Amersfoort";
148
122
149
123
/* create a prepared statement */
150
-
if ($stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?")) {
151
-
152
-
/* bind parameters for markers */
153
-
mysqli_stmt_bind_param($stmt, "s", $city);
124
+
$stmt = mysqli_prepare($link, "SELECT District FROM City WHERE Name=?");
154
125
155
-
/* execute query */
156
-
mysqli_stmt_execute($stmt);
126
+
/* bind parameters for markers */
127
+
mysqli_stmt_bind_param($stmt, "s", $city);
157
128
158
-
/* bind result variables */
159
-
mysqli_stmt_bind_result($stmt, $district);
129
+
/* execute query */
130
+
mysqli_stmt_execute($stmt);
160
131
161
-
/* fetch value */
162
-
mysqli_stmt_fetch($stmt);
132
+
/* bind result variables */
133
+
mysqli_stmt_bind_result($stmt, $district);
163
134
164
-
printf("%s is in district %s\n", $city, $district);
135
+
/* fetch value */
136
+
mysqli_stmt_fetch($stmt);
165
137
166
-
/* close statement */
167
-
mysqli_stmt_close($stmt);
168
-
}
169
-
170
-
/* close connection */
171
-
mysqli_close($link);
172
-
?>
138
+
printf("%s is in district %s\n", $city, $district);
173
139
]]>
174
140
</programlisting>
175
141
&examples.outputs;
...
...
@@ -189,13 +155,13 @@ Amersfoort is in district Utrecht
189
155
<member><function>mysqli_stmt_fetch</function></member>
190
156
<member><function>mysqli_stmt_bind_param</function></member>
191
157
<member><function>mysqli_stmt_bind_result</function></member>
158
+
<member><function>mysqli_stmt_get_result</function></member>
192
159
<member><function>mysqli_stmt_close</function></member>
193
160
</simplelist>
194
161
</para>
195
162
</refsect1>
196
163
197
164
</refentry>
198
-
199
165
<!-- Keep this comment at the end of the file
200
166
Local variables:
201
167
mode: sgml
202
168