reference/sqlite3/sqlite3stmt/bindparam.xml
855bfee2f3db70d7dbb4c60c7c4a4efa567f1c60
855bfee2f3db70d7dbb4c60c7c4a4efa567f1c60
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
4
3
<refentry xml:id="sqlite3stmt.bindparam" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>SQLite3Stmt::bindParam</refname>
...
...
@@ -9,15 +8,27 @@
9
8
10
9
<refsect1 role="description">
11
10
&reftitle.description;
12
-
<methodsynopsis>
11
+
<methodsynopsis role="SQLite3Stmt">
13
12
<modifier>public</modifier> <type>bool</type><methodname>SQLite3Stmt::bindParam</methodname>
14
-
<methodparam><type>mixed</type><parameter>sql_param</parameter></methodparam>
15
-
<methodparam><type>mixed</type><parameter role="reference">param</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>type</parameter></methodparam>
13
+
<methodparam><type class="union"><type>string</type><type>int</type></type><parameter>param</parameter></methodparam>
14
+
<methodparam><type>mixed</type><parameter role="reference">var</parameter></methodparam>
15
+
<methodparam choice="opt"><type>int</type><parameter>type</parameter><initializer><constant>SQLITE3_TEXT</constant></initializer></methodparam>
17
16
</methodsynopsis>
18
17
<para>
19
18
Binds a parameter to a statement variable.
20
19
</para>
20
+
<caution>
21
+
<para>
22
+
Before PHP 7.2.14 and 7.3.0, respectively,
23
+
<methodname>SQLite3Stmt::reset</methodname> must be called after the first call to
24
+
<methodname>SQLite3Stmt::execute</methodname> if the bound value should be properly
25
+
updated on following calls to <methodname>SQLite3Stmt::execute</methodname>.
26
+
If <methodname>SQLite3Stmt::reset</methodname> is not called, the bound value will
27
+
not change, even if the value assigned to the variable passed to
28
+
<methodname>SQLite3Stmt::bindParam</methodname> has changed, or
29
+
<methodname>SQLite3Stmt::bindParam</methodname> has been called again.
30
+
</para>
31
+
</caution>
21
32
</refsect1>
22
33
23
34
<refsect1 role="parameters">
...
...
@@ -25,16 +36,20 @@
25
36
<para>
26
37
<variablelist>
27
38
<varlistentry>
28
-
<term><parameter>sql_param</parameter></term>
39
+
<term><parameter>param</parameter></term>
29
40
<listitem>
30
41
<para>
31
-
Either a <type>string</type> or an <type>int</type> identifying the statement variable to which the
32
-
parameter should be bound.
42
+
Either a <type>string</type> (for named parameters) or an <type>int</type>
43
+
(for positional parameters) identifying the statement variable to which the
44
+
value should be bound.
45
+
If a named parameter does not start with a colon (<literal>:</literal>) or an
46
+
at sign (<literal>@</literal>), a colon (<literal>:</literal>) is automatically preprended.
47
+
Positional parameters start with <literal>1</literal>.
33
48
</para>
34
49
</listitem>
35
50
</varlistentry>
36
51
<varlistentry>
37
-
<term><parameter>param</parameter></term>
52
+
<term><parameter>var</parameter></term>
38
53
<listitem>
39
54
<para>
40
55
The parameter to bind to a statement variable.
...
...
@@ -49,41 +64,56 @@
49
64
<itemizedlist>
50
65
<listitem>
51
66
<para>
52
-
<literal>SQLITE3_INTEGER</literal>: The value is a signed integer,
67
+
<constant>SQLITE3_INTEGER</constant>: The value is a signed integer,
53
68
stored in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of
54
69
the value.
55
70
</para>
56
71
</listitem>
57
72
<listitem>
58
73
<para>
59
-
<literal>SQLITE3_FLOAT</literal>: The value is a floating point
74
+
<constant>SQLITE3_FLOAT</constant>: The value is a floating point
60
75
value, stored as an 8-byte IEEE floating point number.
61
76
</para>
62
77
</listitem>
63
78
<listitem>
64
79
<para>
65
-
<literal>SQLITE3_TEXT</literal>: The value is a text string, stored
80
+
<constant>SQLITE3_TEXT</constant>: The value is a text string, stored
66
81
using the database encoding (UTF-8, UTF-16BE or UTF-16-LE).
67
82
</para>
68
83
</listitem>
69
84
<listitem>
70
85
<para>
71
-
<literal>SQLITE3_BLOB</literal>: The value is a blob of data, stored
86
+
<constant>SQLITE3_BLOB</constant>: The value is a blob of data, stored
72
87
exactly as it was input.
73
88
</para>
74
89
</listitem>
75
90
<listitem>
76
91
<para>
77
-
<literal>SQLITE3_NULL</literal>: The value is a NULL value.
92
+
<constant>SQLITE3_NULL</constant>: The value is a NULL value.
78
93
</para>
79
94
</listitem>
80
95
</itemizedlist>
81
96
</para>
97
+
<para>
98
+
As of PHP 7.0.7, if <parameter>type</parameter> is omitted, it is automatically
99
+
detected from the type of the <parameter>var</parameter>: <type>bool</type>
100
+
and <type>int</type> are treated as <constant>SQLITE3_INTEGER</constant>,
101
+
<type>float</type> as <constant>SQLITE3_FLOAT</constant>, <type>null</type>
102
+
as <constant>SQLITE3_NULL</constant> and all others as <constant>SQLITE3_TEXT</constant>.
103
+
Formerly, if <parameter>type</parameter> has been omitted, it has defaulted
104
+
to <constant>SQLITE3_TEXT</constant>.
105
+
</para>
106
+
<note>
107
+
<para>
108
+
If <parameter>var</parameter> is &null;, it is always treated as
109
+
<constant>SQLITE3_NULL</constant>, regardless of the given
110
+
<parameter>type</parameter>.
111
+
</para>
112
+
</note>
82
113
</listitem>
83
114
</varlistentry>
84
115
</variablelist>
85
116
</para>
86
-
87
117
</refsect1>
88
118
89
119
<refsect1 role="returnvalues">
...
...
@@ -94,8 +124,86 @@
94
124
</para>
95
125
</refsect1>
96
126
97
-
</refentry>
127
+
<refsect1 role="changelog">
128
+
&reftitle.changelog;
129
+
<informaltable>
130
+
<tgroup cols="2">
131
+
<thead>
132
+
<row>
133
+
<entry>&Version;</entry>
134
+
<entry>&Description;</entry>
135
+
</row>
136
+
</thead>
137
+
<tbody>
138
+
<row>
139
+
<entry>7.4.0</entry>
140
+
<entry>
141
+
<parameter>param</parameter> now also supports the <literal>@param</literal>
142
+
notation.
143
+
</entry>
144
+
</row>
145
+
</tbody>
146
+
</tgroup>
147
+
</informaltable>
148
+
</refsect1>
149
+
150
+
<refsect1 role="examples">
151
+
&reftitle.examples;
152
+
<para>
153
+
<example>
154
+
<title><function>SQLite3Stmt::bindParam</function> Usage</title>
155
+
<para>
156
+
This example shows how a single prepared statement with a single parameter
157
+
binding can be used to insert multiple rows with different values.
158
+
</para>
159
+
<programlisting role="php">
160
+
<![CDATA[
161
+
<?php
162
+
$db = new SQLite3(':memory:');
163
+
$db->exec("CREATE TABLE foo (bar TEXT)");
98
164
165
+
$stmt = $db->prepare("INSERT INTO foo VALUES (:bar)");
166
+
$stmt->bindParam(':bar', $bar, SQLITE3_TEXT);
167
+
168
+
$bar = 'baz';
169
+
$stmt->execute();
170
+
171
+
$bar = 42;
172
+
$stmt->execute();
173
+
174
+
$res = $db->query("SELECT * FROM foo");
175
+
while (($row = $res->fetchArray(SQLITE3_ASSOC))) {
176
+
var_dump($row);
177
+
}
178
+
?>
179
+
]]>
180
+
</programlisting>
181
+
&example.outputs;
182
+
<screen role="php">
183
+
<![CDATA[
184
+
array(1) {
185
+
["bar"]=>
186
+
string(3) "baz"
187
+
}
188
+
array(1) {
189
+
["bar"]=>
190
+
string(2) "42"
191
+
}
192
+
]]>
193
+
</screen>
194
+
</example>
195
+
</para>
196
+
</refsect1>
197
+
198
+
<refsect1 role="seealso">
199
+
&reftitle.seealso;
200
+
<simplelist>
201
+
<member><methodname>SQLite3Stmt::bindValue</methodname></member>
202
+
<member><methodname>SQLite3::prepare</methodname></member>
203
+
</simplelist>
204
+
</refsect1>
205
+
206
+
</refentry>
99
207
<!-- Keep this comment at the end of the file
100
208
Local variables:
101
209
mode: sgml
102
210