[doc-en] master: Document mysqli_stmt_insert_id (#5945)

Author: Kamil Tekiela (kamil-tekiela) Committer: GitHub (web-flow) Pusher: kamil-tekiela Date: 2026-10-14T13:36:58+01:00 Commit: https://github.com/php/doc-en/commit/aa135ef2689157299c23fd4b8eb8c4f70733deaa Raw diff: https://github.com/php/doc-en/commit/aa135ef2689157299c23fd4b8eb8c4f70733deaa.diff Document mysqli_stmt_insert_id (#5945) Changed paths: M reference/mysqli/mysqli_stmt/insert-id.xml Diff: diff --git a/reference/mysqli/mysqli_stmt/insert-id.xml b/reference/mysqli/mysqli_stmt/insert-id.xml index bb182400b4d3..7f982aedd9bd 100644 --- a/reference/mysqli/mysqli_stmt/insert-id.xml +++ b/reference/mysqli/mysqli_stmt/insert-id.xml @@ -4,7 +4,7 @@ <refnamediv> <refname>mysqli_stmt::$insert_id</refname> <refname>mysqli_stmt_insert_id</refname> - <refpurpose>Get the ID generated from the previous INSERT operation</refpurpose> + <refpurpose>Returns the value generated for an AUTO_INCREMENT column by the last statement executed</refpurpose> </refnamediv> <refsect1 role="description"> @@ -16,9 +16,114 @@ <type class="union"><type>int</type><type>string</type></type><methodname>mysqli_stmt_insert_id</methodname> <methodparam><type>mysqli_stmt</type><parameter>statement</parameter></methodparam> </methodsynopsis> + <simpara> + Returns the ID generated by an <literal>INSERT</literal> or + <literal>UPDATE</literal> statement on a table with a column having the + <literal>AUTO_INCREMENT</literal> attribute. In the case of a multiple-row + <literal>INSERT</literal> statement, it returns the first automatically + generated value that was successfully inserted. If + <literal>LAST_INSERT_ID(expr)</literal> is used to set the + <literal>AUTO_INCREMENT</literal> value, or in an <literal>UPDATE</literal>, + the value of <literal>expr</literal> is returned instead. + </simpara> + <simpara> + Returns <literal>0</literal> if the statement did not change an + <literal>AUTO_INCREMENT</literal> value. + </simpara> + </refsect1> + + <refsect1 role="parameters"> + &reftitle.parameters; + <variablelist> + &mysqli.stmt.description; + </variablelist> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <simpara> + The value of the <literal>AUTO_INCREMENT</literal> field that was updated + by the statement. Returns zero if the statement has not been executed yet or + if it did not update an <literal>AUTO_INCREMENT</literal> value. + </simpara> + <simpara> + The value is specific to the statement object. It is not affected by + other statements executed on the same connection after this statement, + nor by statements issued using other connections or clients. + </simpara> + <note> + <simpara> + If the number is greater than the maximum int value, it will be returned as + a string. + </simpara> + </note> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <example> + <title><varname>mysqli_stmt::$insert_id</varname> example</title> + <simpara>&style.oop;</simpara> + <programlisting role="php"> +<![CDATA[ +<?php + +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); + +$mysqli->query("CREATE TEMPORARY TABLE myCity LIKE City"); + +$stmt = $mysqli->prepare("INSERT INTO myCity (Name, CountryCode, District, Population) VALUES (?, ?, ?, ?)"); + +$name = 'Stuttgart'; +$countryCode = 'DEU'; +$district = 'Stuttgart'; +$population = 617000; +$stmt->bind_param('sssi', $name, $countryCode, $district, $population); +$stmt->execute(); + +printf("New record has ID %d.\n", $stmt->insert_id); +]]> + </programlisting> + <simpara>&style.procedural;</simpara> + <programlisting role="php"> +<![CDATA[ +<?php + +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); +$link = mysqli_connect("localhost", "my_user", "my_password", "world"); + +mysqli_query($link, "CREATE TEMPORARY TABLE myCity LIKE City"); + +$stmt = mysqli_prepare($link, "INSERT INTO myCity (Name, CountryCode, District, Population) VALUES (?, ?, ?, ?)"); + +$name = 'Stuttgart'; +$countryCode = 'DEU'; +$district = 'Stuttgart'; +$population = 617000; +mysqli_stmt_bind_param($stmt, 'sssi', $name, $countryCode, $district, $population); +mysqli_stmt_execute($stmt); + +printf("New record has ID %d.\n", mysqli_stmt_insert_id($stmt)); +]]> + </programlisting> + &examples.outputs; + <screen> +<![CDATA[ +New record has ID 1. +]]> + </screen> + </example> + </refsect1> - &warn.undocumented.func; + <refsect1 role="seealso"> + &reftitle.seealso; + <simplelist> + <member><function>mysqli_insert_id</function></member> + <member><function>mysqli_stmt_affected_rows</function></member> + <member><function>mysqli_stmt_execute</function></member> + </simplelist> </refsect1> </refentry>