[ticket/8071] Add sql_last_inserted_id alias for sql_nextid

Fixes [DBAL function sql_nextid - name is
misleading](https://tracker.phpbb.com/browse/PHPBB3-8071).

Per the tracker issue:
> This function gets the ID of the last inserted row, not the ID of the next row
to be inserted (which is difficult due to different autoincrement steps and also
lends itself nicely to race conditions).

@iwisdom replied that the naming is consistent with how PHP itself names this
functionality, but the link they posted doesn't support that (I guess this is
referring to a much older version of PHP? The comment is from 2009).

PHPBB3-8071

phpBB/phpbb/db/driver/driver_interface.php

@@ -289,12 +289,37 @@ interface driver_interface
 	public function cast_expr_to_bigint($expression);
 
 	/**
-	* Get last inserted id after insert statement
-	*
-	* @return	string		Autoincrement value of the last inserted row
-	*/
+	 * Gets the ID of the **last** inserted row immediately after an INSERT
+	 * statement.
+	 *
+	 * **Note**: Despite the name, the returned ID refers to the row that has
+	 * just been inserted, rather than the hypothetical ID of the next row if a
+	 * new one was to be inserted.
+	 *
+	 * The returned value can be used for selecting the item that has just been
+	 * inserted or for updating another table with an ID pointing to that item.
+	 *
+	 * Will be deprecated in a future version of phpBB in favor of
+	 * `sql_last_inserted_id`.
+	 *
+	 * @return	string|false	Auto-incremented value of the last inserted row
+	 */
 	public function sql_nextid();
 
+	/**
+	 * Gets the ID of the last inserted row immediately after an INSERT
+	 * statement. The returned value can be used for selecting the item that has
+	 * just been inserted or for updating another table with an ID pointing to
+	 * that item.
+	 *
+	 * Alias of `sql_nextid`.
+	 *
+	 * @return	string|false	Auto-incremented value of the last inserted row
+	 *
+	 * @since 3.3.8-RC1
+	 */
+	public function sql_last_inserted_id();
+
 	/**
 	* Add to query count
 	*

phpBB/phpbb/db/driver/factory.php

@@ -314,13 +314,21 @@ class factory implements driver_interface
 	}
 
 	/**
-	* {@inheritdoc}
-	*/
+	 * {@inheritdoc}
+	 */
 	public function sql_nextid()
 	{
 		return $this->get_driver()->sql_nextid();
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->get_driver()->sql_nextid();
+	}
+
 	/**
 	* {@inheritdoc}
 	*/

phpBB/phpbb/db/driver/mssql_odbc.php

@@ -269,8 +269,8 @@ class mssql_odbc extends \phpbb\db\driver\mssql_base
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
+	 * {@inheritDoc}
+	 */
 	function sql_nextid()
 	{
 		$result_id = @odbc_exec($this->db_connect_id, 'SELECT @@IDENTITY');
@@ -289,6 +289,14 @@ class mssql_odbc extends \phpbb\db\driver\mssql_base
 		return false;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/

phpBB/phpbb/db/driver/mssqlnative.php

@@ -271,8 +271,8 @@ class mssqlnative extends \phpbb\db\driver\mssql_base
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
+	 * {@inheritDoc}
+	 */
 	function sql_nextid()
 	{
 		$result_id = @sqlsrv_query($this->db_connect_id, 'SELECT @@IDENTITY');
@@ -290,6 +290,14 @@ class mssqlnative extends \phpbb\db\driver\mssql_base
 		}
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/

phpBB/phpbb/db/driver/mysqli.php

@@ -289,13 +289,21 @@ class mysqli extends \phpbb\db\driver\mysql_base
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
+	 * {@inheritDoc}
+	 */
 	function sql_nextid()
 	{
 		return ($this->db_connect_id) ? @mysqli_insert_id($this->db_connect_id) : false;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/

phpBB/phpbb/db/driver/oracle.php

@@ -570,8 +570,8 @@ class oracle extends \phpbb\db\driver\driver
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
+	 * {@inheritDoc}
+	 */
 	function sql_nextid()
 	{
 		$query_id = $this->query_result;
@@ -607,6 +607,14 @@ class oracle extends \phpbb\db\driver\driver
 		return false;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/

phpBB/phpbb/db/driver/postgres.php

@@ -342,8 +342,8 @@ class postgres extends \phpbb\db\driver\driver
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
+	 * {@inheritDoc}
+	 */
 	function sql_nextid()
 	{
 		$query_id = $this->query_result;
@@ -370,6 +370,14 @@ class postgres extends \phpbb\db\driver\driver
 		return false;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/

phpBB/phpbb/db/driver/sqlite3.php

@@ -242,13 +242,21 @@ class sqlite3 extends \phpbb\db\driver\driver
 	}
 
 	/**
-	* {@inheritDoc}
-	*/
-	public function sql_nextid()
+	 * {@inheritDoc}
+	 */
+	function sql_nextid()
 	{
 		return ($this->db_connect_id) ? $this->dbo->lastInsertRowID() : false;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 */
+	public function sql_last_inserted_id()
+	{
+		return $this->sql_nextid();
+	}
+
 	/**
 	* {@inheritDoc}
 	*/