| [ Index ] |
PHP Cross Reference of WordPress |
[Summary view] [Print] [Text view]
1 <?php 2 /** 3 * WordPress Plugin Administration API 4 * 5 * @package WordPress 6 * @subpackage Administration 7 */ 8 9 /** 10 * Parses the plugin contents to retrieve plugin's metadata. 11 * 12 * All plugin headers must be on their own line. Plugin description must not have 13 * any newlines, otherwise only parts of the description will be displayed. 14 * The below is formatted for printing. 15 * 16 * /* 17 * Plugin Name: Name of the plugin. 18 * Plugin URI: The home page of the plugin. 19 * Description: Plugin description. 20 * Author: Plugin author's name. 21 * Author URI: Link to the author's website. 22 * Version: Plugin version. 23 * Text Domain: Optional. Unique identifier, should be same as the one used in 24 * load_plugin_textdomain(). 25 * Domain Path: Optional. Only useful if the translations are located in a 26 * folder above the plugin's base path. For example, if .mo files are 27 * located in the locale folder then Domain Path will be "/locale/" and 28 * must have the first slash. Defaults to the base folder the plugin is 29 * located in. 30 * Network: Optional. Specify "Network: true" to require that a plugin is activated 31 * across all sites in an installation. This will prevent a plugin from being 32 * activated on a single site when Multisite is enabled. 33 * Requires at least: Optional. Specify the minimum required WordPress version. 34 * Requires PHP: Optional. Specify the minimum required PHP version. 35 * * / # Remove the space to close comment. 36 * 37 * The first 8 KB of the file will be pulled in and if the plugin data is not 38 * within that first 8 KB, then the plugin author should correct their plugin 39 * and move the plugin data headers to the top. 40 * 41 * The plugin file is assumed to have permissions to allow for scripts to read 42 * the file. This is not checked however and the file is only opened for 43 * reading. 44 * 45 * @since 1.5.0 46 * @since 5.3.0 Added support for `Requires at least` and `Requires PHP` headers. 47 * 48 * @param string $plugin_file Absolute path to the main plugin file. 49 * @param bool $markup Optional. If the returned data should have HTML markup applied. 50 * Default true. 51 * @param bool $translate Optional. If the returned data should be translated. Default true. 52 * @return array { 53 * Plugin data. Values will be empty if not supplied by the plugin. 54 * 55 * @type string $Name Name of the plugin. Should be unique. 56 * @type string $Title Title of the plugin and link to the plugin's site (if set). 57 * @type string $Description Plugin description. 58 * @type string $Author Author's name. 59 * @type string $AuthorURI Author's website address (if set). 60 * @type string $Version Plugin version. 61 * @type string $TextDomain Plugin textdomain. 62 * @type string $DomainPath Plugins relative directory path to .mo files. 63 * @type bool $Network Whether the plugin can only be activated network-wide. 64 * @type string $RequiresWP Minimum required version of WordPress. 65 * @type string $RequiresPHP Minimum required version of PHP. 66 * } 67 */ 68 function get_plugin_data( $plugin_file, $markup = true, $translate = true ) { 69 70 $default_headers = array( 71 'Name' => 'Plugin Name', 72 'PluginURI' => 'Plugin URI', 73 'Version' => 'Version', 74 'Description' => 'Description', 75 'Author' => 'Author', 76 'AuthorURI' => 'Author URI', 77 'TextDomain' => 'Text Domain', 78 'DomainPath' => 'Domain Path', 79 'Network' => 'Network', 80 'RequiresWP' => 'Requires at least', 81 'RequiresPHP' => 'Requires PHP', 82 // Site Wide Only is deprecated in favor of Network. 83 '_sitewide' => 'Site Wide Only', 84 ); 85 86 $plugin_data = get_file_data( $plugin_file, $default_headers, 'plugin' ); 87 88 // Site Wide Only is the old header for Network. 89 if ( ! $plugin_data['Network'] && $plugin_data['_sitewide'] ) { 90 /* translators: 1: Site Wide Only: true, 2: Network: true */ 91 _deprecated_argument( __FUNCTION__, '3.0.0', sprintf( __( 'The %1$s plugin header is deprecated. Use %2$s instead.' ), '<code>Site Wide Only: true</code>', '<code>Network: true</code>' ) ); 92 $plugin_data['Network'] = $plugin_data['_sitewide']; 93 } 94 $plugin_data['Network'] = ( 'true' == strtolower( $plugin_data['Network'] ) ); 95 unset( $plugin_data['_sitewide'] ); 96 97 // If no text domain is defined fall back to the plugin slug. 98 if ( ! $plugin_data['TextDomain'] ) { 99 $plugin_slug = dirname( plugin_basename( $plugin_file ) ); 100 if ( '.' !== $plugin_slug && false === strpos( $plugin_slug, '/' ) ) { 101 $plugin_data['TextDomain'] = $plugin_slug; 102 } 103 } 104 105 if ( $markup || $translate ) { 106 $plugin_data = _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup, $translate ); 107 } else { 108 $plugin_data['Title'] = $plugin_data['Name']; 109 $plugin_data['AuthorName'] = $plugin_data['Author']; 110 } 111 112 return $plugin_data; 113 } 114 115 /** 116 * Sanitizes plugin data, optionally adds markup, optionally translates. 117 * 118 * @since 2.7.0 119 * 120 * @see get_plugin_data() 121 * 122 * @access private 123 * 124 * @param string $plugin_file Path to the main plugin file. 125 * @param array $plugin_data An array of plugin data. See `get_plugin_data()`. 126 * @param bool $markup Optional. If the returned data should have HTML markup applied. 127 * Default true. 128 * @param bool $translate Optional. If the returned data should be translated. Default true. 129 * @return array { 130 * Plugin data. Values will be empty if not supplied by the plugin. 131 * 132 * @type string $Name Name of the plugin. Should be unique. 133 * @type string $Title Title of the plugin and link to the plugin's site (if set). 134 * @type string $Description Plugin description. 135 * @type string $Author Author's name. 136 * @type string $AuthorURI Author's website address (if set). 137 * @type string $Version Plugin version. 138 * @type string $TextDomain Plugin textdomain. 139 * @type string $DomainPath Plugins relative directory path to .mo files. 140 * @type bool $Network Whether the plugin can only be activated network-wide. 141 * } 142 */ 143 function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup = true, $translate = true ) { 144 145 // Sanitize the plugin filename to a WP_PLUGIN_DIR relative path. 146 $plugin_file = plugin_basename( $plugin_file ); 147 148 // Translate fields. 149 if ( $translate ) { 150 $textdomain = $plugin_data['TextDomain']; 151 if ( $textdomain ) { 152 if ( ! is_textdomain_loaded( $textdomain ) ) { 153 if ( $plugin_data['DomainPath'] ) { 154 load_plugin_textdomain( $textdomain, false, dirname( $plugin_file ) . $plugin_data['DomainPath'] ); 155 } else { 156 load_plugin_textdomain( $textdomain, false, dirname( $plugin_file ) ); 157 } 158 } 159 } elseif ( 'hello.php' == basename( $plugin_file ) ) { 160 $textdomain = 'default'; 161 } 162 if ( $textdomain ) { 163 foreach ( array( 'Name', 'PluginURI', 'Description', 'Author', 'AuthorURI', 'Version' ) as $field ) { 164 // phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain 165 $plugin_data[ $field ] = translate( $plugin_data[ $field ], $textdomain ); 166 } 167 } 168 } 169 170 // Sanitize fields. 171 $allowed_tags_in_links = array( 172 'abbr' => array( 'title' => true ), 173 'acronym' => array( 'title' => true ), 174 'code' => true, 175 'em' => true, 176 'strong' => true, 177 ); 178 179 $allowed_tags = $allowed_tags_in_links; 180 $allowed_tags['a'] = array( 181 'href' => true, 182 'title' => true, 183 ); 184 185 // Name is marked up inside <a> tags. Don't allow these. 186 // Author is too, but some plugins have used <a> here (omitting Author URI). 187 $plugin_data['Name'] = wp_kses( $plugin_data['Name'], $allowed_tags_in_links ); 188 $plugin_data['Author'] = wp_kses( $plugin_data['Author'], $allowed_tags ); 189 190 $plugin_data['Description'] = wp_kses( $plugin_data['Description'], $allowed_tags ); 191 $plugin_data['Version'] = wp_kses( $plugin_data['Version'], $allowed_tags ); 192 193 $plugin_data['PluginURI'] = esc_url( $plugin_data['PluginURI'] ); 194 $plugin_data['AuthorURI'] = esc_url( $plugin_data['AuthorURI'] ); 195 196 $plugin_data['Title'] = $plugin_data['Name']; 197 $plugin_data['AuthorName'] = $plugin_data['Author']; 198 199 // Apply markup. 200 if ( $markup ) { 201 if ( $plugin_data['PluginURI'] && $plugin_data['Name'] ) { 202 $plugin_data['Title'] = '<a href="' . $plugin_data['PluginURI'] . '">' . $plugin_data['Name'] . '</a>'; 203 } 204 205 if ( $plugin_data['AuthorURI'] && $plugin_data['Author'] ) { 206 $plugin_data['Author'] = '<a href="' . $plugin_data['AuthorURI'] . '">' . $plugin_data['Author'] . '</a>'; 207 } 208 209 $plugin_data['Description'] = wptexturize( $plugin_data['Description'] ); 210 211 if ( $plugin_data['Author'] ) { 212 $plugin_data['Description'] .= sprintf( 213 /* translators: %s: Plugin author. */ 214 ' <cite>' . __( 'By %s.' ) . '</cite>', 215 $plugin_data['Author'] 216 ); 217 } 218 } 219 220 return $plugin_data; 221 } 222 223 /** 224 * Get a list of a plugin's files. 225 * 226 * @since 2.8.0 227 * 228 * @param string $plugin Path to the plugin file relative to the plugins directory. 229 * @return string[] Array of file names relative to the plugin root. 230 */ 231 function get_plugin_files( $plugin ) { 232 $plugin_file = WP_PLUGIN_DIR . '/' . $plugin; 233 $dir = dirname( $plugin_file ); 234 235 $plugin_files = array( plugin_basename( $plugin_file ) ); 236 237 if ( is_dir( $dir ) && WP_PLUGIN_DIR !== $dir ) { 238 239 /** 240 * Filters the array of excluded directories and files while scanning the folder. 241 * 242 * @since 4.9.0 243 * 244 * @param string[] $exclusions Array of excluded directories and files. 245 */ 246 $exclusions = (array) apply_filters( 'plugin_files_exclusions', array( 'CVS', 'node_modules', 'vendor', 'bower_components' ) ); 247 248 $list_files = list_files( $dir, 100, $exclusions ); 249 $list_files = array_map( 'plugin_basename', $list_files ); 250 251 $plugin_files = array_merge( $plugin_files, $list_files ); 252 $plugin_files = array_values( array_unique( $plugin_files ) ); 253 } 254 255 return $plugin_files; 256 } 257 258 /** 259 * Check the plugins directory and retrieve all plugin files with plugin data. 260 * 261 * WordPress only supports plugin files in the base plugins directory 262 * (wp-content/plugins) and in one directory above the plugins directory 263 * (wp-content/plugins/my-plugin). The file it looks for has the plugin data 264 * and must be found in those two locations. It is recommended to keep your 265 * plugin files in their own directories. 266 * 267 * The file with the plugin data is the file that will be included and therefore 268 * needs to have the main execution for the plugin. This does not mean 269 * everything must be contained in the file and it is recommended that the file 270 * be split for maintainability. Keep everything in one file for extreme 271 * optimization purposes. 272 * 273 * @since 1.5.0 274 * 275 * @param string $plugin_folder Optional. Relative path to single plugin folder. 276 * @return array[] Array of arrays of plugin data, keyed by plugin file name. See `get_plugin_data()`. 277 */ 278 function get_plugins( $plugin_folder = '' ) { 279 280 $cache_plugins = wp_cache_get( 'plugins', 'plugins' ); 281 if ( ! $cache_plugins ) { 282 $cache_plugins = array(); 283 } 284 285 if ( isset( $cache_plugins[ $plugin_folder ] ) ) { 286 return $cache_plugins[ $plugin_folder ]; 287 } 288 289 $wp_plugins = array(); 290 $plugin_root = WP_PLUGIN_DIR; 291 if ( ! empty( $plugin_folder ) ) { 292 $plugin_root .= $plugin_folder; 293 } 294 295 // Files in wp-content/plugins directory. 296 $plugins_dir = @ opendir( $plugin_root ); 297 $plugin_files = array(); 298 if ( $plugins_dir ) { 299 while ( ( $file = readdir( $plugins_dir ) ) !== false ) { 300 if ( substr( $file, 0, 1 ) == '.' ) { 301 continue; 302 } 303 if ( is_dir( $plugin_root . '/' . $file ) ) { 304 $plugins_subdir = @ opendir( $plugin_root . '/' . $file ); 305 if ( $plugins_subdir ) { 306 while ( ( $subfile = readdir( $plugins_subdir ) ) !== false ) { 307 if ( substr( $subfile, 0, 1 ) == '.' ) { 308 continue; 309 } 310 if ( substr( $subfile, -4 ) == '.php' ) { 311 $plugin_files[] = "$file/$subfile"; 312 } 313 } 314 closedir( $plugins_subdir ); 315 } 316 } else { 317 if ( substr( $file, -4 ) == '.php' ) { 318 $plugin_files[] = $file; 319 } 320 } 321 } 322 closedir( $plugins_dir ); 323 } 324 325 if ( empty( $plugin_files ) ) { 326 return $wp_plugins; 327 } 328 329 foreach ( $plugin_files as $plugin_file ) { 330 if ( ! is_readable( "$plugin_root/$plugin_file" ) ) { 331 continue; 332 } 333 334 $plugin_data = get_plugin_data( "$plugin_root/$plugin_file", false, false ); //Do not apply markup/translate as it'll be cached. 335 336 if ( empty( $plugin_data['Name'] ) ) { 337 continue; 338 } 339 340 $wp_plugins[ plugin_basename( $plugin_file ) ] = $plugin_data; 341 } 342 343 uasort( $wp_plugins, '_sort_uname_callback' ); 344 345 $cache_plugins[ $plugin_folder ] = $wp_plugins; 346 wp_cache_set( 'plugins', $cache_plugins, 'plugins' ); 347 348 return $wp_plugins; 349 } 350 351 /** 352 * Check the mu-plugins directory and retrieve all mu-plugin files with any plugin data. 353 * 354 * WordPress only includes mu-plugin files in the base mu-plugins directory (wp-content/mu-plugins). 355 * 356 * @since 3.0.0 357 * @return array[] Array of arrays of mu-plugin data, keyed by plugin file name. See `get_plugin_data()`. 358 */ 359 function get_mu_plugins() { 360 $wp_plugins = array(); 361 // Files in wp-content/mu-plugins directory. 362 $plugin_files = array(); 363 364 if ( ! is_dir( WPMU_PLUGIN_DIR ) ) { 365 return $wp_plugins; 366 } 367 $plugins_dir = @opendir( WPMU_PLUGIN_DIR ); 368 if ( $plugins_dir ) { 369 while ( ( $file = readdir( $plugins_dir ) ) !== false ) { 370 if ( substr( $file, -4 ) == '.php' ) { 371 $plugin_files[] = $file; 372 } 373 } 374 } else { 375 return $wp_plugins; 376 } 377 378 closedir( $plugins_dir ); 379 380 if ( empty( $plugin_files ) ) { 381 return $wp_plugins; 382 } 383 384 foreach ( $plugin_files as $plugin_file ) { 385 if ( ! is_readable( WPMU_PLUGIN_DIR . "/$plugin_file" ) ) { 386 continue; 387 } 388 389 $plugin_data = get_plugin_data( WPMU_PLUGIN_DIR . "/$plugin_file", false, false ); //Do not apply markup/translate as it'll be cached. 390 391 if ( empty( $plugin_data['Name'] ) ) { 392 $plugin_data['Name'] = $plugin_file; 393 } 394 395 $wp_plugins[ $plugin_file ] = $plugin_data; 396 } 397 398 if ( isset( $wp_plugins['index.php'] ) && filesize( WPMU_PLUGIN_DIR . '/index.php' ) <= 30 ) { // silence is golden 399 unset( $wp_plugins['index.php'] ); 400 } 401 402 uasort( $wp_plugins, '_sort_uname_callback' ); 403 404 return $wp_plugins; 405 } 406 407 /** 408 * Callback to sort array by a 'Name' key. 409 * 410 * @since 3.1.0 411 * 412 * @access private 413 * 414 * @param array $a array with 'Name' key. 415 * @param array $b array with 'Name' key. 416 * @return int Return 0 or 1 based on two string comparison. 417 */ 418 function _sort_uname_callback( $a, $b ) { 419 return strnatcasecmp( $a['Name'], $b['Name'] ); 420 } 421 422 /** 423 * Check the wp-content directory and retrieve all drop-ins with any plugin data. 424 * 425 * @since 3.0.0 426 * @return array[] Array of arrays of dropin plugin data, keyed by plugin file name. See `get_plugin_data()`. 427 */ 428 function get_dropins() { 429 $dropins = array(); 430 $plugin_files = array(); 431 432 $_dropins = _get_dropins(); 433 434 // These exist in the wp-content directory. 435 $plugins_dir = @opendir( WP_CONTENT_DIR ); 436 if ( $plugins_dir ) { 437 while ( ( $file = readdir( $plugins_dir ) ) !== false ) { 438 if ( isset( $_dropins[ $file ] ) ) { 439 $plugin_files[] = $file; 440 } 441 } 442 } else { 443 return $dropins; 444 } 445 446 closedir( $plugins_dir ); 447 448 if ( empty( $plugin_files ) ) { 449 return $dropins; 450 } 451 452 foreach ( $plugin_files as $plugin_file ) { 453 if ( ! is_readable( WP_CONTENT_DIR . "/$plugin_file" ) ) { 454 continue; 455 } 456 $plugin_data = get_plugin_data( WP_CONTENT_DIR . "/$plugin_file", false, false ); //Do not apply markup/translate as it'll be cached. 457 if ( empty( $plugin_data['Name'] ) ) { 458 $plugin_data['Name'] = $plugin_file; 459 } 460 $dropins[ $plugin_file ] = $plugin_data; 461 } 462 463 uksort( $dropins, 'strnatcasecmp' ); 464 465 return $dropins; 466 } 467 468 /** 469 * Returns drop-ins that WordPress uses. 470 * 471 * Includes Multisite drop-ins only when is_multisite() 472 * 473 * @since 3.0.0 474 * @return array[] Key is file name. The value is an array, with the first value the 475 * purpose of the drop-in and the second value the name of the constant that must be 476 * true for the drop-in to be used, or true if no constant is required. 477 */ 478 function _get_dropins() { 479 $dropins = array( 480 'advanced-cache.php' => array( __( 'Advanced caching plugin.' ), 'WP_CACHE' ), // WP_CACHE 481 'db.php' => array( __( 'Custom database class.' ), true ), // auto on load 482 'db-error.php' => array( __( 'Custom database error message.' ), true ), // auto on error 483 'install.php' => array( __( 'Custom installation script.' ), true ), // auto on installation 484 'maintenance.php' => array( __( 'Custom maintenance message.' ), true ), // auto on maintenance 485 'object-cache.php' => array( __( 'External object cache.' ), true ), // auto on load 486 'php-error.php' => array( __( 'Custom PHP error message.' ), true ), // auto on error 487 'fatal-error-handler.php' => array( __( 'Custom PHP fatal error handler.' ), true ), // auto on error 488 ); 489 490 if ( is_multisite() ) { 491 $dropins['sunrise.php'] = array( __( 'Executed before Multisite is loaded.' ), 'SUNRISE' ); // SUNRISE 492 $dropins['blog-deleted.php'] = array( __( 'Custom site deleted message.' ), true ); // auto on deleted blog 493 $dropins['blog-inactive.php'] = array( __( 'Custom site inactive message.' ), true ); // auto on inactive blog 494 $dropins['blog-suspended.php'] = array( __( 'Custom site suspended message.' ), true ); // auto on archived or spammed blog 495 } 496 497 return $dropins; 498 } 499 500 /** 501 * Determines whether a plugin is active. 502 * 503 * Only plugins installed in the plugins/ folder can be active. 504 * 505 * Plugins in the mu-plugins/ folder can't be "activated," so this function will 506 * return false for those plugins. 507 * 508 * For more information on this and similar theme functions, check out 509 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 510 * Conditional Tags} article in the Theme Developer Handbook. 511 * 512 * @since 2.5.0 513 * 514 * @param string $plugin Path to the plugin file relative to the plugins directory. 515 * @return bool True, if in the active plugins list. False, not in the list. 516 */ 517 function is_plugin_active( $plugin ) { 518 return in_array( $plugin, (array) get_option( 'active_plugins', array() ) ) || is_plugin_active_for_network( $plugin ); 519 } 520 521 /** 522 * Determines whether the plugin is inactive. 523 * 524 * Reverse of is_plugin_active(). Used as a callback. 525 * 526 * For more information on this and similar theme functions, check out 527 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 528 * Conditional Tags} article in the Theme Developer Handbook. 529 * 530 * @since 3.1.0 531 * @see is_plugin_active() 532 * 533 * @param string $plugin Path to the plugin file relative to the plugins directory. 534 * @return bool True if inactive. False if active. 535 */ 536 function is_plugin_inactive( $plugin ) { 537 return ! is_plugin_active( $plugin ); 538 } 539 540 /** 541 * Determines whether the plugin is active for the entire network. 542 * 543 * Only plugins installed in the plugins/ folder can be active. 544 * 545 * Plugins in the mu-plugins/ folder can't be "activated," so this function will 546 * return false for those plugins. 547 * 548 * For more information on this and similar theme functions, check out 549 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 550 * Conditional Tags} article in the Theme Developer Handbook. 551 * 552 * @since 3.0.0 553 * 554 * @param string $plugin Path to the plugin file relative to the plugins directory. 555 * @return bool True if active for the network, otherwise false. 556 */ 557 function is_plugin_active_for_network( $plugin ) { 558 if ( ! is_multisite() ) { 559 return false; 560 } 561 562 $plugins = get_site_option( 'active_sitewide_plugins' ); 563 if ( isset( $plugins[ $plugin ] ) ) { 564 return true; 565 } 566 567 return false; 568 } 569 570 /** 571 * Checks for "Network: true" in the plugin header to see if this should 572 * be activated only as a network wide plugin. The plugin would also work 573 * when Multisite is not enabled. 574 * 575 * Checks for "Site Wide Only: true" for backward compatibility. 576 * 577 * @since 3.0.0 578 * 579 * @param string $plugin Path to the plugin file relative to the plugins directory. 580 * @return bool True if plugin is network only, false otherwise. 581 */ 582 function is_network_only_plugin( $plugin ) { 583 $plugin_data = get_plugin_data( WP_PLUGIN_DIR . '/' . $plugin ); 584 if ( $plugin_data ) { 585 return $plugin_data['Network']; 586 } 587 return false; 588 } 589 590 /** 591 * Attempts activation of plugin in a "sandbox" and redirects on success. 592 * 593 * A plugin that is already activated will not attempt to be activated again. 594 * 595 * The way it works is by setting the redirection to the error before trying to 596 * include the plugin file. If the plugin fails, then the redirection will not 597 * be overwritten with the success message. Also, the options will not be 598 * updated and the activation hook will not be called on plugin error. 599 * 600 * It should be noted that in no way the below code will actually prevent errors 601 * within the file. The code should not be used elsewhere to replicate the 602 * "sandbox", which uses redirection to work. 603 * {@source 13 1} 604 * 605 * If any errors are found or text is outputted, then it will be captured to 606 * ensure that the success redirection will update the error redirection. 607 * 608 * @since 2.5.0 609 * @since 5.2.0 Test for WordPress version and PHP version compatibility. 610 * 611 * @param string $plugin Path to the plugin file relative to the plugins directory. 612 * @param string $redirect Optional. URL to redirect to. 613 * @param bool $network_wide Optional. Whether to enable the plugin for all sites in the network 614 * or just the current site. Multisite only. Default false. 615 * @param bool $silent Optional. Whether to prevent calling activation hooks. Default false. 616 * @return null|WP_Error Null on success, WP_Error on invalid file. 617 */ 618 function activate_plugin( $plugin, $redirect = '', $network_wide = false, $silent = false ) { 619 $plugin = plugin_basename( trim( $plugin ) ); 620 621 if ( is_multisite() && ( $network_wide || is_network_only_plugin( $plugin ) ) ) { 622 $network_wide = true; 623 $current = get_site_option( 'active_sitewide_plugins', array() ); 624 $_GET['networkwide'] = 1; // Back compat for plugins looking for this value. 625 } else { 626 $current = get_option( 'active_plugins', array() ); 627 } 628 629 $valid = validate_plugin( $plugin ); 630 if ( is_wp_error( $valid ) ) { 631 return $valid; 632 } 633 634 $requirements = validate_plugin_requirements( $plugin ); 635 if ( is_wp_error( $requirements ) ) { 636 return $requirements; 637 } 638 639 if ( ( $network_wide && ! isset( $current[ $plugin ] ) ) || ( ! $network_wide && ! in_array( $plugin, $current ) ) ) { 640 if ( ! empty( $redirect ) ) { 641 wp_redirect( add_query_arg( '_error_nonce', wp_create_nonce( 'plugin-activation-error_' . $plugin ), $redirect ) ); // we'll override this later if the plugin can be included without fatal error 642 } 643 644 ob_start(); 645 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin ); 646 $_wp_plugin_file = $plugin; 647 if ( ! defined( 'WP_SANDBOX_SCRAPING' ) ) { 648 define( 'WP_SANDBOX_SCRAPING', true ); 649 } 650 include_once( WP_PLUGIN_DIR . '/' . $plugin ); 651 $plugin = $_wp_plugin_file; // Avoid stomping of the $plugin variable in a plugin. 652 653 if ( ! $silent ) { 654 /** 655 * Fires before a plugin is activated. 656 * 657 * If a plugin is silently activated (such as during an update), 658 * this hook does not fire. 659 * 660 * @since 2.9.0 661 * 662 * @param string $plugin Path to the plugin file relative to the plugins directory. 663 * @param bool $network_wide Whether to enable the plugin for all sites in the network 664 * or just the current site. Multisite only. Default is false. 665 */ 666 do_action( 'activate_plugin', $plugin, $network_wide ); 667 668 /** 669 * Fires as a specific plugin is being activated. 670 * 671 * This hook is the "activation" hook used internally by register_activation_hook(). 672 * The dynamic portion of the hook name, `$plugin`, refers to the plugin basename. 673 * 674 * If a plugin is silently activated (such as during an update), this hook does not fire. 675 * 676 * @since 2.0.0 677 * 678 * @param bool $network_wide Whether to enable the plugin for all sites in the network 679 * or just the current site. Multisite only. Default is false. 680 */ 681 do_action( "activate_{$plugin}", $network_wide ); 682 } 683 684 if ( $network_wide ) { 685 $current = get_site_option( 'active_sitewide_plugins', array() ); 686 $current[ $plugin ] = time(); 687 update_site_option( 'active_sitewide_plugins', $current ); 688 } else { 689 $current = get_option( 'active_plugins', array() ); 690 $current[] = $plugin; 691 sort( $current ); 692 update_option( 'active_plugins', $current ); 693 } 694 695 if ( ! $silent ) { 696 /** 697 * Fires after a plugin has been activated. 698 * 699 * If a plugin is silently activated (such as during an update), 700 * this hook does not fire. 701 * 702 * @since 2.9.0 703 * 704 * @param string $plugin Path to the plugin file relative to the plugins directory. 705 * @param bool $network_wide Whether to enable the plugin for all sites in the network 706 * or just the current site. Multisite only. Default is false. 707 */ 708 do_action( 'activated_plugin', $plugin, $network_wide ); 709 } 710 711 if ( ob_get_length() > 0 ) { 712 $output = ob_get_clean(); 713 return new WP_Error( 'unexpected_output', __( 'The plugin generated unexpected output.' ), $output ); 714 } 715 ob_end_clean(); 716 } 717 718 return null; 719 } 720 721 /** 722 * Deactivate a single plugin or multiple plugins. 723 * 724 * The deactivation hook is disabled by the plugin upgrader by using the $silent 725 * parameter. 726 * 727 * @since 2.5.0 728 * 729 * @param string|string[] $plugins Single plugin or list of plugins to deactivate. 730 * @param bool $silent Prevent calling deactivation hooks. Default false. 731 * @param bool|null $network_wide Whether to deactivate the plugin for all sites in the network. 732 * A value of null will deactivate plugins for both the network 733 * and the current site. Multisite only. Default null. 734 */ 735 function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) { 736 if ( is_multisite() ) { 737 $network_current = get_site_option( 'active_sitewide_plugins', array() ); 738 } 739 $current = get_option( 'active_plugins', array() ); 740 $do_blog = false; 741 $do_network = false; 742 743 foreach ( (array) $plugins as $plugin ) { 744 $plugin = plugin_basename( trim( $plugin ) ); 745 if ( ! is_plugin_active( $plugin ) ) { 746 continue; 747 } 748 749 $network_deactivating = false !== $network_wide && is_plugin_active_for_network( $plugin ); 750 751 if ( ! $silent ) { 752 /** 753 * Fires before a plugin is deactivated. 754 * 755 * If a plugin is silently deactivated (such as during an update), 756 * this hook does not fire. 757 * 758 * @since 2.9.0 759 * 760 * @param string $plugin Path to the plugin file relative to the plugins directory. 761 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network 762 * or just the current site. Multisite only. Default false. 763 */ 764 do_action( 'deactivate_plugin', $plugin, $network_deactivating ); 765 } 766 767 if ( false !== $network_wide ) { 768 if ( is_plugin_active_for_network( $plugin ) ) { 769 $do_network = true; 770 unset( $network_current[ $plugin ] ); 771 } elseif ( $network_wide ) { 772 continue; 773 } 774 } 775 776 if ( true !== $network_wide ) { 777 $key = array_search( $plugin, $current ); 778 if ( false !== $key ) { 779 $do_blog = true; 780 unset( $current[ $key ] ); 781 } 782 } 783 784 if ( $do_blog && wp_is_recovery_mode() ) { 785 list( $extension ) = explode( '/', $plugin ); 786 wp_paused_plugins()->delete( $extension ); 787 } 788 789 if ( ! $silent ) { 790 /** 791 * Fires as a specific plugin is being deactivated. 792 * 793 * This hook is the "deactivation" hook used internally by register_deactivation_hook(). 794 * The dynamic portion of the hook name, `$plugin`, refers to the plugin basename. 795 * 796 * If a plugin is silently deactivated (such as during an update), this hook does not fire. 797 * 798 * @since 2.0.0 799 * 800 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network 801 * or just the current site. Multisite only. Default false. 802 */ 803 do_action( "deactivate_{$plugin}", $network_deactivating ); 804 805 /** 806 * Fires after a plugin is deactivated. 807 * 808 * If a plugin is silently deactivated (such as during an update), 809 * this hook does not fire. 810 * 811 * @since 2.9.0 812 * 813 * @param string $plugin Path to the plugin file relative to the plugins directory. 814 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network 815 * or just the current site. Multisite only. Default false. 816 */ 817 do_action( 'deactivated_plugin', $plugin, $network_deactivating ); 818 } 819 } 820 821 if ( $do_blog ) { 822 update_option( 'active_plugins', $current ); 823 } 824 if ( $do_network ) { 825 update_site_option( 'active_sitewide_plugins', $network_current ); 826 } 827 } 828 829 /** 830 * Activate multiple plugins. 831 * 832 * When WP_Error is returned, it does not mean that one of the plugins had 833 * errors. It means that one or more of the plugin file paths were invalid. 834 * 835 * The execution will be halted as soon as one of the plugins has an error. 836 * 837 * @since 2.6.0 838 * 839 * @param string|string[] $plugins Single plugin or list of plugins to activate. 840 * @param string $redirect Redirect to page after successful activation. 841 * @param bool $network_wide Whether to enable the plugin for all sites in the network. 842 * Default false. 843 * @param bool $silent Prevent calling activation hooks. Default false. 844 * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation. 845 */ 846 function activate_plugins( $plugins, $redirect = '', $network_wide = false, $silent = false ) { 847 if ( ! is_array( $plugins ) ) { 848 $plugins = array( $plugins ); 849 } 850 851 $errors = array(); 852 foreach ( $plugins as $plugin ) { 853 if ( ! empty( $redirect ) ) { 854 $redirect = add_query_arg( 'plugin', $plugin, $redirect ); 855 } 856 $result = activate_plugin( $plugin, $redirect, $network_wide, $silent ); 857 if ( is_wp_error( $result ) ) { 858 $errors[ $plugin ] = $result; 859 } 860 } 861 862 if ( ! empty( $errors ) ) { 863 return new WP_Error( 'plugins_invalid', __( 'One of the plugins is invalid.' ), $errors ); 864 } 865 866 return true; 867 } 868 869 /** 870 * Remove directory and files of a plugin for a list of plugins. 871 * 872 * @since 2.6.0 873 * 874 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. 875 * 876 * @param string[] $plugins List of plugin paths to delete, relative to the plugins directory. 877 * @param string $deprecated Not used. 878 * @return bool|null|WP_Error True on success, false if `$plugins` is empty, `WP_Error` on failure. 879 * `null` if filesystem credentials are required to proceed. 880 */ 881 function delete_plugins( $plugins, $deprecated = '' ) { 882 global $wp_filesystem; 883 884 if ( empty( $plugins ) ) { 885 return false; 886 } 887 888 $checked = array(); 889 foreach ( $plugins as $plugin ) { 890 $checked[] = 'checked[]=' . $plugin; 891 } 892 893 $url = wp_nonce_url( 'plugins.php?action=delete-selected&verify-delete=1&' . implode( '&', $checked ), 'bulk-plugins' ); 894 895 ob_start(); 896 $credentials = request_filesystem_credentials( $url ); 897 $data = ob_get_clean(); 898 899 if ( false === $credentials ) { 900 if ( ! empty( $data ) ) { 901 include_once( ABSPATH . 'wp-admin/admin-header.php' ); 902 echo $data; 903 include( ABSPATH . 'wp-admin/admin-footer.php' ); 904 exit; 905 } 906 return; 907 } 908 909 if ( ! WP_Filesystem( $credentials ) ) { 910 ob_start(); 911 request_filesystem_credentials( $url, '', true ); // Failed to connect, Error and request again. 912 $data = ob_get_clean(); 913 914 if ( ! empty( $data ) ) { 915 include_once( ABSPATH . 'wp-admin/admin-header.php' ); 916 echo $data; 917 include( ABSPATH . 'wp-admin/admin-footer.php' ); 918 exit; 919 } 920 return; 921 } 922 923 if ( ! is_object( $wp_filesystem ) ) { 924 return new WP_Error( 'fs_unavailable', __( 'Could not access filesystem.' ) ); 925 } 926 927 if ( is_wp_error( $wp_filesystem->errors ) && $wp_filesystem->errors->has_errors() ) { 928 return new WP_Error( 'fs_error', __( 'Filesystem error.' ), $wp_filesystem->errors ); 929 } 930 931 // Get the base plugin folder. 932 $plugins_dir = $wp_filesystem->wp_plugins_dir(); 933 if ( empty( $plugins_dir ) ) { 934 return new WP_Error( 'fs_no_plugins_dir', __( 'Unable to locate WordPress plugin directory.' ) ); 935 } 936 937 $plugins_dir = trailingslashit( $plugins_dir ); 938 939 $plugin_translations = wp_get_installed_translations( 'plugins' ); 940 941 $errors = array(); 942 943 foreach ( $plugins as $plugin_file ) { 944 // Run Uninstall hook. 945 if ( is_uninstallable_plugin( $plugin_file ) ) { 946 uninstall_plugin( $plugin_file ); 947 } 948 949 /** 950 * Fires immediately before a plugin deletion attempt. 951 * 952 * @since 4.4.0 953 * 954 * @param string $plugin_file Path to the plugin file relative to the plugins directory. 955 */ 956 do_action( 'delete_plugin', $plugin_file ); 957 958 $this_plugin_dir = trailingslashit( dirname( $plugins_dir . $plugin_file ) ); 959 960 // If plugin is in its own directory, recursively delete the directory. 961 if ( strpos( $plugin_file, '/' ) && $this_plugin_dir != $plugins_dir ) { //base check on if plugin includes directory separator AND that it's not the root plugin folder 962 $deleted = $wp_filesystem->delete( $this_plugin_dir, true ); 963 } else { 964 $deleted = $wp_filesystem->delete( $plugins_dir . $plugin_file ); 965 } 966 967 /** 968 * Fires immediately after a plugin deletion attempt. 969 * 970 * @since 4.4.0 971 * 972 * @param string $plugin_file Path to the plugin file relative to the plugins directory. 973 * @param bool $deleted Whether the plugin deletion was successful. 974 */ 975 do_action( 'deleted_plugin', $plugin_file, $deleted ); 976 977 if ( ! $deleted ) { 978 $errors[] = $plugin_file; 979 continue; 980 } 981 982 // Remove language files, silently. 983 $plugin_slug = dirname( $plugin_file ); 984 if ( '.' !== $plugin_slug && ! empty( $plugin_translations[ $plugin_slug ] ) ) { 985 $translations = $plugin_translations[ $plugin_slug ]; 986 987 foreach ( $translations as $translation => $data ) { 988 $wp_filesystem->delete( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '.po' ); 989 $wp_filesystem->delete( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '.mo' ); 990 991 $json_translation_files = glob( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '-*.json' ); 992 if ( $json_translation_files ) { 993 array_map( array( $wp_filesystem, 'delete' ), $json_translation_files ); 994 } 995 } 996 } 997 } 998 999 // Remove deleted plugins from the plugin updates list. 1000 $current = get_site_transient( 'update_plugins' ); 1001 if ( $current ) { 1002 // Don't remove the plugins that weren't deleted. 1003 $deleted = array_diff( $plugins, $errors ); 1004 1005 foreach ( $deleted as $plugin_file ) { 1006 unset( $current->response[ $plugin_file ] ); 1007 } 1008 1009 set_site_transient( 'update_plugins', $current ); 1010 } 1011 1012 if ( ! empty( $errors ) ) { 1013 if ( 1 === count( $errors ) ) { 1014 /* translators: %s: Plugin filename. */ 1015 $message = __( 'Could not fully remove the plugin %s.' ); 1016 } else { 1017 /* translators: %s: Comma-separated list of plugin filenames. */ 1018 $message = __( 'Could not fully remove the plugins %s.' ); 1019 } 1020 1021 return new WP_Error( 'could_not_remove_plugin', sprintf( $message, implode( ', ', $errors ) ) ); 1022 } 1023 1024 return true; 1025 } 1026 1027 /** 1028 * Validate active plugins 1029 * 1030 * Validate all active plugins, deactivates invalid and 1031 * returns an array of deactivated ones. 1032 * 1033 * @since 2.5.0 1034 * @return WP_Error[] Array of plugin errors keyed by plugin file name. 1035 */ 1036 function validate_active_plugins() { 1037 $plugins = get_option( 'active_plugins', array() ); 1038 // Validate vartype: array. 1039 if ( ! is_array( $plugins ) ) { 1040 update_option( 'active_plugins', array() ); 1041 $plugins = array(); 1042 } 1043 1044 if ( is_multisite() && current_user_can( 'manage_network_plugins' ) ) { 1045 $network_plugins = (array) get_site_option( 'active_sitewide_plugins', array() ); 1046 $plugins = array_merge( $plugins, array_keys( $network_plugins ) ); 1047 } 1048 1049 if ( empty( $plugins ) ) { 1050 return array(); 1051 } 1052 1053 $invalid = array(); 1054 1055 // Invalid plugins get deactivated. 1056 foreach ( $plugins as $plugin ) { 1057 $result = validate_plugin( $plugin ); 1058 if ( is_wp_error( $result ) ) { 1059 $invalid[ $plugin ] = $result; 1060 deactivate_plugins( $plugin, true ); 1061 } 1062 } 1063 return $invalid; 1064 } 1065 1066 /** 1067 * Validate the plugin path. 1068 * 1069 * Checks that the main plugin file exists and is a valid plugin. See validate_file(). 1070 * 1071 * @since 2.5.0 1072 * 1073 * @param string $plugin Path to the plugin file relative to the plugins directory. 1074 * @return int|WP_Error 0 on success, WP_Error on failure. 1075 */ 1076 function validate_plugin( $plugin ) { 1077 if ( validate_file( $plugin ) ) { 1078 return new WP_Error( 'plugin_invalid', __( 'Invalid plugin path.' ) ); 1079 } 1080 if ( ! file_exists( WP_PLUGIN_DIR . '/' . $plugin ) ) { 1081 return new WP_Error( 'plugin_not_found', __( 'Plugin file does not exist.' ) ); 1082 } 1083 1084 $installed_plugins = get_plugins(); 1085 if ( ! isset( $installed_plugins[ $plugin ] ) ) { 1086 return new WP_Error( 'no_plugin_header', __( 'The plugin does not have a valid header.' ) ); 1087 } 1088 return 0; 1089 } 1090 1091 /** 1092 * Validate the plugin requirements for WP version and PHP version. 1093 * 1094 * @since 5.2.0 1095 * 1096 * @param string $plugin Path to the plugin file relative to the plugins directory. 1097 * @return true|WP_Error True if requirements are met, WP_Error on failure. 1098 */ 1099 function validate_plugin_requirements( $plugin ) { 1100 $readme_file = WP_PLUGIN_DIR . '/' . dirname( $plugin ) . '/readme.txt'; 1101 $plugin_data = array( 1102 'requires' => '', 1103 'requires_php' => '', 1104 ); 1105 1106 if ( file_exists( $readme_file ) ) { 1107 $plugin_data = get_file_data( 1108 $readme_file, 1109 array( 1110 'requires' => 'Requires at least', 1111 'requires_php' => 'Requires PHP', 1112 ), 1113 'plugin' 1114 ); 1115 } 1116 1117 $plugin_data = array_merge( $plugin_data, get_plugin_data( WP_PLUGIN_DIR . '/' . $plugin ) ); 1118 1119 // Check for headers in the plugin's PHP file, give precedence to the plugin headers. 1120 $plugin_data['requires'] = ! empty( $plugin_data['RequiresWP'] ) ? $plugin_data['RequiresWP'] : $plugin_data['requires']; 1121 $plugin_data['requires_php'] = ! empty( $plugin_data['RequiresPHP'] ) ? $plugin_data['RequiresPHP'] : $plugin_data['requires_php']; 1122 1123 $plugin_data['wp_compatible'] = is_wp_version_compatible( $plugin_data['requires'] ); 1124 $plugin_data['php_compatible'] = is_php_version_compatible( $plugin_data['requires_php'] ); 1125 1126 if ( ! $plugin_data['wp_compatible'] && ! $plugin_data['php_compatible'] ) { 1127 return new WP_Error( 1128 'plugin_wp_php_incompatible', 1129 sprintf( 1130 /* translators: %s: Plugin name. */ 1131 __( '<strong>Error:</strong> Current WordPress and PHP versions do not meet minimum requirements for %s.' ), 1132 $plugin_data['Name'] 1133 ) 1134 ); 1135 } elseif ( ! $plugin_data['php_compatible'] ) { 1136 return new WP_Error( 1137 'plugin_php_incompatible', 1138 sprintf( 1139 /* translators: %s: Plugin name. */ 1140 __( '<strong>Error:</strong> Current PHP version does not meet minimum requirements for %s.' ), 1141 $plugin_data['Name'] 1142 ) 1143 ); 1144 } elseif ( ! $plugin_data['wp_compatible'] ) { 1145 return new WP_Error( 1146 'plugin_wp_incompatible', 1147 sprintf( 1148 /* translators: %s: Plugin name. */ 1149 __( '<strong>Error:</strong> Current WordPress version does not meet minimum requirements for %s.' ), 1150 $plugin_data['Name'] 1151 ) 1152 ); 1153 } 1154 1155 return true; 1156 } 1157 1158 /** 1159 * Whether the plugin can be uninstalled. 1160 * 1161 * @since 2.7.0 1162 * 1163 * @param string $plugin Path to the plugin file relative to the plugins directory. 1164 * @return bool Whether plugin can be uninstalled. 1165 */ 1166 function is_uninstallable_plugin( $plugin ) { 1167 $file = plugin_basename( $plugin ); 1168 1169 $uninstallable_plugins = (array) get_option( 'uninstall_plugins' ); 1170 if ( isset( $uninstallable_plugins[ $file ] ) || file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) { 1171 return true; 1172 } 1173 1174 return false; 1175 } 1176 1177 /** 1178 * Uninstall a single plugin. 1179 * 1180 * Calls the uninstall hook, if it is available. 1181 * 1182 * @since 2.7.0 1183 * 1184 * @param string $plugin Path to the plugin file relative to the plugins directory. 1185 * @return true True if a plugin's uninstall.php file has been found and included. 1186 */ 1187 function uninstall_plugin( $plugin ) { 1188 $file = plugin_basename( $plugin ); 1189 1190 $uninstallable_plugins = (array) get_option( 'uninstall_plugins' ); 1191 1192 /** 1193 * Fires in uninstall_plugin() immediately before the plugin is uninstalled. 1194 * 1195 * @since 4.5.0 1196 * 1197 * @param string $plugin Path to the plugin file relative to the plugins directory. 1198 * @param array $uninstallable_plugins Uninstallable plugins. 1199 */ 1200 do_action( 'pre_uninstall_plugin', $plugin, $uninstallable_plugins ); 1201 1202 if ( file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) { 1203 if ( isset( $uninstallable_plugins[ $file ] ) ) { 1204 unset( $uninstallable_plugins[ $file ] ); 1205 update_option( 'uninstall_plugins', $uninstallable_plugins ); 1206 } 1207 unset( $uninstallable_plugins ); 1208 1209 define( 'WP_UNINSTALL_PLUGIN', $file ); 1210 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file ); 1211 include( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ); 1212 1213 return true; 1214 } 1215 1216 if ( isset( $uninstallable_plugins[ $file ] ) ) { 1217 $callable = $uninstallable_plugins[ $file ]; 1218 unset( $uninstallable_plugins[ $file ] ); 1219 update_option( 'uninstall_plugins', $uninstallable_plugins ); 1220 unset( $uninstallable_plugins ); 1221 1222 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file ); 1223 include( WP_PLUGIN_DIR . '/' . $file ); 1224 1225 add_action( "uninstall_{$file}", $callable ); 1226 1227 /** 1228 * Fires in uninstall_plugin() once the plugin has been uninstalled. 1229 * 1230 * The action concatenates the 'uninstall_' prefix with the basename of the 1231 * plugin passed to uninstall_plugin() to create a dynamically-named action. 1232 * 1233 * @since 2.7.0 1234 */ 1235 do_action( "uninstall_{$file}" ); 1236 } 1237 } 1238 1239 // 1240 // Menu 1241 // 1242 1243 /** 1244 * Add a top-level menu page. 1245 * 1246 * This function takes a capability which will be used to determine whether 1247 * or not a page is included in the menu. 1248 * 1249 * The function which is hooked in to handle the output of the page must check 1250 * that the user has the required capability as well. 1251 * 1252 * @since 1.5.0 1253 * 1254 * @global array $menu 1255 * @global array $admin_page_hooks 1256 * @global array $_registered_pages 1257 * @global array $_parent_pages 1258 * 1259 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1260 * @param string $menu_title The text to be used for the menu. 1261 * @param string $capability The capability required for this menu to be displayed to the user. 1262 * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu page and only 1263 * include lowercase alphanumeric, dashes, and underscores characters to be compatible 1264 * with sanitize_key(). 1265 * @param callable $function The function to be called to output the content for this page. 1266 * @param string $icon_url The URL to the icon to be used for this menu. 1267 * * Pass a base64-encoded SVG using a data URI, which will be colored to match 1268 * the color scheme. This should begin with 'data:image/svg+xml;base64,'. 1269 * * Pass the name of a Dashicons helper class to use a font icon, 1270 * e.g. 'dashicons-chart-pie'. 1271 * * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS. 1272 * @param int $position The position in the menu order this item should appear. 1273 * @return string The resulting page's hook_suffix. 1274 */ 1275 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) { 1276 global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages; 1277 1278 $menu_slug = plugin_basename( $menu_slug ); 1279 1280 $admin_page_hooks[ $menu_slug ] = sanitize_title( $menu_title ); 1281 1282 $hookname = get_plugin_page_hookname( $menu_slug, '' ); 1283 1284 if ( ! empty( $function ) && ! empty( $hookname ) && current_user_can( $capability ) ) { 1285 add_action( $hookname, $function ); 1286 } 1287 1288 if ( empty( $icon_url ) ) { 1289 $icon_url = 'dashicons-admin-generic'; 1290 $icon_class = 'menu-icon-generic '; 1291 } else { 1292 $icon_url = set_url_scheme( $icon_url ); 1293 $icon_class = ''; 1294 } 1295 1296 $new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url ); 1297 1298 if ( null === $position ) { 1299 $menu[] = $new_menu; 1300 } elseif ( isset( $menu[ "$position" ] ) ) { 1301 $position = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ), -5 ) * 0.00001; 1302 $menu[ "$position" ] = $new_menu; 1303 } else { 1304 $menu[ $position ] = $new_menu; 1305 } 1306 1307 $_registered_pages[ $hookname ] = true; 1308 1309 // No parent as top level 1310 $_parent_pages[ $menu_slug ] = false; 1311 1312 return $hookname; 1313 } 1314 1315 /** 1316 * Add a submenu page. 1317 * 1318 * This function takes a capability which will be used to determine whether 1319 * or not a page is included in the menu. 1320 * 1321 * The function which is hooked in to handle the output of the page must check 1322 * that the user has the required capability as well. 1323 * 1324 * @since 1.5.0 1325 * @since 5.3.0 Added the `$position` parameter. 1326 * 1327 * @global array $submenu 1328 * @global array $menu 1329 * @global array $_wp_real_parent_file 1330 * @global bool $_wp_submenu_nopriv 1331 * @global array $_registered_pages 1332 * @global array $_parent_pages 1333 * 1334 * @param string $parent_slug The slug name for the parent menu (or the file name of a standard 1335 * WordPress admin page). 1336 * @param string $page_title The text to be displayed in the title tags of the page when the menu 1337 * is selected. 1338 * @param string $menu_title The text to be used for the menu. 1339 * @param string $capability The capability required for this menu to be displayed to the user. 1340 * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu 1341 * and only include lowercase alphanumeric, dashes, and underscores characters 1342 * to be compatible with sanitize_key(). 1343 * @param callable $function The function to be called to output the content for this page. 1344 * @param int $position The position in the menu order this item should appear. 1345 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1346 */ 1347 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1348 global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv, 1349 $_registered_pages, $_parent_pages; 1350 1351 $menu_slug = plugin_basename( $menu_slug ); 1352 $parent_slug = plugin_basename( $parent_slug ); 1353 1354 if ( isset( $_wp_real_parent_file[ $parent_slug ] ) ) { 1355 $parent_slug = $_wp_real_parent_file[ $parent_slug ]; 1356 } 1357 1358 if ( ! current_user_can( $capability ) ) { 1359 $_wp_submenu_nopriv[ $parent_slug ][ $menu_slug ] = true; 1360 return false; 1361 } 1362 1363 /* 1364 * If the parent doesn't already have a submenu, add a link to the parent 1365 * as the first item in the submenu. If the submenu file is the same as the 1366 * parent file someone is trying to link back to the parent manually. In 1367 * this case, don't automatically add a link back to avoid duplication. 1368 */ 1369 if ( ! isset( $submenu[ $parent_slug ] ) && $menu_slug != $parent_slug ) { 1370 foreach ( (array) $menu as $parent_menu ) { 1371 if ( $parent_menu[2] == $parent_slug && current_user_can( $parent_menu[1] ) ) { 1372 $submenu[ $parent_slug ][] = array_slice( $parent_menu, 0, 4 ); 1373 } 1374 } 1375 } 1376 1377 $new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title ); 1378 if ( ! is_int( $position ) ) { 1379 if ( null !== $position ) { 1380 _doing_it_wrong( 1381 __FUNCTION__, 1382 sprintf( 1383 /* translators: %s: add_submenu_page() */ 1384 __( 'The seventh parameter passed to %s should be an integer representing menu position.' ), 1385 '<code>add_submenu_page()</code>' 1386 ), 1387 '5.3.0' 1388 ); 1389 } 1390 1391 $submenu[ $parent_slug ][] = $new_sub_menu; 1392 } else { 1393 // Append the submenu if the parent item is not present in the submenu, 1394 // or if position is equal or higher than the number of items in the array. 1395 if ( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) ) { 1396 $submenu[ $parent_slug ][] = $new_sub_menu; 1397 } else { 1398 // Test for a negative position. 1399 $position = max( $position, 0 ); 1400 if ( 0 === $position ) { 1401 // For negative or `0` positions, prepend the submenu. 1402 array_unshift( $submenu[ $parent_slug ], $new_sub_menu ); 1403 } else { 1404 // Grab all of the items before the insertion point. 1405 $before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true ); 1406 // Grab all of the items after the insertion point. 1407 $after_items = array_slice( $submenu[ $parent_slug ], $position, null, true ); 1408 // Add the new item. 1409 $before_items[] = $new_sub_menu; 1410 // Merge the items. 1411 $submenu[ $parent_slug ] = array_merge( $before_items, $after_items ); 1412 } 1413 } 1414 } 1415 // Sort the parent array 1416 ksort( $submenu[ $parent_slug ] ); 1417 1418 $hookname = get_plugin_page_hookname( $menu_slug, $parent_slug ); 1419 if ( ! empty( $function ) && ! empty( $hookname ) ) { 1420 add_action( $hookname, $function ); 1421 } 1422 1423 $_registered_pages[ $hookname ] = true; 1424 1425 /* 1426 * Backward-compatibility for plugins using add_management_page(). 1427 * See wp-admin/admin.php for redirect from edit.php to tools.php. 1428 */ 1429 if ( 'tools.php' == $parent_slug ) { 1430 $_registered_pages[ get_plugin_page_hookname( $menu_slug, 'edit.php' ) ] = true; 1431 } 1432 1433 // No parent as top level. 1434 $_parent_pages[ $menu_slug ] = $parent_slug; 1435 1436 return $hookname; 1437 } 1438 1439 /** 1440 * Add submenu page to the Tools main menu. 1441 * 1442 * This function takes a capability which will be used to determine whether 1443 * or not a page is included in the menu. 1444 * 1445 * The function which is hooked in to handle the output of the page must check 1446 * that the user has the required capability as well. 1447 * 1448 * @since 1.5.0 1449 * @since 5.3.0 Added the `$position` parameter. 1450 * 1451 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1452 * @param string $menu_title The text to be used for the menu. 1453 * @param string $capability The capability required for this menu to be displayed to the user. 1454 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1455 * @param callable $function The function to be called to output the content for this page. 1456 * @param int $position The position in the menu order this item should appear. 1457 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1458 */ 1459 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1460 return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1461 } 1462 1463 /** 1464 * Add submenu page to the Settings main menu. 1465 * 1466 * This function takes a capability which will be used to determine whether 1467 * or not a page is included in the menu. 1468 * 1469 * The function which is hooked in to handle the output of the page must check 1470 * that the user has the required capability as well. 1471 * 1472 * @since 1.5.0 1473 * @since 5.3.0 Added the `$position` parameter. 1474 * 1475 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1476 * @param string $menu_title The text to be used for the menu. 1477 * @param string $capability The capability required for this menu to be displayed to the user. 1478 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1479 * @param callable $function The function to be called to output the content for this page. 1480 * @param int $position The position in the menu order this item should appear. 1481 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1482 */ 1483 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1484 return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1485 } 1486 1487 /** 1488 * Add submenu page to the Appearance main menu. 1489 * 1490 * This function takes a capability which will be used to determine whether 1491 * or not a page is included in the menu. 1492 * 1493 * The function which is hooked in to handle the output of the page must check 1494 * that the user has the required capability as well. 1495 * 1496 * @since 2.0.0 1497 * @since 5.3.0 Added the `$position` parameter. 1498 * 1499 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1500 * @param string $menu_title The text to be used for the menu. 1501 * @param string $capability The capability required for this menu to be displayed to the user. 1502 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1503 * @param callable $function The function to be called to output the content for this page. 1504 * @param int $position The position in the menu order this item should appear. 1505 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1506 */ 1507 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1508 return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1509 } 1510 1511 /** 1512 * Add submenu page to the Plugins main menu. 1513 * 1514 * This function takes a capability which will be used to determine whether 1515 * or not a page is included in the menu. 1516 * 1517 * The function which is hooked in to handle the output of the page must check 1518 * that the user has the required capability as well. 1519 * 1520 * @since 3.0.0 1521 * @since 5.3.0 Added the `$position` parameter. 1522 * 1523 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1524 * @param string $menu_title The text to be used for the menu. 1525 * @param string $capability The capability required for this menu to be displayed to the user. 1526 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1527 * @param callable $function The function to be called to output the content for this page. 1528 * @param int $position The position in the menu order this item should appear. 1529 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1530 */ 1531 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1532 return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1533 } 1534 1535 /** 1536 * Add submenu page to the Users/Profile main menu. 1537 * 1538 * This function takes a capability which will be used to determine whether 1539 * or not a page is included in the menu. 1540 * 1541 * The function which is hooked in to handle the output of the page must check 1542 * that the user has the required capability as well. 1543 * 1544 * @since 2.1.3 1545 * @since 5.3.0 Added the `$position` parameter. 1546 * 1547 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1548 * @param string $menu_title The text to be used for the menu. 1549 * @param string $capability The capability required for this menu to be displayed to the user. 1550 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1551 * @param callable $function The function to be called to output the content for this page. 1552 * @param int $position The position in the menu order this item should appear. 1553 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1554 */ 1555 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1556 if ( current_user_can( 'edit_users' ) ) { 1557 $parent = 'users.php'; 1558 } else { 1559 $parent = 'profile.php'; 1560 } 1561 return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1562 } 1563 1564 /** 1565 * Add submenu page to the Dashboard main menu. 1566 * 1567 * This function takes a capability which will be used to determine whether 1568 * or not a page is included in the menu. 1569 * 1570 * The function which is hooked in to handle the output of the page must check 1571 * that the user has the required capability as well. 1572 * 1573 * @since 2.7.0 1574 * @since 5.3.0 Added the `$position` parameter. 1575 * 1576 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1577 * @param string $menu_title The text to be used for the menu. 1578 * @param string $capability The capability required for this menu to be displayed to the user. 1579 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1580 * @param callable $function The function to be called to output the content for this page. 1581 * @param int $position The position in the menu order this item should appear. 1582 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1583 */ 1584 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1585 return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1586 } 1587 1588 /** 1589 * Add submenu page to the Posts main menu. 1590 * 1591 * This function takes a capability which will be used to determine whether 1592 * or not a page is included in the menu. 1593 * 1594 * The function which is hooked in to handle the output of the page must check 1595 * that the user has the required capability as well. 1596 * 1597 * @since 2.7.0 1598 * @since 5.3.0 Added the `$position` parameter. 1599 * 1600 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1601 * @param string $menu_title The text to be used for the menu. 1602 * @param string $capability The capability required for this menu to be displayed to the user. 1603 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1604 * @param callable $function The function to be called to output the content for this page. 1605 * @param int $position The position in the menu order this item should appear. 1606 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1607 */ 1608 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1609 return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1610 } 1611 1612 /** 1613 * Add submenu page to the Media main menu. 1614 * 1615 * This function takes a capability which will be used to determine whether 1616 * or not a page is included in the menu. 1617 * 1618 * The function which is hooked in to handle the output of the page must check 1619 * that the user has the required capability as well. 1620 * 1621 * @since 2.7.0 1622 * @since 5.3.0 Added the `$position` parameter. 1623 * 1624 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1625 * @param string $menu_title The text to be used for the menu. 1626 * @param string $capability The capability required for this menu to be displayed to the user. 1627 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1628 * @param callable $function The function to be called to output the content for this page. 1629 * @param int $position The position in the menu order this item should appear. 1630 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1631 */ 1632 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1633 return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1634 } 1635 1636 /** 1637 * Add submenu page to the Links main menu. 1638 * 1639 * This function takes a capability which will be used to determine whether 1640 * or not a page is included in the menu. 1641 * 1642 * The function which is hooked in to handle the output of the page must check 1643 * that the user has the required capability as well. 1644 * 1645 * @since 2.7.0 1646 * @since 5.3.0 Added the `$position` parameter. 1647 * 1648 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1649 * @param string $menu_title The text to be used for the menu. 1650 * @param string $capability The capability required for this menu to be displayed to the user. 1651 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1652 * @param callable $function The function to be called to output the content for this page. 1653 * @param int $position The position in the menu order this item should appear. 1654 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1655 */ 1656 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1657 return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1658 } 1659 1660 /** 1661 * Add submenu page to the Pages main menu. 1662 * 1663 * This function takes a capability which will be used to determine whether 1664 * or not a page is included in the menu. 1665 * 1666 * The function which is hooked in to handle the output of the page must check 1667 * that the user has the required capability as well. 1668 * 1669 * @since 2.7.0 1670 * @since 5.3.0 Added the `$position` parameter. 1671 * 1672 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1673 * @param string $menu_title The text to be used for the menu. 1674 * @param string $capability The capability required for this menu to be displayed to the user. 1675 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1676 * @param callable $function The function to be called to output the content for this page. 1677 * @param int $position The position in the menu order this item should appear. 1678 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1679 */ 1680 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1681 return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1682 } 1683 1684 /** 1685 * Add submenu page to the Comments main menu. 1686 * 1687 * This function takes a capability which will be used to determine whether 1688 * or not a page is included in the menu. 1689 * 1690 * The function which is hooked in to handle the output of the page must check 1691 * that the user has the required capability as well. 1692 * 1693 * @since 2.7.0 1694 * @since 5.3.0 Added the `$position` parameter. 1695 * 1696 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1697 * @param string $menu_title The text to be used for the menu. 1698 * @param string $capability The capability required for this menu to be displayed to the user. 1699 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1700 * @param callable $function The function to be called to output the content for this page. 1701 * @param int $position The position in the menu order this item should appear. 1702 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required. 1703 */ 1704 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1705 return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1706 } 1707 1708 /** 1709 * Remove a top-level admin menu. 1710 * 1711 * @since 3.1.0 1712 * 1713 * @global array $menu 1714 * 1715 * @param string $menu_slug The slug of the menu. 1716 * @return array|bool The removed menu on success, false if not found. 1717 */ 1718 function remove_menu_page( $menu_slug ) { 1719 global $menu; 1720 1721 foreach ( $menu as $i => $item ) { 1722 if ( $menu_slug == $item[2] ) { 1723 unset( $menu[ $i ] ); 1724 return $item; 1725 } 1726 } 1727 1728 return false; 1729 } 1730 1731 /** 1732 * Remove an admin submenu. 1733 * 1734 * @since 3.1.0 1735 * 1736 * @global array $submenu 1737 * 1738 * @param string $menu_slug The slug for the parent menu. 1739 * @param string $submenu_slug The slug of the submenu. 1740 * @return array|bool The removed submenu on success, false if not found. 1741 */ 1742 function remove_submenu_page( $menu_slug, $submenu_slug ) { 1743 global $submenu; 1744 1745 if ( ! isset( $submenu[ $menu_slug ] ) ) { 1746 return false; 1747 } 1748 1749 foreach ( $submenu[ $menu_slug ] as $i => $item ) { 1750 if ( $submenu_slug == $item[2] ) { 1751 unset( $submenu[ $menu_slug ][ $i ] ); 1752 return $item; 1753 } 1754 } 1755 1756 return false; 1757 } 1758 1759 /** 1760 * Get the URL to access a particular menu page based on the slug it was registered with. 1761 * 1762 * If the slug hasn't been registered properly, no URL will be returned. 1763 * 1764 * @since 3.0.0 1765 * 1766 * @global array $_parent_pages 1767 * 1768 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1769 * @param bool $echo Whether or not to echo the URL. Default true. 1770 * @return string The menu page URL. 1771 */ 1772 function menu_page_url( $menu_slug, $echo = true ) { 1773 global $_parent_pages; 1774 1775 if ( isset( $_parent_pages[ $menu_slug ] ) ) { 1776 $parent_slug = $_parent_pages[ $menu_slug ]; 1777 if ( $parent_slug && ! isset( $_parent_pages[ $parent_slug ] ) ) { 1778 $url = admin_url( add_query_arg( 'page', $menu_slug, $parent_slug ) ); 1779 } else { 1780 $url = admin_url( 'admin.php?page=' . $menu_slug ); 1781 } 1782 } else { 1783 $url = ''; 1784 } 1785 1786 $url = esc_url( $url ); 1787 1788 if ( $echo ) { 1789 echo $url; 1790 } 1791 1792 return $url; 1793 } 1794 1795 // 1796 // Pluggable Menu Support -- Private 1797 // 1798 /** 1799 * Gets the parent file of the current admin page. 1800 * 1801 * @since 1.5.0 1802 * 1803 * @global string $parent_file 1804 * @global array $menu 1805 * @global array $submenu 1806 * @global string $pagenow 1807 * @global string $typenow 1808 * @global string $plugin_page 1809 * @global array $_wp_real_parent_file 1810 * @global array $_wp_menu_nopriv 1811 * @global array $_wp_submenu_nopriv 1812 * 1813 * @return string The parent file of the current admin page. 1814 */ 1815 function get_admin_page_parent( $parent = '' ) { 1816 global $parent_file, $menu, $submenu, $pagenow, $typenow, 1817 $plugin_page, $_wp_real_parent_file, $_wp_menu_nopriv, $_wp_submenu_nopriv; 1818 1819 if ( ! empty( $parent ) && 'admin.php' != $parent ) { 1820 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1821 $parent = $_wp_real_parent_file[ $parent ]; 1822 } 1823 return $parent; 1824 } 1825 1826 if ( $pagenow == 'admin.php' && isset( $plugin_page ) ) { 1827 foreach ( (array) $menu as $parent_menu ) { 1828 if ( $parent_menu[2] == $plugin_page ) { 1829 $parent_file = $plugin_page; 1830 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1831 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1832 } 1833 return $parent_file; 1834 } 1835 } 1836 if ( isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 1837 $parent_file = $plugin_page; 1838 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1839 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1840 } 1841 return $parent_file; 1842 } 1843 } 1844 1845 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 1846 $parent_file = $pagenow; 1847 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1848 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1849 } 1850 return $parent_file; 1851 } 1852 1853 foreach ( array_keys( (array) $submenu ) as $parent ) { 1854 foreach ( $submenu[ $parent ] as $submenu_array ) { 1855 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1856 $parent = $_wp_real_parent_file[ $parent ]; 1857 } 1858 if ( ! empty( $typenow ) && ( $submenu_array[2] == "$pagenow?post_type=$typenow" ) ) { 1859 $parent_file = $parent; 1860 return $parent; 1861 } elseif ( $submenu_array[2] == $pagenow && empty( $typenow ) && ( empty( $parent_file ) || false === strpos( $parent_file, '?' ) ) ) { 1862 $parent_file = $parent; 1863 return $parent; 1864 } elseif ( isset( $plugin_page ) && ( $plugin_page == $submenu_array[2] ) ) { 1865 $parent_file = $parent; 1866 return $parent; 1867 } 1868 } 1869 } 1870 1871 if ( empty( $parent_file ) ) { 1872 $parent_file = ''; 1873 } 1874 return ''; 1875 } 1876 1877 /** 1878 * Gets the title of the current admin page. 1879 * 1880 * @since 1.5.0 1881 * 1882 * @global string $title 1883 * @global array $menu 1884 * @global array $submenu 1885 * @global string $pagenow 1886 * @global string $plugin_page 1887 * @global string $typenow 1888 * 1889 * @return string The title of the current admin page. 1890 */ 1891 function get_admin_page_title() { 1892 global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow; 1893 1894 if ( ! empty( $title ) ) { 1895 return $title; 1896 } 1897 1898 $hook = get_plugin_page_hook( $plugin_page, $pagenow ); 1899 1900 $parent = get_admin_page_parent(); 1901 $parent1 = $parent; 1902 1903 if ( empty( $parent ) ) { 1904 foreach ( (array) $menu as $menu_array ) { 1905 if ( isset( $menu_array[3] ) ) { 1906 if ( $menu_array[2] == $pagenow ) { 1907 $title = $menu_array[3]; 1908 return $menu_array[3]; 1909 } elseif ( isset( $plugin_page ) && ( $plugin_page == $menu_array[2] ) && ( $hook == $menu_array[3] ) ) { 1910 $title = $menu_array[3]; 1911 return $menu_array[3]; 1912 } 1913 } else { 1914 $title = $menu_array[0]; 1915 return $title; 1916 } 1917 } 1918 } else { 1919 foreach ( array_keys( $submenu ) as $parent ) { 1920 foreach ( $submenu[ $parent ] as $submenu_array ) { 1921 if ( isset( $plugin_page ) && 1922 ( $plugin_page == $submenu_array[2] ) && 1923 ( 1924 ( $parent == $pagenow ) || 1925 ( $parent == $plugin_page ) || 1926 ( $plugin_page == $hook ) || 1927 ( $pagenow == 'admin.php' && $parent1 != $submenu_array[2] ) || 1928 ( ! empty( $typenow ) && $parent == $pagenow . '?post_type=' . $typenow ) 1929 ) 1930 ) { 1931 $title = $submenu_array[3]; 1932 return $submenu_array[3]; 1933 } 1934 1935 if ( $submenu_array[2] != $pagenow || isset( $_GET['page'] ) ) { // not the current page 1936 continue; 1937 } 1938 1939 if ( isset( $submenu_array[3] ) ) { 1940 $title = $submenu_array[3]; 1941 return $submenu_array[3]; 1942 } else { 1943 $title = $submenu_array[0]; 1944 return $title; 1945 } 1946 } 1947 } 1948 if ( empty( $title ) ) { 1949 foreach ( $menu as $menu_array ) { 1950 if ( isset( $plugin_page ) && 1951 ( $plugin_page == $menu_array[2] ) && 1952 ( $pagenow == 'admin.php' ) && 1953 ( $parent1 == $menu_array[2] ) ) { 1954 $title = $menu_array[3]; 1955 return $menu_array[3]; 1956 } 1957 } 1958 } 1959 } 1960 1961 return $title; 1962 } 1963 1964 /** 1965 * Gets the hook attached to the administrative page of a plugin. 1966 * 1967 * @since 1.5.0 1968 * 1969 * @param string $plugin_page The slug name of the plugin page. 1970 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1971 * WordPress admin page). 1972 * @return string|null Hook attached to the plugin page, null otherwise. 1973 */ 1974 function get_plugin_page_hook( $plugin_page, $parent_page ) { 1975 $hook = get_plugin_page_hookname( $plugin_page, $parent_page ); 1976 if ( has_action( $hook ) ) { 1977 return $hook; 1978 } else { 1979 return null; 1980 } 1981 } 1982 1983 /** 1984 * Gets the hook name for the administrative page of a plugin. 1985 * 1986 * @since 1.5.0 1987 * 1988 * @global array $admin_page_hooks 1989 * 1990 * @param string $plugin_page The slug name of the plugin page. 1991 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1992 * WordPress admin page). 1993 * @return string Hook name for the plugin page. 1994 */ 1995 function get_plugin_page_hookname( $plugin_page, $parent_page ) { 1996 global $admin_page_hooks; 1997 1998 $parent = get_admin_page_parent( $parent_page ); 1999 2000 $page_type = 'admin'; 2001 if ( empty( $parent_page ) || 'admin.php' == $parent_page || isset( $admin_page_hooks[ $plugin_page ] ) ) { 2002 if ( isset( $admin_page_hooks[ $plugin_page ] ) ) { 2003 $page_type = 'toplevel'; 2004 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 2005 $page_type = $admin_page_hooks[ $parent ]; 2006 } 2007 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 2008 $page_type = $admin_page_hooks[ $parent ]; 2009 } 2010 2011 $plugin_name = preg_replace( '!\.php!', '', $plugin_page ); 2012 2013 return $page_type . '_page_' . $plugin_name; 2014 } 2015 2016 /** 2017 * Determines whether the current user can access the current admin page. 2018 * 2019 * @since 1.5.0 2020 * 2021 * @global string $pagenow 2022 * @global array $menu 2023 * @global array $submenu 2024 * @global array $_wp_menu_nopriv 2025 * @global array $_wp_submenu_nopriv 2026 * @global string $plugin_page 2027 * @global array $_registered_pages 2028 * 2029 * @return bool True if the current user can access the admin page, false otherwise. 2030 */ 2031 function user_can_access_admin_page() { 2032 global $pagenow, $menu, $submenu, $_wp_menu_nopriv, $_wp_submenu_nopriv, 2033 $plugin_page, $_registered_pages; 2034 2035 $parent = get_admin_page_parent(); 2036 2037 if ( ! isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $parent ][ $pagenow ] ) ) { 2038 return false; 2039 } 2040 2041 if ( isset( $plugin_page ) ) { 2042 if ( isset( $_wp_submenu_nopriv[ $parent ][ $plugin_page ] ) ) { 2043 return false; 2044 } 2045 2046 $hookname = get_plugin_page_hookname( $plugin_page, $parent ); 2047 2048 if ( ! isset( $_registered_pages[ $hookname ] ) ) { 2049 return false; 2050 } 2051 } 2052 2053 if ( empty( $parent ) ) { 2054 if ( isset( $_wp_menu_nopriv[ $pagenow ] ) ) { 2055 return false; 2056 } 2057 if ( isset( $_wp_submenu_nopriv[ $pagenow ][ $pagenow ] ) ) { 2058 return false; 2059 } 2060 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 2061 return false; 2062 } 2063 if ( isset( $plugin_page ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2064 return false; 2065 } 2066 foreach ( array_keys( $_wp_submenu_nopriv ) as $key ) { 2067 if ( isset( $_wp_submenu_nopriv[ $key ][ $pagenow ] ) ) { 2068 return false; 2069 } 2070 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $key ][ $plugin_page ] ) ) { 2071 return false; 2072 } 2073 } 2074 return true; 2075 } 2076 2077 if ( isset( $plugin_page ) && ( $plugin_page == $parent ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2078 return false; 2079 } 2080 2081 if ( isset( $submenu[ $parent ] ) ) { 2082 foreach ( $submenu[ $parent ] as $submenu_array ) { 2083 if ( isset( $plugin_page ) && ( $submenu_array[2] == $plugin_page ) ) { 2084 if ( current_user_can( $submenu_array[1] ) ) { 2085 return true; 2086 } else { 2087 return false; 2088 } 2089 } elseif ( $submenu_array[2] == $pagenow ) { 2090 if ( current_user_can( $submenu_array[1] ) ) { 2091 return true; 2092 } else { 2093 return false; 2094 } 2095 } 2096 } 2097 } 2098 2099 foreach ( $menu as $menu_array ) { 2100 if ( $menu_array[2] == $parent ) { 2101 if ( current_user_can( $menu_array[1] ) ) { 2102 return true; 2103 } else { 2104 return false; 2105 } 2106 } 2107 } 2108 2109 return true; 2110 } 2111 2112 /* Whitelist functions */ 2113 2114 /** 2115 * Refreshes the value of the options whitelist available via the 'whitelist_options' hook. 2116 * 2117 * See the {@see 'whitelist_options'} filter. 2118 * 2119 * @since 2.7.0 2120 * 2121 * @global array $new_whitelist_options 2122 * 2123 * @param array $options 2124 * @return array 2125 */ 2126 function option_update_filter( $options ) { 2127 global $new_whitelist_options; 2128 2129 if ( is_array( $new_whitelist_options ) ) { 2130 $options = add_option_whitelist( $new_whitelist_options, $options ); 2131 } 2132 2133 return $options; 2134 } 2135 2136 /** 2137 * Adds an array of options to the options whitelist. 2138 * 2139 * @since 2.7.0 2140 * 2141 * @global array $whitelist_options 2142 * 2143 * @param array $new_options 2144 * @param string|array $options 2145 * @return array 2146 */ 2147 function add_option_whitelist( $new_options, $options = '' ) { 2148 if ( $options == '' ) { 2149 global $whitelist_options; 2150 } else { 2151 $whitelist_options = $options; 2152 } 2153 2154 foreach ( $new_options as $page => $keys ) { 2155 foreach ( $keys as $key ) { 2156 if ( ! isset( $whitelist_options[ $page ] ) || ! is_array( $whitelist_options[ $page ] ) ) { 2157 $whitelist_options[ $page ] = array(); 2158 $whitelist_options[ $page ][] = $key; 2159 } else { 2160 $pos = array_search( $key, $whitelist_options[ $page ] ); 2161 if ( $pos === false ) { 2162 $whitelist_options[ $page ][] = $key; 2163 } 2164 } 2165 } 2166 } 2167 2168 return $whitelist_options; 2169 } 2170 2171 /** 2172 * Removes a list of options from the options whitelist. 2173 * 2174 * @since 2.7.0 2175 * 2176 * @global array $whitelist_options 2177 * 2178 * @param array $del_options 2179 * @param string|array $options 2180 * @return array 2181 */ 2182 function remove_option_whitelist( $del_options, $options = '' ) { 2183 if ( $options == '' ) { 2184 global $whitelist_options; 2185 } else { 2186 $whitelist_options = $options; 2187 } 2188 2189 foreach ( $del_options as $page => $keys ) { 2190 foreach ( $keys as $key ) { 2191 if ( isset( $whitelist_options[ $page ] ) && is_array( $whitelist_options[ $page ] ) ) { 2192 $pos = array_search( $key, $whitelist_options[ $page ] ); 2193 if ( $pos !== false ) { 2194 unset( $whitelist_options[ $page ][ $pos ] ); 2195 } 2196 } 2197 } 2198 } 2199 2200 return $whitelist_options; 2201 } 2202 2203 /** 2204 * Output nonce, action, and option_page fields for a settings page. 2205 * 2206 * @since 2.7.0 2207 * 2208 * @param string $option_group A settings group name. This should match the group name 2209 * used in register_setting(). 2210 */ 2211 function settings_fields( $option_group ) { 2212 echo "<input type='hidden' name='option_page' value='" . esc_attr( $option_group ) . "' />"; 2213 echo '<input type="hidden" name="action" value="update" />'; 2214 wp_nonce_field( "$option_group-options" ); 2215 } 2216 2217 /** 2218 * Clears the plugins cache used by get_plugins() and by default, the plugin updates cache. 2219 * 2220 * @since 3.7.0 2221 * 2222 * @param bool $clear_update_cache Whether to clear the plugin updates cache. Default true. 2223 */ 2224 function wp_clean_plugins_cache( $clear_update_cache = true ) { 2225 if ( $clear_update_cache ) { 2226 delete_site_transient( 'update_plugins' ); 2227 } 2228 wp_cache_delete( 'plugins', 'plugins' ); 2229 } 2230 2231 /** 2232 * Load a given plugin attempt to generate errors. 2233 * 2234 * @since 3.0.0 2235 * @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file. 2236 * 2237 * @param string $plugin Path to the plugin file relative to the plugins directory. 2238 */ 2239 function plugin_sandbox_scrape( $plugin ) { 2240 if ( ! defined( 'WP_SANDBOX_SCRAPING' ) ) { 2241 define( 'WP_SANDBOX_SCRAPING', true ); 2242 } 2243 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin ); 2244 include( WP_PLUGIN_DIR . '/' . $plugin ); 2245 } 2246 2247 /** 2248 * Helper function for adding content to the Privacy Policy Guide. 2249 * 2250 * Plugins and themes should suggest text for inclusion in the site's privacy policy. 2251 * The suggested text should contain information about any functionality that affects user privacy, 2252 * and will be shown on the Privacy Policy Guide screen. 2253 * 2254 * A plugin or theme can use this function multiple times as long as it will help to better present 2255 * the suggested policy content. For example modular plugins such as WooCommerse or Jetpack 2256 * can add or remove suggested content depending on the modules/extensions that are enabled. 2257 * For more information see the Plugin Handbook: 2258 * https://developer.wordpress.org/plugins/privacy/suggesting-text-for-the-site-privacy-policy/. 2259 * 2260 * Intended for use with the `'admin_init'` action. 2261 * 2262 * @since 4.9.6 2263 * 2264 * @param string $plugin_name The name of the plugin or theme that is suggesting content 2265 * for the site's privacy policy. 2266 * @param string $policy_text The suggested content for inclusion in the policy. 2267 */ 2268 function wp_add_privacy_policy_content( $plugin_name, $policy_text ) { 2269 if ( ! is_admin() ) { 2270 _doing_it_wrong( 2271 __FUNCTION__, 2272 sprintf( 2273 /* translators: %s: admin_init */ 2274 __( 'The suggested privacy policy content should be added only in wp-admin by using the %s (or later) action.' ), 2275 '<code>admin_init</code>' 2276 ), 2277 '4.9.7' 2278 ); 2279 return; 2280 } elseif ( ! doing_action( 'admin_init' ) && ! did_action( 'admin_init' ) ) { 2281 _doing_it_wrong( 2282 __FUNCTION__, 2283 sprintf( 2284 /* translators: %s: admin_init */ 2285 __( 'The suggested privacy policy content should be added by using the %s (or later) action. Please see the inline documentation.' ), 2286 '<code>admin_init</code>' 2287 ), 2288 '4.9.7' 2289 ); 2290 return; 2291 } 2292 2293 if ( ! class_exists( 'WP_Privacy_Policy_Content' ) ) { 2294 require_once( ABSPATH . 'wp-admin/includes/class-wp-privacy-policy-content.php' ); 2295 } 2296 2297 WP_Privacy_Policy_Content::add( $plugin_name, $policy_text ); 2298 } 2299 2300 /** 2301 * Determines whether a plugin is technically active but was paused while 2302 * loading. 2303 * 2304 * For more information on this and similar theme functions, check out 2305 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 2306 * Conditional Tags} article in the Theme Developer Handbook. 2307 * 2308 * @since 5.2.0 2309 * 2310 * @param string $plugin Path to the plugin file relative to the plugins directory. 2311 * @return bool True, if in the list of paused plugins. False, if not in the list. 2312 */ 2313 function is_plugin_paused( $plugin ) { 2314 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2315 return false; 2316 } 2317 2318 if ( ! is_plugin_active( $plugin ) ) { 2319 return false; 2320 } 2321 2322 list( $plugin ) = explode( '/', $plugin ); 2323 2324 return array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ); 2325 } 2326 2327 /** 2328 * Gets the error that was recorded for a paused plugin. 2329 * 2330 * @since 5.2.0 2331 * 2332 * @param string $plugin Path to the plugin file relative to the plugins directory. 2333 * @return array|false Array of error information as returned by `error_get_last()`, 2334 * or false if none was recorded. 2335 */ 2336 function wp_get_plugin_error( $plugin ) { 2337 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2338 return false; 2339 } 2340 2341 list( $plugin ) = explode( '/', $plugin ); 2342 2343 if ( ! array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ) ) { 2344 return false; 2345 } 2346 2347 return $GLOBALS['_paused_plugins'][ $plugin ]; 2348 } 2349 2350 /** 2351 * Tries to resume a single plugin. 2352 * 2353 * If a redirect was provided, we first ensure the plugin does not throw fatal 2354 * errors anymore. 2355 * 2356 * The way it works is by setting the redirection to the error before trying to 2357 * include the plugin file. If the plugin fails, then the redirection will not 2358 * be overwritten with the success message and the plugin will not be resumed. 2359 * 2360 * @since 5.2.0 2361 * 2362 * @param string $plugin Single plugin to resume. 2363 * @param string $redirect Optional. URL to redirect to. Default empty string. 2364 * @return bool|WP_Error True on success, false if `$plugin` was not paused, 2365 * `WP_Error` on failure. 2366 */ 2367 function resume_plugin( $plugin, $redirect = '' ) { 2368 /* 2369 * We'll override this later if the plugin could be resumed without 2370 * creating a fatal error. 2371 */ 2372 if ( ! empty( $redirect ) ) { 2373 wp_redirect( 2374 add_query_arg( 2375 '_error_nonce', 2376 wp_create_nonce( 'plugin-resume-error_' . $plugin ), 2377 $redirect 2378 ) 2379 ); 2380 2381 // Load the plugin to test whether it throws a fatal error. 2382 ob_start(); 2383 plugin_sandbox_scrape( $plugin ); 2384 ob_clean(); 2385 } 2386 2387 list( $extension ) = explode( '/', $plugin ); 2388 2389 $result = wp_paused_plugins()->delete( $extension ); 2390 2391 if ( ! $result ) { 2392 return new WP_Error( 2393 'could_not_resume_plugin', 2394 __( 'Could not resume the plugin.' ) 2395 ); 2396 } 2397 2398 return true; 2399 } 2400 2401 /** 2402 * Renders an admin notice in case some plugins have been paused due to errors. 2403 * 2404 * @since 5.2.0 2405 */ 2406 function paused_plugins_notice() { 2407 if ( 'plugins.php' === $GLOBALS['pagenow'] ) { 2408 return; 2409 } 2410 2411 if ( ! current_user_can( 'resume_plugins' ) ) { 2412 return; 2413 } 2414 2415 if ( ! isset( $GLOBALS['_paused_plugins'] ) || empty( $GLOBALS['_paused_plugins'] ) ) { 2416 return; 2417 } 2418 2419 printf( 2420 '<div class="notice notice-error"><p><strong>%s</strong><br>%s</p><p><a href="%s">%s</a></p></div>', 2421 __( 'One or more plugins failed to load properly.' ), 2422 __( 'You can find more details and make changes on the Plugins screen.' ), 2423 esc_url( admin_url( 'plugins.php?plugin_status=paused' ) ), 2424 __( 'Go to the Plugins screen' ) 2425 ); 2426 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Jan 21 01:00:03 2020 | Cross-referenced by PHPXref 0.7.1 |