Merge pull request #2921 from skaut/dependabot/composer/phpstan/phpst…

…an-2.0.2

Bump phpstan/phpstan from 1.12.8 to 2.0.2

composer.json

@@ -66,7 +66,7 @@
         "symfony/polyfill-mbstring": "^1.23.0",
         "humbug/php-scoper": "^0.18.4 <0.18.5",
         "yoast/phpunit-polyfills": "^2.0",
-        "phpstan/phpstan": "^1.2",
+        "phpstan/phpstan": "^2.0",
         "slevomat/coding-standard": "^8.2",
         "phpunit/phpunit": "^10.5.24",
         "dealerdirect/phpcodesniffer-composer-installer": "^1.0"

phpcs.xml

@@ -15,7 +15,10 @@
 	<rule ref="PHPCompatibilityWP"/>
 
 	<config name="minimum_supported_wp_version" value="4.9"/>
-	<rule ref="WordPress"/>
+	<rule ref="WordPress">
+		<!-- Incorrectly doesn't count exceptions thrown from called functions -->
+		<exclude name="Squiz.Commenting.FunctionCommentThrowTag.WrongNumber"/>
+	</rule>
 	<rule ref="WordPress.Files.FileName.NotHyphenatedLowercase">
 		<exclude-pattern>scoper.inc.php</exclude-pattern>
 		<exclude-pattern>tests/</exclude-pattern>

phpmd.xml

@@ -4,7 +4,15 @@
 		xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 http://pmd.sf.net/ruleset_xml_schema.xsd"
 		xsi:noNamespaceSchemaLocation="http://pmd.sf.net/ruleset_xml_schema.xsd">
 	<rule ref="rulesets/codesize.xml"/>
-	<rule ref="rulesets/design.xml"/>
+	<rule ref="rulesets/design.xml">
+		<exclude name="CouplingBetweenObjects" />
+	</rule>
+	<rule ref="rulesets/design.xml/CouplingBetweenObjects">
+		<properties>
+			<property name="maximum" value="20" />
+        </properties>
+	</rule>
+	CouplingBetweenObjects maximum = 20
 	<rule ref="rulesets/naming.xml"/>
 	<rule ref="rulesets/unusedcode.xml"/>
 </ruleset>

src/php/admin/class-tinymce-plugin.php

@@ -9,8 +9,14 @@
 
 use Sgdg\API_Client;
 use Sgdg\API_Facade;
+use Sgdg\Exceptions\API_Exception;
+use Sgdg\Exceptions\API_Rate_Limit_Exception;
 use Sgdg\Exceptions\Cant_Edit_Exception;
+use Sgdg\Exceptions\Directory_Not_Found_Exception;
+use Sgdg\Exceptions\Internal_Exception;
+use Sgdg\Exceptions\Not_Found_Exception;
 use Sgdg\Exceptions\Plugin_Not_Authorized_Exception;
+use Sgdg\Exceptions\Unsupported_Value_Exception;
 use Sgdg\Frontend\API_Fields;
 use Sgdg\Frontend\Single_Page_Pagination_Helper;
 use Sgdg\GET_Helpers;
@@ -111,8 +117,14 @@ public static function handle_ajax() {
 	 *
 	 * @return void
 	 *
+	 * @throws API_Exception A wrapped API exception.
+	 * @throws API_Rate_Limit_Exception Rate limit exceeded.
 	 * @throws Cant_Edit_Exception Insufficient role.
+	 * @throws Directory_Not_Found_Exception The directory wasn't found.
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Not_Found_Exception The requested resource couldn't be found.
 	 * @throws Plugin_Not_Authorized_Exception Plugin not authorized.
+	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
 	 */
 	public static function ajax_handler_body() {
 		check_ajax_referer( 'sgdg_editor_plugin' );
@@ -140,6 +152,10 @@ public static function ajax_handler_body() {
 	 * @param string        $root The root directory relative to which the path is taken.
 	 *
 	 * @return PromiseInterface A list of directory names.
+	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
+	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
 	 */
 	private static function list_directories_in_path( array $path, $root ) {
 		if ( 0 === count( $path ) ) {

src/php/admin/settings-pages/basic/root-selection/class-list-ajax-endpoint.php

@@ -9,9 +9,14 @@
 
 use Sgdg\API_Client;
 use Sgdg\API_Facade;
+use Sgdg\Exceptions\API_Exception;
+use Sgdg\Exceptions\API_Rate_Limit_Exception;
 use Sgdg\Exceptions\Cant_Manage_Exception;
 use Sgdg\Exceptions\Drive_Not_Found_Exception;
 use Sgdg\Exceptions\File_Not_Found_Exception;
+use Sgdg\Exceptions\Internal_Exception;
+use Sgdg\Exceptions\Not_Found_Exception;
+use Sgdg\Exceptions\Plugin_Not_Authorized_Exception;
 use Sgdg\Frontend\API_Fields;
 use Sgdg\Frontend\Single_Page_Pagination_Helper;
 use Sgdg\GET_Helpers;
@@ -25,7 +30,7 @@
  * Handles the list_gdrive_dir ajax endpoint.
  *
  * @phan-constructor-used-for-side-effects
- * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ * @SuppressWarnings("PHPMD.CouplingBetweenObjects")
  */
 final class List_Ajax_Endpoint {
 
@@ -60,7 +65,12 @@ public static function handle_ajax() {
 	 *
 	 * @return void
 	 *
+	 * @throws API_Exception A wrapped API exception.
+	 * @throws API_Rate_Limit_Exception Rate limit exceeded.
 	 * @throws Cant_Manage_Exception Insufficient role.
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Not_Found_Exception The requested resource couldn't be found.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function ajax_handler_body() {
 		check_ajax_referer( 'sgdg_root_selection' );
@@ -117,6 +127,9 @@ static function ( $ret ) {
 	 * @param array<string> $path An array of Gooogle Drive directory IDs.
 	 *
 	 * @return PromiseInterface An array of directory names.
+	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	private static function path_ids_to_names( $path ) {
 		$promises = array();
@@ -142,6 +155,9 @@ private static function path_ids_to_names( $path ) {
 	 * Returns a list of all Shared drives plus "My Drive".
 	 *
 	 * @return PromiseInterface An array of drive records in the format `['name' => '', 'id' => '']`
+	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	private static function list_drives() {
 		return API_Facade::list_drives(

src/php/class-api-client.php

@@ -35,7 +35,7 @@
 /**
  * API client
  *
- * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ * @SuppressWarnings("PHPMD.CouplingBetweenObjects")
  */
 final class API_Client {
 
@@ -126,6 +126,8 @@ public static function get_authorized_raw_client() {
 	 * Returns a fully set-up Google Drive API client.
 	 *
 	 * @return Drive
+	 *
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function get_drive_client() {
 		$drive_client = self::$drive_client;
@@ -150,6 +152,7 @@ public static function get_drive_client() {
 	 * @return PromiseInterface A promise that will be resolved in `$callback`.
 	 *
 	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function async_request( $request, $transform, $rejection_handler = null ) {
 		self::initialize_batch();
@@ -183,6 +186,9 @@ public static function async_request( $request, $transform, $rejection_handler =
 	 * @param callable|null     $rejection_handler A function to be executed when the request fails, in the format `function( $exception ): $output` where `$exception` is the exception in question and `$output` should be a RejectedPromise.
 	 *
 	 * @return PromiseInterface A promise that will be resolved in `$callback`.
+	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function async_paginated_request(
 		$request,
@@ -255,6 +261,8 @@ public static function async_paginated_request(
 	 * @param array<int|string, PromiseInterface> $promises The promises to resolve and throw exceptions if they reject.
 	 *
 	 * @return array<int|string, mixed> A list of results from the promises. Is in the same format as the parameter `$promises`, i.e. if an associative array of promises is passed, an associative array of results will be returned.
+	 *
+	 * @throws Sgdg_Exception Any exception thrown in promises or callbacks.
 	 */
 	public static function execute( $promises = array() ) {
 		self::execute_current_batch();
@@ -271,6 +279,8 @@ public static function execute( $promises = array() ) {
 	 * Sets up request batching.
 	 *
 	 * @return void
+	 *
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	private static function initialize_batch() {
 		if ( ! is_null( self::$current_batch ) ) {
@@ -289,6 +299,8 @@ private static function initialize_batch() {
 	 * Executes the current batch request and calls its callbacks
 	 *
 	 * @return void
+	 *
+	 * @throws Sgdg_Exception Any exception thrown in promises or callbacks.
 	 */
 	private static function execute_current_batch() {
 		$batch = self::$current_batch;

src/php/class-api-facade.php

@@ -8,12 +8,12 @@
 namespace Sgdg;
 
 use Sgdg\API_Client;
-use Sgdg\Exceptions\API_Exception;
-use Sgdg\Exceptions\API_Rate_Limit_Exception;
 use Sgdg\Exceptions\Directory_Not_Found_Exception;
 use Sgdg\Exceptions\Drive_Not_Found_Exception;
 use Sgdg\Exceptions\File_Not_Found_Exception;
+use Sgdg\Exceptions\Internal_Exception;
 use Sgdg\Exceptions\Not_Found_Exception;
+use Sgdg\Exceptions\Plugin_Not_Authorized_Exception;
 use Sgdg\Exceptions\Unsupported_Value_Exception;
 use Sgdg\Frontend\API_Fields;
 use Sgdg\Frontend\Pagination_Helper;
@@ -34,7 +34,8 @@ final class API_Facade {
 	 *
 	 * @return PromiseInterface A promise resolving to the ID of the directory.
 	 *
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function get_directory_id( $parent_id, $name ) {
 		$params = array(
@@ -81,7 +82,10 @@ static function ( $response ) use ( $name ) {
 	 *
 	 * @return PromiseInterface A promise resolving to the name of the drive.
 	 *
-	 * @SuppressWarnings(PHPMD.ShortVariable)
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
+	 *
+	 * @SuppressWarnings("PHPMD.ShortVariable")
 	 */
 	public static function get_drive_name( $id ) {
 		return API_Client::async_request(
@@ -112,16 +116,12 @@ static function ( $exception ) {
 	 *
 	 * @return PromiseInterface A promise resolving to the name of the directory.
 	 *
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 *
-	 * @SuppressWarnings(PHPMD.ShortVariable)
+	 * @SuppressWarnings("PHPMD.ShortVariable")
 	 */
 	public static function get_file_name( $id ) {
-		/**
-		 * `$transform` transforms the raw Google API response into the structured response this function returns.
-		 *
-		 * @throws File_Not_Found_Exception The file/directory wasn't found.
-		 */
 		return API_Client::async_request(
 			// @phan-suppress-next-line PhanTypeMismatchArgument
 			API_Client::get_drive_client()->files->get(
@@ -131,6 +131,11 @@ public static function get_file_name( $id ) {
 					'supportsAllDrives' => true,
 				)
 			),
+			/**
+			 * `$transform` transforms the raw Google API response into the structured response this function returns.
+			 *
+			 * @throws File_Not_Found_Exception The file/directory wasn't found.
+			 */
 			static function ( $response ) {
 				if ( $response->getTrashed() ) {
 					throw new File_Not_Found_Exception();
@@ -156,19 +161,23 @@ static function ( $exception ) {
 	 *
 	 * @return PromiseInterface A promise resolving if the directory is valid.
 	 *
-	 * @SuppressWarnings(PHPMD.ShortVariable)
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
+	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
+	 *
+	 * @SuppressWarnings("PHPMD.ShortVariable")
 	 */
 	public static function check_directory_in_directory( $id, $parent_id ) {
-		/**
-		 * `$transform` transforms the raw Google API response into the structured response this function returns.
-		 *
-		 * @throws Directory_Not_Found_Exception The directory wasn't found.
-		 */
 		return self::list_directories(
 			$parent_id,
 			new API_Fields( array( 'id', 'trashed' ) ),
 			new Single_Page_Pagination_Helper()
 		)->then(
+			/**
+			 * `$transform` transforms the raw Google API response into the structured response this function returns.
+			 *
+			 * @throws Directory_Not_Found_Exception The directory wasn't found.
+			 */
 			static function ( $directories ) use ( $id ) {
 				foreach ( $directories as $directory ) {
 					if ( $directory['id'] === $id && ! boolval( $directory['trashed'] ) ) {
@@ -195,7 +204,8 @@ static function ( $exception ) {
 	 *
 	 * @return PromiseInterface A promise resolving to a list of drives in the format `[ 'id' => '', 'name' => '' ]`.
 	 *
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 */
 	public static function list_drives( $pagination_helper ) {
 		return API_Client::async_paginated_request(
@@ -233,8 +243,9 @@ static function ( $drive ) {
 	 *
 	 * @return PromiseInterface A promise resolving to a list of directories in the format `[ 'id' => '', 'name' => '' ]`- the fields of each directory are givent by the parameter `$fields`.
 	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
 	 */
 	public static function list_directories( $parent_id, $fields, $pagination_helper, $order_by = 'name' ) {
 		return self::list_files(
@@ -256,8 +267,9 @@ public static function list_directories( $parent_id, $fields, $pagination_helper
 	 *
 	 * @return PromiseInterface A promise resolving to a list of images in the format `[ 'id' => '', 'name' => '' ]`- the fields of each directory are givent by the parameter `$fields`.
 	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
 	 */
 	public static function list_images( $parent_id, $fields, $pagination_helper, $order_by = 'name' ) {
 		return self::list_files( $parent_id, $fields, $order_by, $pagination_helper, 'image/' );
@@ -273,8 +285,9 @@ public static function list_images( $parent_id, $fields, $pagination_helper, $or
 	 *
 	 * @return PromiseInterface A promise resolving to a list of images in the format `[ 'id' => '', 'name' => '' ]`- the fields of each directory are givent by the parameter `$fields`.
 	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
-	 * @throws API_Exception|API_Rate_Limit_Exception A problem with the API.
 	 */
 	public static function list_videos( $parent_id, $fields, $pagination_helper, $order_by = 'name' ) {
 		return self::list_files( $parent_id, $fields, $order_by, $pagination_helper, 'video/' );
@@ -291,6 +304,8 @@ public static function list_videos( $parent_id, $fields, $pagination_helper, $or
 	 *
 	 * @return PromiseInterface A promise resolving to a list of files in the format `[ 'id' => '', 'name' => '' ]`- the fields of each file are given by the parameter `$fields`.
 	 *
+	 * @throws Internal_Exception The method was called without an initialized batch.
+	 * @throws Plugin_Not_Authorized_Exception Not authorized.
 	 * @throws Unsupported_Value_Exception A field that is not supported was passed in `$fields`.
 	 */
 	private static function list_files( $parent_id, $fields, $order_by, $pagination_helper, $mime_type_prefix ) {