From 24d64c75579985cf3452039689986378059e466c Mon Sep 17 00:00:00 2001
From: Umherirrender <umherirrender_de.wp@web.de>
Date: Mon, 30 Aug 2021 22:08:17 +0200
Subject: [PATCH] docs: Declare UserArray/TitleArray as
 Iterator<User>/Iterator<Title>

Declaring the abstract functions and using return type hints helps
phan to understands foreach loop over TitleArray objects

$extraPages = TitleArray::newFromResult( ... );
foreach ( $extraPages as $oldSubpage ) {
	$oldSubpage->getDBkey();
}

It also helps phan-seccheck to decide another issue type in
UploadFromFile

Change-Id: I5f9a0dd5578bd9b585fb4d086a3e133a5ca35cf6
---
 includes/TitleArray.php               | 12 ++++++++++++
 includes/TitleArrayFromResult.php     |  6 ++++--
 includes/upload/UploadFromFile.php    |  2 +-
 includes/user/UserArray.php           | 10 ++++++++++
 includes/user/UserArrayFromResult.php |  9 +++------
 5 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/includes/TitleArray.php b/includes/TitleArray.php
index b1de396732e..652b9375b9f 100644
--- a/includes/TitleArray.php
+++ b/includes/TitleArray.php
@@ -29,6 +29,8 @@ use Wikimedia\Rdbms\IResultWrapper;
 /**
  * The TitleArray class only exists to provide the newFromResult method at pre-
  * sent.
+ * The documentation of the return types for the abstract current/key functions
+ * helps static code analyzer to treat this as Iterator<Title>
  *
  * @method int count()
  */
@@ -44,4 +46,14 @@ abstract class TitleArray implements Iterator {
 		// TitleArrayFromResult hook has been removed
 		return new TitleArrayFromResult( $res );
 	}
+
+	/**
+	 * @return Title
+	 */
+	abstract public function current(): Title;
+
+	/**
+	 * @return int
+	 */
+	abstract public function key(): int;
 }
diff --git a/includes/TitleArrayFromResult.php b/includes/TitleArrayFromResult.php
index 71b959564e6..6dd89b79d65 100644
--- a/includes/TitleArrayFromResult.php
+++ b/includes/TitleArrayFromResult.php
@@ -35,8 +35,10 @@ class TitleArrayFromResult extends TitleArray implements Countable {
 	/** @var IResultWrapper */
 	public $res;
 
+	/** @var int */
 	public $key;
 
+	/** @var Title|false */
 	public $current;
 
 	/**
@@ -69,11 +71,11 @@ class TitleArrayFromResult extends TitleArray implements Countable {
 		return $this->res->numRows();
 	}
 
-	public function current() {
+	public function current(): Title {
 		return $this->current;
 	}
 
-	public function key() {
+	public function key(): int {
 		return $this->key;
 	}
 
diff --git a/includes/upload/UploadFromFile.php b/includes/upload/UploadFromFile.php
index 875e3a18a82..47cbe7bd255 100644
--- a/includes/upload/UploadFromFile.php
+++ b/includes/upload/UploadFromFile.php
@@ -53,7 +53,7 @@ class UploadFromFile extends UploadBase {
 	 */
 	public function initialize( $name, $webRequestUpload ) {
 		$this->mUpload = $webRequestUpload;
-		// @phan-suppress-next-line SecurityCheckMulti False positive T268920
+		// @phan-suppress-next-line SecurityCheck-PathTraversal False positive T268920
 		$this->initializePathInfo( $name,
 			$this->mUpload->getTempName(), $this->mUpload->getSize() );
 	}
diff --git a/includes/user/UserArray.php b/includes/user/UserArray.php
index 834388993ac..969b76be8ac 100644
--- a/includes/user/UserArray.php
+++ b/includes/user/UserArray.php
@@ -96,4 +96,14 @@ abstract class UserArray implements Iterator {
 		);
 		return self::newFromResult( $res );
 	}
+
+	/**
+	 * @return User
+	 */
+	abstract public function current(): User;
+
+	/**
+	 * @return int
+	 */
+	abstract public function key(): int;
 }
diff --git a/includes/user/UserArrayFromResult.php b/includes/user/UserArrayFromResult.php
index 71208d43e6b..e24d9d540ea 100644
--- a/includes/user/UserArrayFromResult.php
+++ b/includes/user/UserArrayFromResult.php
@@ -29,7 +29,7 @@ class UserArrayFromResult extends UserArray implements Countable {
 	/** @var int */
 	public $key;
 
-	/** @var bool|User */
+	/** @var User|false */
 	public $current;
 
 	/**
@@ -60,14 +60,11 @@ class UserArrayFromResult extends UserArray implements Countable {
 		return $this->res->numRows();
 	}
 
-	/**
-	 * @return User
-	 */
-	public function current() {
+	public function current(): User {
 		return $this->current;
 	}
 
-	public function key() {
+	public function key(): int {
 		return $this->key;
 	}