Jetpack: Fix various PhanUndefined issues (#37344)

Notable changes:

* Remove `Jetpack_User_Agent_Info::is_OperaMobile()`. #16434 removed the
  jetpack-device-detect function this was calling in October 2021, but
  missed this caller.
* Remove `jetpack_server_sandbox()` and
  `jetpack_server_sandbox_request_parameters()`. Due to a wrong
  namespace in #21128, they'd have thrown fatals since October 2021.
* Use `$skin` instead of `$upgrader->skin`, it's the same object but not
  typed as a parent class. Should be no change to functionality.
* Add some missing methods to `WPCOM_JSON_API`.
* Add some missing abstract methods to SAL_Site, and implement in
  Jetpack_Site.
* Fix `SAL_Token::is_global()`.
* Remove `views/admin/deactivation-dialog.php`, unused since #21048 in
  November 2021.
* Add `@phan-var-force` in a lot of "template" files. I'm not entirely
  happy with this, it pollutes the global scope for any subsequent files
  processed, but short of writing a Phan plugin that somehow adjusts the
  scope for only the file I can't find a better idea.

projects/packages/sync/changelog/fix-misc-phan-undeclared-issues

@@ -0,0 +1,4 @@
+Significance: patch
+Type: fixed
+
+Fix phpdoc type on `Replicastore_Interface::get_term()` `$taxonomy` arg.

projects/packages/sync/src/class-replicastore.php

@@ -874,9 +874,9 @@ public function get_terms( $taxonomy ) {
 	 *
 	 * @access public
 	 *
-	 * @param string $taxonomy   Taxonomy slug.
-	 * @param int    $term_id    ID of the term.
-	 * @param string $term_key   ID Field `term_id` or `term_taxonomy_id`.
+	 * @param string|false $taxonomy   Taxonomy slug.
+	 * @param int          $term_id    ID of the term.
+	 * @param string       $term_key   ID Field `term_id` or `term_taxonomy_id`.
 	 *
 	 * @return \WP_Term|WP_Error Term object on success, \WP_Error object on failure.
 	 */

projects/packages/sync/src/interface-replicastore.php

@@ -414,9 +414,9 @@ public function get_terms( $taxonomy );
 	 *
 	 * @access public
 	 *
-	 * @param string $taxonomy   Taxonomy slug.
-	 * @param int    $term_id    ID of the term.
-	 * @param string $term_key   ID Field `term_id` or `term_taxonomy_id`.
+	 * @param string|false $taxonomy   Taxonomy slug.
+	 * @param int          $term_id    ID of the term.
+	 * @param string       $term_key   ID Field `term_id` or `term_taxonomy_id`.
 	 */
 	public function get_term( $taxonomy, $term_id, $term_key = 'term_id' );
 

projects/plugins/jetpack/_inc/lib/core-api/load-wpcom-endpoints.php

@@ -42,8 +42,7 @@ function wpcom_rest_api_v2_load_plugin( $class_name ) {
 	global $wpcom_rest_api_v2_plugins;
 
 	if ( ! isset( $wpcom_rest_api_v2_plugins ) ) {
-		$wpcom_rest_api_v2_plugins             = array();
-		$_GLOBALS['wpcom_rest_api_v2_plugins'] = array(); // phpcs:ignore WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase,VariableAnalysis.CodeAnalysis.VariableAnalysis.UndefinedVariable
+		$wpcom_rest_api_v2_plugins = array();
 	}
 
 	if ( ! isset( $wpcom_rest_api_v2_plugins[ $class_name ] ) ) {

projects/plugins/jetpack/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-newsletter-categories-list.php

@@ -64,11 +64,11 @@ public function register_routes() {
 	public function get_newsletter_categories() {
 		require_lib( 'newsletter-categories' );
 
-		$newsletter_categories = get_newsletter_categories();
+		$newsletter_categories = \Newsletter_Categories\get_newsletter_categories();
 
 		// Include subscription counts for each category if the user can manage categories.
 		if ( $this->can_manage_categories() === true ) {
-			$subscription_counts_per_category = get_blog_subscription_counts_per_category();
+			$subscription_counts_per_category = \Newsletter_Categories\get_blog_subscription_counts_per_category();
 			array_walk(
 				$newsletter_categories,
 				function ( &$category ) use ( $subscription_counts_per_category ) {

projects/plugins/jetpack/_inc/lib/core-api/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-newsletter-categories-subscriptions-count.php

@@ -76,7 +76,7 @@ public function get_newsletter_categories_subscriptions_count( WP_REST_Request $
 		$blog_id  = get_current_blog_id();
 		$term_ids = explode( ',', $request->get_param( 'term_ids' ) );
 
-		$subscriptions_count = get_blog_subscriptions_aggregate_count( $blog_id, $term_ids );
+		$subscriptions_count = \Newsletter_Categories\get_blog_subscriptions_aggregate_count( $blog_id, $term_ids );
 
 		return rest_ensure_response(
 			array(

projects/plugins/jetpack/_inc/lib/markdown/extra.php

@@ -2608,6 +2608,7 @@ function _doTable_callback($matches) {
 
 		# Reading alignement from header underline.
 		$separators	= preg_split('/ *[|] */', $underline);
+		$attr = array();
 		foreach ($separators as $n => $s) {
 			if (preg_match('/^ *-+: *$/', $s))		$attr[$n] = ' align="right"';
 			else if (preg_match('/^ *:-+: *$/', $s))$attr[$n] = ' align="center"';

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues

@@ -0,0 +1,5 @@
+Significance: patch
+Type: other
+Comment: #16434 removed the jetpack-device-detect function this was calling, but missed this caller.
+
+Remove `Jetpack_User_Agent_Info::is_OperaMobile()`, it would have thrown fatals since October 2021.

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#2

@@ -0,0 +1,5 @@
+Significance: patch
+Type: other
+Comment: Due to a wrong namespace in #21128, the stubs never actually worked.
+
+Remove `jetpack_server_sandbox()` and `jetpack_server_sandbox_request_parameters()`. They'd have thrown fatals since October 2021.

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#3

@@ -0,0 +1,5 @@
+Significance: patch
+Type: other
+Comment: Use `$skin` instead of `$upgrader->skin`, it's the same object but not typed as a parent class. Should be no change to functionality.
+
+

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#4

@@ -0,0 +1,5 @@
+Significance: patch
+Type: other
+Comment: Add some missing methods to `WPCOM_JSON_API`.
+
+

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#5

@@ -0,0 +1,4 @@
+Significance: patch
+Type: other
+
+Add some missing abstract methods to SAL_Site, and implement in Jetpack_Site.

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#6

@@ -0,0 +1,4 @@
+Significance: patch
+Type: other
+
+Fix `SAL_Token::is_global()`.

projects/plugins/jetpack/changelog/fix-misc-phan-undeclared-issues#7

@@ -0,0 +1,5 @@
+Significance: patch
+Type: other
+Comment: Remove views/admin/deactivation-dialog.php, unused since #21048.
+
+

projects/plugins/jetpack/class.jetpack-cli.php

@@ -23,6 +23,7 @@
 	return;
 }
 
+// @phan-suppress-next-line PhanUndeclaredFunctionInCallable -- https://github.com/phan/phan/issues/4763
 WP_CLI::add_command( 'jetpack', 'Jetpack_CLI' );
 
 /**
@@ -1866,9 +1867,11 @@ public function publicize( $args, $named_args ) {
 								);
 							}
 
+							// @phan-suppress-next-line PhanUndeclaredClassMethod - Class is missing from php-stubs/wp-cli-stubs 🤷
 							$progress->tick();
 						}
 
+						// @phan-suppress-next-line PhanUndeclaredClassMethod - Class is missing from php-stubs/wp-cli-stubs 🤷
 						$progress->finish();
 
 						if ( 'all' === $service ) {

projects/plugins/jetpack/class.jetpack-user-agent.php

@@ -330,19 +330,6 @@ public static function is_opera_mini_dumb() {
 		return User_Agent_Info::is_opera_mini_dumb();
 	}
 
-	/**
-	 * Detects if the current browser is Opera Mobile or Mini.
-	 *
-	 * Opera Mini 5 Beta: Opera/9.80 (J2ME/MIDP; Opera Mini/5.0.15650/756; U; en) Presto/2.2.0
-	 * Opera Mini 8: Opera/8.01 (J2ME/MIDP; Opera Mini/3.0.6306/1528; en; U; ssr)
-	 *
-	 * @deprecated 8.7.0 Use Automattic\Jetpack\Device_Detection\User_Agent_Info
-	 */
-	public static function is_OperaMobile() {
-		self::warn_deprecated( __METHOD__, '::is_opera_mini() or \Automattic\Jetpack\Device_Detection\User_Agent_Info::is_opera_mobile()' );
-		return User_Agent_Info::is_OperaMobile();
-	}
-
 	/**
 	 * Detects if the current browser is a Windows Phone 7 device.
 	 * ex: Mozilla/4.0 (compatible; MSIE 7.0; Windows Phone OS 7.0; Trident/3.1; IEMobile/7.0; LG; GW910)

projects/plugins/jetpack/class.jetpack.php

@@ -3308,6 +3308,7 @@ public function throw_error_on_activate_plugin( $plugin ) {
 					$throw = true;
 				}
 			} else {
+				// @phan-suppress-next-line PhanUndeclaredFunctionInCallable -- Checked above. See also https://github.com/phan/phan/issues/1204.
 				$reflection = new ReflectionFunction( 'stats_get_api_key' );
 				if ( basename( $plugin ) === basename( $reflection->getFileName() ) ) {
 					$throw = true;

projects/plugins/jetpack/class.json-api-endpoints.php

@@ -77,6 +77,7 @@ abstract class WPCOM_JSON_API_Endpoint {
 	 * Maximum version of the api for which to serve this endpoint
 	 *
 	 * @var string
+	 * @phan-suppress PhanUndeclaredConstant -- https://github.com/phan/phan/issues/4855
 	 */
 	public $max_version = WPCOM_JSON_API__CURRENT_VERSION;
 
@@ -98,6 +99,7 @@ abstract class WPCOM_JSON_API_Endpoint {
 	 * Version of the endpoint this endpoint is deprecated in favor of.
 	 *
 	 * @var string
+	 * @phan-suppress PhanUndeclaredConstant -- https://github.com/phan/phan/issues/4855
 	 */
 	protected $new_version = WPCOM_JSON_API__CURRENT_VERSION;
 
@@ -2596,8 +2598,11 @@ public function get_amp_cache_origins( $siteurl ) {
 		 */
 		if ( function_exists( 'idn_to_utf8' ) ) {
 			// The third parameter is set explicitly to prevent issues with newer PHP versions compiled with an old ICU version.
-			// phpcs:ignore PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003Deprecated, PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved
-			$host = idn_to_utf8( $host, IDNA_DEFAULT, defined( 'INTL_IDNA_VARIANT_UTS46' ) ? INTL_IDNA_VARIANT_UTS46 : INTL_IDNA_VARIANT_2003 );
+			$variant = defined( 'INTL_IDNA_VARIANT_UTS46' )
+				? INTL_IDNA_VARIANT_UTS46
+				// phpcs:ignore PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003Deprecated, PHPCompatibility.Constants.RemovedConstants.intl_idna_variant_2003DeprecatedRemoved
+				: INTL_IDNA_VARIANT_2003; // @phan-suppress-current-line PhanUndeclaredConstant
+			$host = idn_to_utf8( $host, IDNA_DEFAULT, $variant );
 		}
 		$subdomain = str_replace( array( '-', '.' ), array( '--', '-' ), $host );
 		return array(

projects/plugins/jetpack/class.json-api.php

@@ -381,6 +381,17 @@ public function is_jetpack_authorized_for_site( $site_id = false ) {
 		return true;
 	}
 
+	/**
+	 * Checks if the current request is authorized with an upload token.
+	 * This method is overridden by a child class in WPCOM.
+	 *
+	 * @since $$next-version$$
+	 * @return boolean
+	 */
+	public function is_authorized_with_upload_token() {
+		return false;
+	}
+
 	/**
 	 * Serve.
 	 *
@@ -1016,6 +1027,18 @@ public function add_global_ID( $blog_id, $post_id ) { // phpcs:ignore VariableAn
 		return '';
 	}
 
+	/**
+	 * Return a count of comment likes.
+	 * This method is overridden by a child class in WPCOM.
+	 *
+	 * @since $$next-version$$
+	 * @return int
+	 */
+	public function comment_like_count() {
+		func_get_args(); // @phan-suppress-current-line PhanPluginUseReturnValueInternalKnown -- This is just here so Phan realizes the wpcom version does this.
+		return 0;
+	}
+
 	/**
 	 * Get avatar URL.
 	 *

projects/plugins/jetpack/extensions/blocks/like/like.php

@@ -145,6 +145,7 @@ function render_iframe() {
 
 	if ( ! $main_iframe_added ) {
 		if ( defined( 'IS_WPCOM' ) && IS_WPCOM ) {
+			// @phan-suppress-next-line PhanUndeclaredStaticMethod -- Can't do a stub for this one since Jetpack has its own class with the same name.
 			\Jetpack_Likes::likes_master();
 		} else {
 			require_once JETPACK__PLUGIN_DIR . 'modules/likes.php';

projects/plugins/jetpack/extensions/blocks/podcast-player/templates/playlist-track.php

@@ -14,6 +14,7 @@
  *
  * @var array $template_props
  */
+'@phan-var-force array $template_props';
 
 $track_title    = $template_props['attachment']['title'];
 $track_link     = empty( $template_props['attachment']['link'] ) ? $template_props['attachment']['src'] : $template_props['attachment']['link'];

projects/plugins/jetpack/json-endpoints/class.wpcom-json-api-get-site-endpoint.php

@@ -289,7 +289,7 @@ class WPCOM_JSON_API_GET_Site_Endpoint extends WPCOM_JSON_API_Endpoint {
 	/**
 	 * Site
 	 *
-	 * @var $site.
+	 * @var SAL_Site $site.
 	 */
 	private $site;
 
@@ -560,11 +560,7 @@ protected function render_response_key( $key, &$response, $is_user_logged_in ) {
 				$response[ $key ] = $this->site->get_products();
 				break;
 			case 'zendesk_site_meta':
-				// D59613-code only added this function to the wpcom SAL subclasses. Absent any better idea,
-				// we'll just omit the key entirely in Jetpack.
-				if ( is_callable( array( $this->site, 'get_zendesk_site_meta' ) ) ) {
-					$response[ $key ] = $this->site->get_zendesk_site_meta();
-				}
+				$response[ $key ] = $this->site->get_zendesk_site_meta();
 				break;
 			case 'quota':
 				$response[ $key ] = $this->site->get_quota();
@@ -819,11 +815,7 @@ protected function render_option_keys( &$options_response_keys ) {
 					$options[ $key ] = $site->get_import_engine();
 					break;
 				case 'is_pending_plan':
-					// D40032-code only added this function to the wpcom SAL subclasses. Absent any better idea,
-					// we'll just omit the key entirely in Jetpack.
-					if ( is_callable( array( $site, 'is_pending_plan' ) ) ) {
-						$options[ $key ] = $site->is_pending_plan();
-					}
+					$options[ $key ] = $site->is_pending_plan();
 					break;
 
 				case 'is_wpforteams_site':

projects/plugins/jetpack/json-endpoints/jetpack/class.jetpack-json-api-plugins-modify-endpoint.php

@@ -461,8 +461,8 @@ protected function update() {
 			// This avoids the plugin to be deactivated.
 			// Using bulk upgrade puts the site into maintenance mode during the upgrades
 			$result               = $upgrader->bulk_upgrade( array( $plugin ) );
-			$errors               = $upgrader->skin->get_errors();
-			$this->log[ $plugin ] = $upgrader->skin->get_upgrade_messages();
+			$errors               = $skin->get_errors();
+			$this->log[ $plugin ] = $skin->get_upgrade_messages();
 
 			// release individual plugin lock.
 			WP_Upgrader::release_lock( 'jetpack_' . $plugin_slug );

projects/plugins/jetpack/json-endpoints/jetpack/class.jetpack-json-api-plugins-new-endpoint.php

@@ -142,8 +142,8 @@ public function install() {
 			$plugin                    = array_values( array_diff( array_keys( $after_install_plugin_list ), array_keys( $pre_install_plugin_list ) ) );
 
 			if ( ! $result ) {
-				$error_code = $upgrader->skin->get_main_error_code();
-				$message    = $upgrader->skin->get_main_error_message();
+				$error_code = $skin->get_main_error_code();
+				$message    = $skin->get_main_error_message();
 				if ( empty( $message ) ) {
 					$message = __( 'An unknown error occurred during installation', 'jetpack' );
 				}

projects/plugins/jetpack/json-endpoints/jetpack/class.jetpack-json-api-themes-new-endpoint.php

@@ -96,8 +96,8 @@ public function install() {
 			$plugin             = array_values( array_diff( array_keys( $after_install_list ), array_keys( $pre_install_list ) ) );
 
 			if ( ! $result ) {
-				$error_code = $upgrader->skin->get_main_error_code();
-				$message    = $upgrader->skin->get_main_error_message();
+				$error_code = $skin->get_main_error_code();
+				$message    = $skin->get_main_error_message();
 				if ( empty( $message ) ) {
 					$message = __( 'An unknown error occurred during installation', 'jetpack' );
 				}

projects/plugins/jetpack/modules/infinite-scroll/infinity.php

@@ -214,6 +214,7 @@ public static function get_settings() {
 			// Otherwise, if a widget area ID or array of IDs was provided in the footer_widgets parameter, check if any contains any widgets.
 			// It is safe to use `is_active_sidebar()` before the sidebar is registered as this function doesn't check for a sidebar's existence when determining if it contains any widgets.
 			if ( function_exists( 'infinite_scroll_has_footer_widgets' ) ) {
+				// @phan-suppress-next-line PhanUndeclaredFunction -- Checked above. See also https://github.com/phan/phan/issues/1204.
 				$settings['footer_widgets'] = (bool) infinite_scroll_has_footer_widgets();
 			} elseif ( is_array( $settings['footer_widgets'] ) ) {
 				$sidebar_ids                = $settings['footer_widgets'];

projects/plugins/jetpack/modules/masterbar/inline-help/inline-help-template.php

@@ -5,7 +5,9 @@
  * @package automattic/jetpack
  */
 
-// phpcs:disable VariableAnalysis.CodeAnalysis.VariableAnalysis.UndefinedVariable
+// phpcs:disable VariableAnalysis.CodeAnalysis.VariableAnalysis.UndefinedVariable -- Defined by the caller. Let Phan handle it.
+'@phan-var-force array{href:string,icon:string,svg_allowed:array} $args';
+
 ?>
 
 <div class="a8c-faux-inline-help">

projects/plugins/jetpack/modules/memberships/class-jetpack-memberships.php

@@ -414,6 +414,7 @@ public function render_button( $attributes, $content = null, $block = null ) {
 				return $this->render_button_error( new WP_Error( 'jetpack-memberships-rb-npf', __( 'Could not find a plan for this button.', 'jetpack' ) . ' ' . __( 'Edit this post and confirm that the selected payment plan still exists and is available for purchase.', 'jetpack' ) ) );
 			}
 			if ( is_wp_error( $product ) ) {
+				'@phan-var WP_Error $product'; // `get_post` isn't supposed to return a WP_Error, so Phan is confused here. See also https://github.com/phan/phan/issues/3127
 				return $this->render_button_error( new WP_Error( 'jetpack-memberships-rb-npf-we', __( 'Encountered an error when getting the plan associated with this button:', 'jetpack' ) . ' ' . $product->get_error_message() . '. ' . __( ' Edit this post and confirm that the selected payment plan still exists and is available for purchase.', 'jetpack' ) ) );
 			}
 			if ( $product->post_type !== self::$post_type_plan ) {

projects/plugins/jetpack/modules/sharedaddy/sharing-service.php

@@ -511,12 +511,12 @@ public function get_global_options() {
 	/**
 	 * Save a sharing service for use.
 	 *
-	 * @param int            $id Sharing unique ID.
-	 * @param Sharing_Source $service Sharing service.
+	 * @param int                     $id Sharing unique ID.
+	 * @param Sharing_Advanced_Source $service Sharing service.
 	 *
 	 * @return void
 	 */
-	public function set_service( $id, Sharing_Source $service ) {
+	public function set_service( $id, Sharing_Advanced_Source $service ) {
 		// Update the options for this service
 		$options = get_option( 'sharing-options' );