X-Git-Url: http://git.cyclocoop.org/%7B%24admin_url%7Dmes_infos.php?a=blobdiff_plain;f=includes%2Fdb%2FIDatabase.php;h=710efb2ca60b96dd66b0036b816cbf06ff8ceb0a;hb=62d543af640479a1ecbd4de69b3f975e509ca1ab;hp=1e728d80a14652c807bc8b37f974f0d8ac15351a;hpb=1f2706b49939bfc85ec5abc8ccc24aacd938eed0;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/db/IDatabase.php b/includes/db/IDatabase.php
index 1e728d80a1..710efb2ca6 100644
--- a/includes/db/IDatabase.php
+++ b/includes/db/IDatabase.php
@@ -472,7 +472,7 @@ interface IDatabase {
 	 * @return bool|mixed The value from the field, or false on failure.
 	 */
 	public function selectField(
-		$table, $var, $cond = '', $fname = __METHOD__, $options = array()
+		$table, $var, $cond = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -494,7 +494,7 @@ interface IDatabase {
 	 * @since 1.25
 	 */
 	public function selectFieldValues(
-		$table, $var, $cond = '', $fname = __METHOD__, $options = array()
+		$table, $var, $cond = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -520,9 +520,11 @@ interface IDatabase {
 	 * for use in field names (e.g. a.user_name).
 	 *
 	 * All of the table names given here are automatically run through
-	 * IDatabase::tableName(), which causes the table prefix (if any) to be
+	 * DatabaseBase::tableName(), which causes the table prefix (if any) to be
 	 * added, and various other table name mappings to be performed.
 	 *
+	 * Do not use untrusted user input as a table name. Alias names should
+	 * not have characters outside of the Basic multilingual plane.
 	 *
 	 * @param string|array $vars
 	 *
@@ -537,6 +539,7 @@ interface IDatabase {
 	 * If an expression is given, care must be taken to ensure that it is
 	 * DBMS-independent.
 	 *
+	 * Untrusted user input must not be passed to this parameter.
 	 *
 	 * @param string|array $conds
 	 *
@@ -563,6 +566,10 @@ interface IDatabase {
 	 *    - IDatabase::buildLike()
 	 *    - IDatabase::conditional()
 	 *
+	 * Untrusted user input is safe in the values of string keys, however untrusted
+	 * input must not be used in the array key names or in the values of numeric keys.
+	 * Escaping of untrusted input used in values of numeric keys should be done via
+	 * IDatabase::addQuotes()
 	 *
 	 * @param string|array $options
 	 *
@@ -628,8 +635,9 @@ interface IDatabase {
 	 *
 	 * The key of the array contains the table name or alias. The value is an
 	 * array with two elements, numbered 0 and 1. The first gives the type of
-	 * join, the second is an SQL fragment giving the join condition for that
-	 * table. For example:
+	 * join, the second is the same as the $conds parameter. Thus it can be
+	 * an SQL fragment, or an array where the string keys are equality and the
+	 * numeric keys are SQL fragments all AND'd together. For example:
 	 *
 	 *    array( 'page' => array( 'LEFT JOIN', 'page_latest=rev_id' ) )
 	 *
@@ -640,7 +648,7 @@ interface IDatabase {
 	 */
 	public function select(
 		$table, $vars, $conds = '', $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -661,7 +669,7 @@ interface IDatabase {
 	 */
 	public function selectSQLText(
 		$table, $vars, $conds = '', $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -679,7 +687,7 @@ interface IDatabase {
 	 * @return stdClass|bool
 	 */
 	public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -703,7 +711,7 @@ interface IDatabase {
 	 * @return int Row count
 	 */
 	public function estimateRowCount(
-		$table, $vars = '*', $conds = '', $fname = __METHOD__, $options = array()
+		$table, $vars = '*', $conds = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -724,7 +732,7 @@ interface IDatabase {
 	 * @return int Row count
 	 */
 	public function selectRowCount(
-		$tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = array(), $join_conds = array()
+		$tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 	);
 
 	/**
@@ -794,20 +802,20 @@ interface IDatabase {
 	 *     IDatabase::affectedRows().
 	 *
 	 * @param string $table Table name. This will be passed through
-	 *   IDatabase::tableName().
+	 *   DatabaseBase::tableName().
 	 * @param array $a Array of rows to insert
 	 * @param string $fname Calling function name (use __METHOD__) for logs/profiling
 	 * @param array $options Array of options
 	 *
 	 * @return bool
 	 */
-	public function insert( $table, $a, $fname = __METHOD__, $options = array() );
+	public function insert( $table, $a, $fname = __METHOD__, $options = [] );
 
 	/**
 	 * UPDATE wrapper. Takes a condition array and a SET array.
 	 *
 	 * @param string $table Name of the table to UPDATE. This will be passed through
-	 *   IDatabase::tableName().
+	 *   DatabaseBase::tableName().
 	 * @param array $values An array of values to SET. For each array element,
 	 *   the key gives the field name, and the value gives the data to set
 	 *   that field to. The data will be quoted by IDatabase::addQuotes().
@@ -821,7 +829,7 @@ interface IDatabase {
 	 *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
 	 * @return bool
 	 */
-	public function update( $table, $values, $conds, $fname = __METHOD__, $options = array() );
+	public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] );
 
 	/**
 	 * Makes an encoded list of strings from an array
@@ -896,7 +904,7 @@ interface IDatabase {
 	 * @since 1.23
 	 */
 	public function buildGroupConcatField(
-		$delim, $table, $field, $conds = '', $join_conds = array()
+		$delim, $table, $field, $conds = '', $join_conds = []
 	);
 
 	/**
@@ -1020,7 +1028,7 @@ interface IDatabase {
 	 *
 	 * @since 1.22
 	 *
-	 * @param string $table Table name. This will be passed through IDatabase::tableName().
+	 * @param string $table Table name. This will be passed through DatabaseBase::tableName().
 	 * @param array $rows A single row or list of rows to insert
 	 * @param array $uniqueIndexes List of single field names or field name tuples
 	 * @param array $set An array of values to SET. For each array element, the
@@ -1098,7 +1106,7 @@ interface IDatabase {
 	 */
 	public function insertSelect( $destTable, $srcTable, $varMap, $conds,
 		$fname = __METHOD__,
-		$insertOptions = array(), $selectOptions = array()
+		$insertOptions = [], $selectOptions = []
 	);
 
 	/**
@@ -1183,14 +1191,13 @@ interface IDatabase {
 	public function wasReadOnlyError();
 
 	/**
-	 * Wait for the slave to catch up to a given master position.
+	 * Wait for the slave to catch up to a given master position
 	 *
 	 * @param DBMasterPos $pos
-	 * @param int $timeout The maximum number of seconds to wait for
-	 *   synchronisation
-	 * @return int Zero if the slave was past that position already,
+	 * @param int $timeout The maximum number of seconds to wait for synchronisation
+	 * @return int|null Zero if the slave was past that position already,
 	 *   greater than zero if we waited for some period of time, less than
-	 *   zero if we timed out.
+	 *   zero if it timed out, and null on error
 	 */
 	public function masterPosWait( DBMasterPos $pos, $timeout );
 
@@ -1334,9 +1341,13 @@ interface IDatabase {
 	 * @param string $fname
 	 * @param string $flush Flush flag, set to 'flush' to disable warnings about
 	 *   explicitly committing implicit transactions, or calling commit when no
-	 *   transaction is in progress. This will silently break any ongoing
-	 *   explicit transaction. Only set the flush flag if you are sure that it
-	 *   is safe to ignore these warnings in your context.
+	 *   transaction is in progress.
+	 *
+	 *   This will trigger an exception if there is an ongoing explicit transaction.
+	 *
+	 *   Only set the flush flag if you are sure that these warnings are not applicable,
+	 *   and no explicit transactions are open.
+	 *
 	 * @throws DBUnexpectedError
 	 */
 	public function commit( $fname = __METHOD__, $flush = '' );