reference/mysqli/mysqli/begin-transaction.xml
035c126c0393fe154bac46e2c3c489ebadce48a5
...
...
@@ -1,6 +1,5 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-

4
3
<refentry xml:id="mysqli.begin-transaction" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5
4
<refnamediv>
6
5
<refname>mysqli::begin_transaction</refname>
...
...
@@ -10,21 +9,21 @@
10
9

11
10
<refsect1 role="description">
12
11
&reftitle.description;
13
-
<para>&style.oop; (method):</para>
14
-
<methodsynopsis>
12
+
<para>&style.oop;</para>
13
+
<methodsynopsis role="mysqli">
15
14
<modifier>public</modifier> <type>bool</type><methodname>mysqli::begin_transaction</methodname>
16
-
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
17
-
<methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
18
-
</methodsynopsis>
15
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
16
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>name</parameter><initializer>&null;</initializer></methodparam>
17
+
</methodsynopsis>
19
18
<para>&style.procedural;:</para>
20
19
<methodsynopsis>
21
20
<type>bool</type><methodname>mysqli_begin_transaction</methodname>
22
-
<methodparam><type>mysqli</type><parameter>link</parameter></methodparam>
23
-
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
24
-
<methodparam choice="opt"><type>string</type><parameter>name</parameter></methodparam>
21
+
<methodparam><type>mysqli</type><parameter>mysql</parameter></methodparam>
22
+
<methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
23
+
<methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>name</parameter><initializer>&null;</initializer></methodparam>
25
24
</methodsynopsis>
26
25
<para>
27
-
Begins a transaction. Requires MySQL 5.6 and above, and the InnoDB
26
+
Begins a transaction. Requires the InnoDB
28
27
engine (it is enabled by default). For additional details about how MySQL transactions
29
28
work, see <link xlink:href="&url.mysql.docs.commit;">&url.mysql.docs.commit;</link>.
30
29
</para>
...
...
@@ -46,12 +45,14 @@
46
45
<para>
47
46
<constant>MYSQLI_TRANS_START_READ_ONLY</constant>:
48
47
Start the transaction as "START TRANSACTION READ ONLY".
48
+
Requires MySQL 5.6 and above.
49
49
</para>
50
50
</listitem>
51
51
<listitem>
52
52
<para>
53
53
<constant>MYSQLI_TRANS_START_READ_WRITE</constant>:
54
54
Start the transaction as "START TRANSACTION READ WRITE".
55
+
Requires MySQL 5.6 and above.
55
56
</para>
56
57
</listitem>
57
58
<listitem>
...
...
@@ -82,53 +83,123 @@
82
83
</para>
83
84
</refsect1>
84
85

86
+
<refsect1 role="changelog">
87
+
&reftitle.changelog;
88
+
<informaltable>
89
+
<tgroup cols="2">
90
+
<thead>
91
+
<row>
92
+
<entry>&Version;</entry>
93
+
<entry>&Description;</entry>
94
+
</row>
95
+
</thead>
96
+
<tbody>
97
+
<row>
98
+
<entry>8.0.0</entry>
99
+
<entry>
100
+
<parameter>name</parameter> is now nullable.
101
+
</entry>
102
+
</row>
103
+
</tbody>
104
+
</tgroup>
105
+
</informaltable>
106
+
</refsect1>
107
+

85
108
<refsect1 role="examples">
86
109
&reftitle.examples;
87
-
<example>
88
-
<title><methodname>$mysqli->begin_transaction</methodname> example</title>
110
+
<example xml:id="mysqli.begin-transaction.example.basic">
111
+
<title><methodname>mysqli::begin_transaction</methodname> example</title>
89
112
<para>&style.oop;</para>
90
113
<programlisting role="php">
91
114
<![CDATA[
92
115
<?php
93
-
$mysqli = new mysqli("127.0.0.1", "my_user", "my_password", "sakila");
94
116

95
-
if ($mysqli->connect_errno) {
96
-
printf("Connect failed: %s\n", $mysqli->connect_error);
97
-
exit();
98
-
}
117
+
/* Tell mysqli to throw an exception if an error occurs */
118
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
99
119

100
-
$mysqli->begin_transaction(MYSQLI_TRANS_START_READ_ONLY);
120
+
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");
101
121

102
-
$mysqli->query("SELECT first_name, last_name FROM actor");
103
-
$mysqli->commit();
122
+
/* The table engine has to support transactions */
123
+
$mysqli->query("CREATE TABLE IF NOT EXISTS language (
124
+
Code text NOT NULL,
125
+
Speakers int(11) NOT NULL
126
+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
104
127

105
-
$mysqli->close();
106
-
?>
128
+
/* Start transaction */
129
+
$mysqli->begin_transaction();
130
+

131
+
try {
132
+
/* Insert some values */
133
+
$mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");
134
+

135
+
/* Try to insert invalid values */
136
+
$language_code = 'FR';
137
+
$native_speakers = 'Unknown';
138
+
$stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)');
139
+
$stmt->bind_param('ss', $language_code, $native_speakers);
140
+
$stmt->execute();
141
+

142
+
/* If code reaches this point without errors then commit the data in the database */
143
+
$mysqli->commit();
144
+
} catch (mysqli_sql_exception $exception) {
145
+
$mysqli->rollback();
146
+

147
+
throw $exception;
148
+
}
107
149
]]>
108
150
</programlisting>
109
151
<para>&style.procedural;</para>
110
152
<programlisting role="php">
111
153
<![CDATA[
112
154
<?php
113
-
$link = mysqli_connect("127.0.0.1", "my_user", "my_password", "sakila");
114
155

115
-
if (mysqli_connect_errno()) {
116
-
printf("Connect failed: %s\n", mysqli_connect_error());
117
-
exit();
118
-
}
156
+
/* Tell mysqli to throw an exception if an error occurs */
157
+
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
158
+

159
+
$mysqli = mysqli_connect("localhost", "my_user", "my_password", "world");
160
+

161
+
/* The table engine has to support transactions */
162
+
mysqli_query($mysqli, "CREATE TABLE IF NOT EXISTS language (
163
+
Code text NOT NULL,
164
+
Speakers int(11) NOT NULL
165
+
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;");
166
+

167
+
/* Start transaction */
168
+
mysqli_begin_transaction($mysqli);
169
+

170
+
try {
171
+
/* Insert some values */
172
+
mysqli_query($mysqli, "INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)");
119
173

120
-
mysqli_begin_transaction($link, MYSQLI_TRANS_START_READ_ONLY);
174
+
/* Try to insert invalid values */
175
+
$language_code = 'FR';
176
+
$native_speakers = 'Unknown';
177
+
$stmt = mysqli_prepare($mysqli, 'INSERT INTO language(Code, Speakers) VALUES (?,?)');
178
+
mysqli_stmt_bind_param($stmt, 'ss', $language_code, $native_speakers);
179
+
mysqli_stmt_execute($stmt);
121
180

122
-
mysqli_query($link, "SELECT first_name, last_name FROM actor LIMIT 1");
123
-
mysqli_commit($link);
181
+
/* If code reaches this point without errors then commit the data in the database */
182
+
mysqli_commit($mysqli);
183
+
} catch (mysqli_sql_exception $exception) {
184
+
mysqli_rollback($mysqli);
124
185

125
-
mysqli_close($link);
126
-
?>
186
+
throw $exception;
187
+
}
127
188
]]>
128
189
</programlisting>
129
190
</example>
130
191
</refsect1>
131
192

193
+
<refsect1 role="notes">
194
+
&reftitle.notes;
195
+
<note>
196
+
<para>
197
+
This function does not work with non transactional table types (like
198
+
MyISAM or ISAM).
199
+
</para>
200
+
</note>
201
+
</refsect1>
202
+

132
203
<refsect1 role="seealso">
133
204
&reftitle.seealso;
134
205
<para>
...
...
@@ -141,7 +212,6 @@ mysqli_close($link);
141
212
</refsect1>
142
213

143
214
</refentry>
144
-

145
215
<!-- Keep this comment at the end of the file
146
216
Local variables:
147
217
mode: sgml
148
218



Tools (Spanish Manual)