force the use of sql_multi_insert() for multi inserts... also adjusted the coding guidelines accordingly.

git-svn-id: file:///svn/phpbb/branches/phpBB-3_0_0@8693 89ea8834-ac86-4346-8a33-228a782c2dd0

phpBB/docs/coding-guidelines.html

@@ -690,7 +690,29 @@ $sql = 'UPDATE ' . SOME_TABLE . '
 $db->sql_query($sql);
 	</pre></div>
 
-	<p>The <code>$db-&gt;sql_build_array()</code> function supports the following modes: <code>INSERT</code> (example above), <code>INSERT_SELECT</code> (building query for <code>INSERT INTO table (...) SELECT value, column ...</code> statements), <code>MULTI_INSERT</code> (for returning extended inserts), <code>UPDATE</code> (example above) and <code>SELECT</code> (for building WHERE statement [AND logic]).</p>
+	<p>The <code>$db-&gt;sql_build_array()</code> function supports the following modes: <code>INSERT</code> (example above), <code>INSERT_SELECT</code> (building query for <code>INSERT INTO table (...) SELECT value, column ...</code> statements), <code>UPDATE</code> (example above) and <code>SELECT</code> (for building WHERE statement [AND logic]).</p>
+
+	<h4>sql_multi_insert():</h4>
+
+	<p>If you want to insert multiple statements at once, please use the separate <code>sql_multi_insert()</code> method. An example:</p>
+
+	<div class="codebox"><pre>
+$sql_ary = array();
+
+$sql_ary[] = array(
+	'somedata'		=&gt; $my_string_1,
+	'otherdata'		=&gt; $an_int_1,
+	'moredata'		=&gt; $another_int_1,
+);
+
+$sql_ary[] = array(
+	'somedata'		=&gt; $my_string_2,
+	'otherdata'		=&gt; $an_int_2,
+	'moredata'		=&gt; $another_int_2,
+);
+
+$db->sql_multi_insert(SOME_TABLE, $sql_ary);
+	</pre></div>
 
 	<h4>sql_in_set():</h4>
 
@@ -2195,6 +2217,13 @@ if (utf8_case_fold_nfc($string1) == utf8_case_fold_nfc($string2))
 
 		<div class="content">
 
+<h3>Revision 8596+</h3>
+
+<ul>
+	<li>Removed sql_build_array('MULTI_INSERT'... statements.</li>
+	<li>Added sql_multi_insert() explanation.</li>
+</ul>
+
 <h3>Revision 1.31</h3>
 
 <ul>

phpBB/includes/db/dbal.php

@@ -34,7 +34,7 @@ class dbal
 	var $query_hold = '';
 	var $html_hold = '';
 	var $sql_report = '';
-	
+
 	var $persistency = false;
 	var $user = '';
 	var $server = '';
@@ -47,7 +47,7 @@ class dbal
 	var $sql_error_sql = '';
 	// Holding the error information - only populated if sql_error_triggered is set
 	var $sql_error_returned = array();
-	
+
 	// Holding transaction count
 	var $transactions = 0;
 
@@ -137,7 +137,7 @@ class dbal
 		{
 			$this->sql_freeresult($query_id);
 		}
-		
+
 		return $this->_sql_close();
 	}
 
@@ -179,7 +179,7 @@ class dbal
 
 			return $result;
 		}
-		
+
 		return false;
 	}
 
@@ -300,7 +300,7 @@ class dbal
 	* Build sql statement from array for insert/update/select statements
 	*
 	* Idea for this from Ikonboard
-	* Possible query values: INSERT, INSERT_SELECT, MULTI_INSERT, UPDATE, SELECT
+	* Possible query values: INSERT, INSERT_SELECT, UPDATE, SELECT
 	*
 	*/
 	function sql_build_array($query, $assoc_ary = false)
@@ -333,24 +333,7 @@ class dbal
 		}
 		else if ($query == 'MULTI_INSERT')
 		{
-			$ary = array();
+			trigger_error('The MULTI_INSERT query value is no longer supported. Please use sql_multi_insert() instead.', E_USER_ERROR);
-			foreach ($assoc_ary as $id => $sql_ary)
-			{
-				// If by accident the sql array is only one-dimensional we build a normal insert statement
-				if (!is_array($sql_ary))
-				{
-					return $this->sql_build_array('INSERT', $assoc_ary);
-				}
-
-				$values = array();
-				foreach ($sql_ary as $key => $var)
-				{
-					$values[] = $this->_sql_validate_value($var);
-				}
-				$ary[] = '(' . implode(', ', $values) . ')';
-			}
-
-			$query = ' (' . implode(', ', array_keys($assoc_ary[0])) . ') VALUES ' . implode(', ', $ary);
 		}
 		else if ($query == 'UPDATE' || $query == 'SELECT')
 		{
@@ -435,7 +418,25 @@ class dbal
 
 		if ($this->multi_insert)
 		{
-			$this->sql_query('INSERT INTO ' . $table . ' ' . $this->sql_build_array('MULTI_INSERT', $sql_ary));
+			$ary = array();
+			foreach ($sql_ary as $id => $_sql_ary)
+			{
+				// If by accident the sql array is only one-dimensional we build a normal insert statement
+				if (!is_array($_sql_ary))
+				{
+					$query = $this->sql_build_array('INSERT', $sql_ary);
+					break;
+				}
+
+				$values = array();
+				foreach ($_sql_ary as $key => $var)
+				{
+					$values[] = $this->_sql_validate_value($var);
+				}
+				$ary[] = '(' . implode(', ', $values) . ')';
+			}
+
+			$this->sql_query('INSERT INTO ' . $table . ' ' . ' (' . implode(', ', array_keys($sql_ary[0])) . ') VALUES ' . implode(', ', $ary));
 		}
 		else
 		{
@@ -700,7 +701,7 @@ class dbal
 					</tr>
 					</tbody>
 					</table>
-					
+
 					' . $this->html_hold . '
 
 					<p style="text-align: center;">
@@ -728,24 +729,24 @@ class dbal
 			case 'start':
 				$this->query_hold = $query;
 				$this->html_hold = '';
-			
+
 				$this->_sql_report($mode, $query);
 
 				$this->curtime = explode(' ', microtime());
 				$this->curtime = $this->curtime[0] + $this->curtime[1];
 
 			break;
-			
+
 			case 'add_select_row':
 
 				$html_table = func_get_arg(2);
 				$row = func_get_arg(3);
-				
+
 				if (!$html_table && sizeof($row))
 				{
 					$html_table = true;
 					$this->html_hold .= '<table cellspacing="1"><tr>';
-								
+
 					foreach (array_keys($row) as $val)
 					{
 						$this->html_hold .= '<th>' . (($val) ? ucwords(str_replace('_', ' ', $val)) : '&nbsp;') . '</th>';
@@ -761,7 +762,7 @@ class dbal
 					$this->html_hold .= '<td class="' . $class . '">' . (($val) ? $val : '&nbsp;') . '</td>';
 				}
 				$this->html_hold .= '</tr>';
-			
+
 				return $html_table;
 
 			break;
@@ -792,7 +793,7 @@ class dbal
 			break;
 
 			default:
-			
+
 				$this->_sql_report($mode, $query);
 
 			break;