General: Make Update PHP notice link customizable.

After [42832], [42891] and [43006], this changeset refines the core notice informing about an outdated PHP version:

* The link to the Update PHP information page can now be adjusted using either a `WP_UPDATE_PHP_URL` environment variable, or a new `wp_update_php_url` filter.
* If that URL is different from the default one that points to https://wordpress.org/support/update-php/ or its localized equivalent, a note indicates that the linked resource has not been provided by WordPress itself, and the default URL is still linked to as an additional resource.
* The URL for the default information page has been updated to use the slug `update-php` instead of `upgrade-php`.
* `@since` annotations have been updated.

Going forward, admin areas that display information related to the PHP version should use the new function `wp_get_update_php_url()`.

Props afragen, fierevere, flixos90, markjaquith, miss_jwo, nerrad, pento, schlessera, SergeyBiryukov, spacedmonkey.
Fixes #45686. See #41191.

Built from https://develop.svn.wordpress.org/trunk@44476


git-svn-id: http://core.svn.wordpress.org/trunk@44307 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/dashboard.php

@@ -1609,9 +1609,9 @@ function wp_check_browser_version() {
 }
 
 /**
- * Displays the PHP upgrade nag.
+ * Displays the PHP update nag.
  *
- * @since 5.0.0
+ * @since 5.1.0
  */
 function wp_dashboard_php_nag() {
 	$response = wp_check_php_version();
@@ -1626,6 +1626,9 @@ function wp_dashboard_php_nag() {
 		$msg = __( 'WordPress has detected that your site is running on an outdated version of PHP.' );
 	}
 
+	$update_url  = wp_get_update_php_url();
+	$default_url = wp_get_default_update_php_url();
+
 	?>
 	<p><?php echo $msg; ?></p>
 
@@ -1634,22 +1637,36 @@ function wp_dashboard_php_nag() {
 
 	<p class="button-container">
 		<?php
-			printf(
-				'<a class="button button-primary" href="%1$s" target="_blank" rel="noopener noreferrer">%2$s <span class="screen-reader-text">%3$s</span><span aria-hidden="true" class="dashicons dashicons-external"></span></a>',
-				esc_url( _x( 'https://wordpress.org/support/update-php/', 'localized PHP upgrade information page' ) ),
-				__( 'Learn more about updating PHP' ),
-				/* translators: accessibility text */
-				__( '(opens in a new tab)' )
-			);
+		printf(
+			'<a class="button button-primary" href="%1$s" target="_blank" rel="noopener noreferrer">%2$s <span class="screen-reader-text">%3$s</span><span aria-hidden="true" class="dashicons dashicons-external"></span></a>',
+			esc_url( $update_url ),
+			__( 'Learn more about updating PHP' ),
+			/* translators: accessibility text */
+			__( '(opens in a new tab)' )
+		);
 		?>
 	</p>
 	<?php
+
+	if ( $update_url !== $default_url ) {
+		?>
+		<p class="description">
+			<?php
+			printf(
+				/* translators: %s: default Update PHP page URL */
+				__( 'This resource is provided by your web host, and is specific to your site. For more information, <a href="%s" target="_blank">see the official WordPress documentation</a>.' ),
+				esc_url( $default_url )
+			);
+			?>
+		</p>
+		<?php
+	}
 }
 
 /**
  * Adds an additional class to the PHP nag if the current version is insecure.
  *
- * @since 5.0.0
+ * @since 5.1.0
  *
  * @param array $classes Metabox classes.
  * @return array Modified metabox classes.
@@ -1665,9 +1682,9 @@ function dashboard_php_nag_class( $classes ) {
 }
 
 /**
- * Checks if the user needs to upgrade PHP.
+ * Checks if the user needs to update PHP.
  *
- * @since 5.0.0
+ * @since 5.1.0
  *
  * @return array|false $response Array of PHP version data. False on failure.
  */

wp-includes/functions.php

@@ -6580,3 +6580,58 @@ function wp_privacy_delete_old_export_files() {
 		}
 	}
 }
+
+/**
+ * Gets the URL to learn more about updating the PHP version the site is running on.
+ *
+ * This URL can be overridden by specifying an environment variable `WP_UPDATE_PHP_URL` or by using the
+ * {@see 'wp_update_php_url'} filter. Providing an empty string is not allowed and will result in the
+ * default URL being used. Furthermore the page the URL links to should preferably be localized in the
+ * site language.
+ *
+ * @since 5.1.0
+ *
+ * @return string URL to learn more about updating PHP.
+ */
+function wp_get_update_php_url() {
+	$default_url = wp_get_default_update_php_url();
+
+	$update_url = $default_url;
+	if ( false !== getenv( 'WP_UPDATE_PHP_URL' ) ) {
+		$update_url = getenv( 'WP_UPDATE_PHP_URL' );
+	}
+
+	/**
+	 * Filters the URL to learn more about updating the PHP version the site is running on.
+	 *
+	 * Providing an empty string is not allowed and will result in the default URL being used. Furthermore
+	 * the page the URL links to should preferably be localized in the site language.
+	 *
+	 * @since 5.1.0
+	 *
+	 * @param string $update_url URL to learn more about updating PHP.
+	 */
+	$update_url = apply_filters( 'wp_update_php_url', $update_url );
+
+	if ( empty( $update_url ) ) {
+		$update_url = $default_url;
+	}
+
+	return $update_url;
+}
+
+/**
+ * Gets the default URL to learn more about updating the PHP version the site is running on.
+ *
+ * Do not use this function to retrieve this URL. Instead, use {@see wp_get_update_php_url()} when relying on the URL.
+ * This function does not allow modifying the returned URL, and is only used to compare the actually used URL with the
+ * default one.
+ *
+ * @since 5.1.0
+ * @access private
+ *
+ * @return string Default URL to learn more about updating PHP.
+ */
+function wp_get_default_update_php_url() {
+	return _x( 'https://wordpress.org/support/update-php/', 'localized PHP upgrade information page' );
+}

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.1-alpha-44475';
+$wp_version = '5.1-alpha-44476';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.