[ticket/16955] Fix another batch of docblocks

PHPBB3-16955

phpBB/phpbb/language/language.php

@@ -298,7 +298,7 @@ class language
 
 		if ($lang === $key)
 		{
-			return $key;
+			return (string) $key;
 		}
 
 		// If the language entry is a string, we simply mimic sprintf() behaviour
@@ -315,7 +315,7 @@ class language
 		else if (count($lang) == 0)
 		{
 			// If the language entry is an empty array, we just return the language key
-			return $key;
+			return (string) $key;
 		}
 
 		// It is an array... now handle different nullar/singular/plural forms
@@ -406,13 +406,6 @@ class language
 		$number			= (int) $number;
 		$plural_rule	= ($force_rule !== false) ? $force_rule : ((isset($this->lang['PLURAL_RULE'])) ? $this->lang['PLURAL_RULE'] : 1);
 
-		if ($plural_rule > 15 || $plural_rule < 0)
-		{
-			throw new invalid_plural_rule_exception('INVALID_PLURAL_RULE', array(
-				'plural_rule' => $plural_rule,
-			));
-		}
-
 		/**
 		 * The following plural rules are based on a list published by the Mozilla Developer Network
 		 * https://developer.mozilla.org/en/Localization_and_Plurals
@@ -565,6 +558,9 @@ class language
 				 * 2 - everything else: 0, 2, 3, ... 10, 11, 12, ... 20, 22, ...
 				 */
 				return (($number % 10 === 1) && ($number % 100 != 11)) ? 1 : 2;
+
+			default:
+				throw new invalid_plural_rule_exception('INVALID_PLURAL_RULE', ['plural_rule' => $plural_rule]);
 		}
 	}
 

phpBB/phpbb/lock/flock.php

@@ -27,7 +27,7 @@ class flock
 
 	/**
 	* File pointer for the lock file
-	* @var string|bool
+	* @var resource|closed-resource|false
 	*/
 	private $lock_fp;
 
@@ -130,7 +130,7 @@ class flock
 	* Note: Attempting to release a lock that is already released,
 	* that is, calling release() multiple times, is harmless.
 	*
-	* @return null
+	* @return void
 	*/
 	public function release()
 	{

phpBB/phpbb/log/log.php

@@ -764,7 +764,14 @@ class log implements \phpbb\log\log_interface
 				}
 
 				$log[$key]['reportee_username'] = $reportee_data_list[$row['reportee_id']]['username'];
-				$log[$key]['reportee_username_full'] = get_username_string('full', $row['reportee_id'], $reportee_data_list[$row['reportee_id']]['username'], $reportee_data_list[$row['reportee_id']]['user_colour'], false, $profile_url);
+				$log[$key]['reportee_username_full'] = get_username_string(
+					'full',
+					$row['reportee_id'],
+					$reportee_data_list[$row['reportee_id']]['username'],
+					$reportee_data_list[$row['reportee_id']]['user_colour'],
+					false,
+					$profile_url
+				);
 			}
 		}
 

phpBB/phpbb/mention/source/base_user.php

@@ -34,8 +34,8 @@ abstract class base_user implements source_interface
 	/** @var string */
 	protected $php_ext;
 
-	/** @var string|false */
-	protected $cache_ttl = false;
+	/** @var int */
+	protected $cache_ttl = 0;
 
 	/**
 	 * base_user constructor.

phpBB/phpbb/mention/source/group.php

@@ -15,7 +15,7 @@ namespace phpbb\mention\source;
 
 class group extends base_group
 {
-	/** @var string|false */
+	/** @var int */
 	protected $cache_ttl = 300;
 
 	/**

phpBB/phpbb/mention/source/team.php

@@ -15,7 +15,7 @@ namespace phpbb\mention\source;
 
 class team extends base_user
 {
-	/** @var string|false */
+	/** @var int */
 	protected $cache_ttl = 300;
 
 	/**

phpBB/phpbb/message/message.php

@@ -234,7 +234,7 @@ class message
 	*
 	* @param \messenger $messenger
 	* @param string $contact
-	* @return null
+	* @return void
 	*/
 	public function send(\messenger $messenger, $contact)
 	{

phpBB/phpbb/mimetype/content_guesser.php

@@ -28,6 +28,6 @@ class content_guesser extends guesser_base
 	*/
 	public function guess($file, $file_name = '')
 	{
-		return mime_content_type($file);
+		return mime_content_type($file) ?: null;
 	}
 }

phpBB/phpbb/mimetype/extension_guesser.php

@@ -425,7 +425,6 @@ class extension_guesser extends guesser_base
 		'wb1'		=> 'application/x-qpro',
 		'wbmp'		=> 'image/vnd.wap.wbmp',
 		'web'		=> 'application/vnd.xara',
-		'webm'		=> 'audio/webm',
 		'webm'		=> 'video/webm',
 		'wiz'		=> 'application/msword',
 		'wk1'		=> 'application/x-123',
@@ -505,13 +504,6 @@ class extension_guesser extends guesser_base
 	{
 		$extension = pathinfo($file_name, PATHINFO_EXTENSION);
 
-		if (isset($this->extension_map[$extension]))
-		{
-			return $this->extension_map[$extension];
-		}
-		else
-		{
-			return null;
-		}
+		return $this->extension_map[$extension] ?? null;
 	}
 }

phpBB/phpbb/mimetype/guesser.php

@@ -102,7 +102,7 @@ class guesser
 	* @param string $file Path to file
 	* @param string $file_name The real file name
 	*
-	* @return string Guess for mimetype of file
+	* @return string|false Guess for mimetype of file or false if file can't be opened
 	*/
 	public function guess($file, $file_name = '')
 	{
@@ -140,13 +140,13 @@ class guesser
 	 * will always overwrite the default application/octet-stream.
 	 *
 	 * @param	string	$mime_type	The current mime type
-	 * @param	string	$guess		The current mime type guess
+	 * @param	string|null|false	$guess		The current mime type guess
 	 *
 	 * @return string The best mime type based on current mime type and guess
 	 */
 	public function choose_mime_type($mime_type, $guess)
 	{
-		if ($guess === null || $guess == 'application/octet-stream')
+		if ($guess === false || $guess === null || $guess == 'application/octet-stream')
 		{
 			return $mime_type;
 		}

phpBB/phpbb/mimetype/guesser_interface.php

@@ -28,7 +28,7 @@ interface guesser_interface
 	* @param string $file Path to file
 	* @param string $file_name The real file name
 	*
-	* @return string Guess for mimetype of file
+	* @return string|null Guess for mimetype of file
 	*/
 	public function guess($file, $file_name = '');
 

phpBB/phpbb/pagination.php

@@ -285,11 +285,12 @@ class pagination
 	*
 	* @param int $per_page the number of items, posts, etc. per page
 	* @param int $start the item which should be considered currently active, used to determine the page we're on
+	*
 	* @return int	Current page number
 	*/
-	public function get_on_page($per_page, $start)
+	public function get_on_page(int $per_page, int $start): int
 	{
-		return floor((int) $start / (int) $per_page) + 1;
+		return (int) floor($start / $per_page) + 1;
 	}
 
 	/**
@@ -318,7 +319,7 @@ class pagination
 	{
 		if ($start < 0 || $start >= $num_items)
 		{
-			return ($start < 0 || $num_items <= 0) ? 0 : floor(($num_items - 1) / $per_page) * $per_page;
+			return ($start < 0 || $num_items <= 0) ? 0 : (int) floor(($num_items - 1) / $per_page) * $per_page;
 		}
 
 		return $start;

phpBB/phpbb/passwords/driver/driver_interface.php

@@ -63,7 +63,7 @@ interface driver_interface
 	* @param string		$hash Password hash
 	* @param bool		$full Return full settings or only settings
 	*			related to the salt
-	* @return string	String containing the hash settings
+	* @return string|false	String containing the hash settings or false if settings are empty or not supported
 	*/
 	public function get_settings_only($hash, $full = false);
 }

phpBB/phpbb/passwords/helper.php

@@ -50,8 +50,8 @@ class helper
 	* @param string $type Data type of the supplied value
 	* @param string $value Value that should be put into the data array
 	*
-	* @return string|null Return complete combined hash if type is neither
-	*			'prefix' nor 'settings', nothing if it is
+	* @return string|false Return complete combined hash if type is neither
+	*			'prefix' nor 'settings', false if it is
 	*/
 	public function combine_hash_output(&$data, $type, $value)
 	{
@@ -70,6 +70,8 @@ class helper
 			// Return full hash
 			return $data['prefix'] . $data['settings'] . '$' . $value;
 		}
+
+		return false;
 	}
 
 	/**

phpBB/phpbb/passwords/manager.php

@@ -115,7 +115,7 @@ class manager
 	/**
 	* Fill algorithm type map
 	*
-	* @param \phpbb\di\service_collection $hashing_algorithms
+	* @param \phpbb\di\service_collection|array $hashing_algorithms
 	*/
 	protected function fill_type_map($hashing_algorithms)
 	{
@@ -154,7 +154,7 @@ class manager
 	*
 	* @param string $hash Password hash that should be checked
 	*
-	* @return object|bool The hash type object or false if the specified
+	* @return array|bool|object The hash type object or false if the specified
 	*			type is not supported
 	*/
 	public function detect_algorithm($hash)
@@ -276,7 +276,7 @@ class manager
 
 		// First find out what kind of hash we're dealing with
 		$stored_hash_type = $this->detect_algorithm($hash);
-		if ($stored_hash_type == false)
+		if (!$stored_hash_type)
 		{
 			// Still check MD5 hashes as that is what the installer
 			// will default to for the admin user

phpBB/phpbb/php/ini.php

@@ -137,15 +137,18 @@ class ini
 			// Already in bytes.
 			return phpbb_to_numeric($value);
 		}
-		else if (strlen($value) < 2)
+		else if (is_string($value))
 		{
-			// Single character.
-			return false;
-		}
-		else if (strlen($value) < 3 && $value[0] === '-')
-		{
-			// Two characters but the first one is a minus.
-			return false;
+			if (strlen($value) < 2)
+			{
+				// Single character.
+				return false;
+			}
+			else if (strlen($value) < 3 && $value[0] === '-')
+			{
+				// Two characters but the first one is a minus.
+				return false;
+			}
 		}
 
 		$value_lower = strtolower($value);

phpBB/phpbb/plupload/plupload.php

@@ -29,7 +29,7 @@ class plupload
 	protected $config;
 
 	/**
-	* @var \phpbb\request\request_interface
+	* @var \phpbb\request\request
 	*/
 	protected $request;
 
@@ -65,12 +65,12 @@ class plupload
 	*
 	* @param string $phpbb_root_path
 	* @param \phpbb\config\config $config
-	* @param \phpbb\request\request_interface $request
+	* @param \phpbb\request\request $request
 	* @param \phpbb\user $user
 	* @param \bantu\IniGetWrapper\IniGetWrapper $php_ini
 	* @param \phpbb\mimetype\guesser $mimetype_guesser
 	*/
-	public function __construct($phpbb_root_path, \phpbb\config\config $config, \phpbb\request\request_interface $request, \phpbb\user $user, \bantu\IniGetWrapper\IniGetWrapper $php_ini, \phpbb\mimetype\guesser $mimetype_guesser)
+	public function __construct($phpbb_root_path, \phpbb\config\config $config, \phpbb\request\request $request, \phpbb\user $user, \bantu\IniGetWrapper\IniGetWrapper $php_ini, \phpbb\mimetype\guesser $mimetype_guesser)
 	{
 		$this->phpbb_root_path = $phpbb_root_path;
 		$this->config = $config;
@@ -308,7 +308,7 @@ class plupload
 			}
 		}
 
-		return floor($max / 2);
+		return (int) floor($max / 2);
 	}
 
 	protected function temporary_filepath($file_name)

phpBB/phpbb/profilefields/lang_helper.php

@@ -126,7 +126,7 @@ class lang_helper
 	* @param	int		$field_id		Database ID of the field
 	* @param	int		$lang_id		ID of the language
 	* @param	int		$field_value	Selected value of the field
-	* @return string
+	* @return string|array
 	*/
 	public function get($field_id, $lang_id, $field_value = null)
 	{

phpBB/phpbb/profilefields/type/type_base.php

@@ -183,8 +183,7 @@ abstract class type_base implements type_interface
 	}
 
 	/**
-	* Return templated value/field. Possible values for $mode are:
-	* change == user is able to set/enter profile values; preview == just show the value
+	* {@inheritDoc}
 	*/
 	public function process_field_row($mode, $profile_row)
 	{
@@ -201,6 +200,7 @@ abstract class type_base implements type_interface
 		// Assign template variables
 		$this->generate_field($profile_row, $preview_options);
 
-		return $this->template->assign_display('cp_body');
+		$compiled_template = $this->template->assign_display('cp_body');
+		return is_string($compiled_template) ? $compiled_template : '';
 	}
 }

phpBB/phpbb/profilefields/type/type_bool.php

@@ -232,13 +232,16 @@ class type_bool extends type_base
 			}
 
 			$options = $this->lang_helper->get($profile_row['field_id'], $profile_row['lang_id']);
-			foreach ($options as $option_id => $option_value)
+			if (is_array($options))
 			{
-				$this->template->assign_block_vars('bool.options', array(
-					'OPTION_ID'	=> $option_id,
-					'CHECKED'	=> ($value == $option_id) ? ' checked="checked"' : '',
-					'VALUE'		=> $option_value,
-				));
+				foreach ($options as $option_id => $option_value)
+				{
+					$this->template->assign_block_vars('bool.options', array(
+						'OPTION_ID'	=> $option_id,
+						'CHECKED'	=> ($value == $option_id) ? ' checked="checked"' : '',
+						'VALUE'		=> $option_value,
+					));
+				}
 			}
 		}
 	}

phpBB/phpbb/profilefields/type/type_dropdown.php

@@ -233,13 +233,16 @@ class type_dropdown extends type_base
 		$this->template->assign_block_vars('dropdown', array_change_key_case($profile_row, CASE_UPPER));
 
 		$options = $this->lang_helper->get($profile_row['field_id'], $profile_row['lang_id']);
-		foreach ($options as $option_id => $option_value)
+		if (is_array($options))
 		{
-			$this->template->assign_block_vars('dropdown.options', array(
-				'OPTION_ID'	=> $option_id,
-				'SELECTED'	=> ($value == $option_id) ? ' selected="selected"' : '',
-				'VALUE'		=> $option_value,
-			));
+			foreach ($options as $option_id => $option_value)
+			{
+				$this->template->assign_block_vars('dropdown.options', array(
+					'OPTION_ID'	=> $option_id,
+					'SELECTED'	=> ($value == $option_id) ? ' selected="selected"' : '',
+					'VALUE'		=> $option_value,
+				));
+			}
 		}
 	}
 

phpBB/phpbb/profilefields/type/type_interface.php

@@ -220,7 +220,7 @@ interface type_interface
 	*
 	* @param string	$mode			Mode for displaying the field (preview|change)
 	* @param array	$profile_row	Array with data for this field
-	* @return null
+	* @return string
 	*/
 	public function process_field_row($mode, $profile_row);
 }

phpBB/phpbb/report/controller/report.php

@@ -14,6 +14,7 @@
 namespace phpbb\report\controller;
 
 use phpbb\exception\http_exception;
+use phpbb\report\report_handler_interface;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 
 class report
@@ -61,6 +62,9 @@ class report
 	/**
 	 * @var \phpbb\report\handler_factory
 	 */
+	protected $report_factory;
+
+	/** @var report_handler_interface */
 	protected $report_handler;
 
 	/**
@@ -78,7 +82,7 @@ class report
 		$this->phpbb_root_path	= $phpbb_root_path;
 		$this->php_ext			= $php_ext;
 		$this->captcha_factory	= $captcha_factory;
-		$this->report_handler	= $report_factory;
+		$this->report_factory	= $report_factory;
 
 		// User interface factory
 		$this->report_reason_provider = $ui_provider;
@@ -97,7 +101,7 @@ class report
 	public function handle($id, $mode)
 	{
 		// Get report handler
-		$this->report_handler = $this->report_handler->get_instance($mode);
+		$this->report_handler = $this->report_factory->get_instance($mode);
 
 		$this->user->add_lang('mcp');
 

phpBB/phpbb/report/handler_factory.php

@@ -36,21 +36,28 @@ class handler_factory
 	 * Return a new instance of an appropriate report handler
 	 *
 	 * @param string	$type
-	 * @return \phpbb\report\report_handler_interface
+	 * @return report_handler_interface
 	 * @throws factory_invalid_argument_exception if $type is not valid
 	 */
 	public function get_instance($type)
 	{
+		$report_handler = null;
 		switch ($type)
 		{
 			case 'pm':
-				return $this->container->get('phpbb.report.handlers.report_handler_pm');
+				$report_handler = $this->container->get('phpbb.report.handlers.report_handler_pm');
 			break;
+
 			case 'post':
-				return $this->container->get('phpbb.report.handlers.report_handler_post');
+				$report_handler =  $this->container->get('phpbb.report.handlers.report_handler_post');
 			break;
 		}
 
+		if ($report_handler instanceof report_handler_interface)
+		{
+			return $report_handler;
+		}
+
 		throw new factory_invalid_argument_exception();
 	}
 }

phpBB/phpbb/report/report_handler.php

@@ -99,6 +99,6 @@ abstract class report_handler implements report_handler_interface
 		$sql = 'INSERT INTO ' . REPORTS_TABLE . ' ' . $this->db->sql_build_array('INSERT', $sql_ary);
 		$this->db->sql_query($sql);
 
-		return $this->db->sql_nextid();
+		return (int) $this->db->sql_nextid();
 	}
 }