| [ 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 WP_Error on invalid file or null on success. 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 false|string 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 // If position is equal or higher than the number of items in the array, append the submenu. 1394 if ( $position >= count( $submenu[ $parent_slug ] ) ) { 1395 $submenu[ $parent_slug ][] = $new_sub_menu; 1396 } else { 1397 // Test for a negative position. 1398 $position = max( $position, 0 ); 1399 if ( 0 === $position ) { 1400 // For negative or `0` positions, prepend the submenu. 1401 array_unshift( $submenu[ $parent_slug ], $new_sub_menu ); 1402 } else { 1403 // Grab all of the items before the insertion point. 1404 $before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true ); 1405 // Grab all of the items after the insertion point. 1406 $after_items = array_slice( $submenu[ $parent_slug ], $position, null, true ); 1407 // Add the new item. 1408 $before_items[] = $new_sub_menu; 1409 // Merge the items. 1410 $submenu[ $parent_slug ] = array_merge( $before_items, $after_items ); 1411 } 1412 } 1413 } 1414 // Sort the parent array 1415 ksort( $submenu[ $parent_slug ] ); 1416 1417 $hookname = get_plugin_page_hookname( $menu_slug, $parent_slug ); 1418 if ( ! empty( $function ) && ! empty( $hookname ) ) { 1419 add_action( $hookname, $function ); 1420 } 1421 1422 $_registered_pages[ $hookname ] = true; 1423 1424 /* 1425 * Backward-compatibility for plugins using add_management_page(). 1426 * See wp-admin/admin.php for redirect from edit.php to tools.php. 1427 */ 1428 if ( 'tools.php' == $parent_slug ) { 1429 $_registered_pages[ get_plugin_page_hookname( $menu_slug, 'edit.php' ) ] = true; 1430 } 1431 1432 // No parent as top level. 1433 $_parent_pages[ $menu_slug ] = $parent_slug; 1434 1435 return $hookname; 1436 } 1437 1438 /** 1439 * Add submenu page to the Tools main menu. 1440 * 1441 * This function takes a capability which will be used to determine whether 1442 * or not a page is included in the menu. 1443 * 1444 * The function which is hooked in to handle the output of the page must check 1445 * that the user has the required capability as well. 1446 * 1447 * @since 1.5.0 1448 * @since 5.3.0 Added the `$position` parameter. 1449 * 1450 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1451 * @param string $menu_title The text to be used for the menu. 1452 * @param string $capability The capability required for this menu to be displayed to the user. 1453 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1454 * @param callable $function The function to be called to output the content for this page. 1455 * @param int $position The position in the menu order this item should appear. 1456 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1457 */ 1458 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1459 return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1460 } 1461 1462 /** 1463 * Add submenu page to the Settings main menu. 1464 * 1465 * This function takes a capability which will be used to determine whether 1466 * or not a page is included in the menu. 1467 * 1468 * The function which is hooked in to handle the output of the page must check 1469 * that the user has the required capability as well. 1470 * 1471 * @since 1.5.0 1472 * @since 5.3.0 Added the `$position` parameter. 1473 * 1474 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1475 * @param string $menu_title The text to be used for the menu. 1476 * @param string $capability The capability required for this menu to be displayed to the user. 1477 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1478 * @param callable $function The function to be called to output the content for this page. 1479 * @param int $position The position in the menu order this item should appear. 1480 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1481 */ 1482 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1483 return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1484 } 1485 1486 /** 1487 * Add submenu page to the Appearance main menu. 1488 * 1489 * This function takes a capability which will be used to determine whether 1490 * or not a page is included in the menu. 1491 * 1492 * The function which is hooked in to handle the output of the page must check 1493 * that the user has the required capability as well. 1494 * 1495 * @since 2.0.0 1496 * @since 5.3.0 Added the `$position` parameter. 1497 * 1498 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1499 * @param string $menu_title The text to be used for the menu. 1500 * @param string $capability The capability required for this menu to be displayed to the user. 1501 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1502 * @param callable $function The function to be called to output the content for this page. 1503 * @param int $position The position in the menu order this item should appear. 1504 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1505 */ 1506 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1507 return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1508 } 1509 1510 /** 1511 * Add submenu page to the Plugins main menu. 1512 * 1513 * This function takes a capability which will be used to determine whether 1514 * or not a page is included in the menu. 1515 * 1516 * The function which is hooked in to handle the output of the page must check 1517 * that the user has the required capability as well. 1518 * 1519 * @since 3.0.0 1520 * @since 5.3.0 Added the `$position` parameter. 1521 * 1522 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1523 * @param string $menu_title The text to be used for the menu. 1524 * @param string $capability The capability required for this menu to be displayed to the user. 1525 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1526 * @param callable $function The function to be called to output the content for this page. 1527 * @param int $position The position in the menu order this item should appear. 1528 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1529 */ 1530 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1531 return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1532 } 1533 1534 /** 1535 * Add submenu page to the Users/Profile main menu. 1536 * 1537 * This function takes a capability which will be used to determine whether 1538 * or not a page is included in the menu. 1539 * 1540 * The function which is hooked in to handle the output of the page must check 1541 * that the user has the required capability as well. 1542 * 1543 * @since 2.1.3 1544 * @since 5.3.0 Added the `$position` parameter. 1545 * 1546 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1547 * @param string $menu_title The text to be used for the menu. 1548 * @param string $capability The capability required for this menu to be displayed to the user. 1549 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1550 * @param callable $function The function to be called to output the content for this page. 1551 * @param int $position The position in the menu order this item should appear. 1552 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1553 */ 1554 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1555 if ( current_user_can( 'edit_users' ) ) { 1556 $parent = 'users.php'; 1557 } else { 1558 $parent = 'profile.php'; 1559 } 1560 return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1561 } 1562 1563 /** 1564 * Add submenu page to the Dashboard main menu. 1565 * 1566 * This function takes a capability which will be used to determine whether 1567 * or not a page is included in the menu. 1568 * 1569 * The function which is hooked in to handle the output of the page must check 1570 * that the user has the required capability as well. 1571 * 1572 * @since 2.7.0 1573 * @since 5.3.0 Added the `$position` parameter. 1574 * 1575 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1576 * @param string $menu_title The text to be used for the menu. 1577 * @param string $capability The capability required for this menu to be displayed to the user. 1578 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1579 * @param callable $function The function to be called to output the content for this page. 1580 * @param int $position The position in the menu order this item should appear. 1581 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1582 */ 1583 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1584 return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1585 } 1586 1587 /** 1588 * Add submenu page to the Posts main menu. 1589 * 1590 * This function takes a capability which will be used to determine whether 1591 * or not a page is included in the menu. 1592 * 1593 * The function which is hooked in to handle the output of the page must check 1594 * that the user has the required capability as well. 1595 * 1596 * @since 2.7.0 1597 * @since 5.3.0 Added the `$position` parameter. 1598 * 1599 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1600 * @param string $menu_title The text to be used for the menu. 1601 * @param string $capability The capability required for this menu to be displayed to the user. 1602 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1603 * @param callable $function The function to be called to output the content for this page. 1604 * @param int $position The position in the menu order this item should appear. 1605 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1606 */ 1607 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1608 return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1609 } 1610 1611 /** 1612 * Add submenu page to the Media main menu. 1613 * 1614 * This function takes a capability which will be used to determine whether 1615 * or not a page is included in the menu. 1616 * 1617 * The function which is hooked in to handle the output of the page must check 1618 * that the user has the required capability as well. 1619 * 1620 * @since 2.7.0 1621 * @since 5.3.0 Added the `$position` parameter. 1622 * 1623 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1624 * @param string $menu_title The text to be used for the menu. 1625 * @param string $capability The capability required for this menu to be displayed to the user. 1626 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1627 * @param callable $function The function to be called to output the content for this page. 1628 * @param int $position The position in the menu order this item should appear. 1629 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1630 */ 1631 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1632 return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1633 } 1634 1635 /** 1636 * Add submenu page to the Links main menu. 1637 * 1638 * This function takes a capability which will be used to determine whether 1639 * or not a page is included in the menu. 1640 * 1641 * The function which is hooked in to handle the output of the page must check 1642 * that the user has the required capability as well. 1643 * 1644 * @since 2.7.0 1645 * @since 5.3.0 Added the `$position` parameter. 1646 * 1647 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1648 * @param string $menu_title The text to be used for the menu. 1649 * @param string $capability The capability required for this menu to be displayed to the user. 1650 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1651 * @param callable $function The function to be called to output the content for this page. 1652 * @param int $position The position in the menu order this item should appear. 1653 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1654 */ 1655 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1656 return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1657 } 1658 1659 /** 1660 * Add submenu page to the Pages main menu. 1661 * 1662 * This function takes a capability which will be used to determine whether 1663 * or not a page is included in the menu. 1664 * 1665 * The function which is hooked in to handle the output of the page must check 1666 * that the user has the required capability as well. 1667 * 1668 * @since 2.7.0 1669 * @since 5.3.0 Added the `$position` parameter. 1670 * 1671 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1672 * @param string $menu_title The text to be used for the menu. 1673 * @param string $capability The capability required for this menu to be displayed to the user. 1674 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1675 * @param callable $function The function to be called to output the content for this page. 1676 * @param int $position The position in the menu order this item should appear. 1677 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1678 */ 1679 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1680 return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1681 } 1682 1683 /** 1684 * Add submenu page to the Comments main menu. 1685 * 1686 * This function takes a capability which will be used to determine whether 1687 * or not a page is included in the menu. 1688 * 1689 * The function which is hooked in to handle the output of the page must check 1690 * that the user has the required capability as well. 1691 * 1692 * @since 2.7.0 1693 * @since 5.3.0 Added the `$position` parameter. 1694 * 1695 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1696 * @param string $menu_title The text to be used for the menu. 1697 * @param string $capability The capability required for this menu to be displayed to the user. 1698 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1699 * @param callable $function The function to be called to output the content for this page. 1700 * @param int $position The position in the menu order this item should appear. 1701 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1702 */ 1703 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1704 return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1705 } 1706 1707 /** 1708 * Remove a top-level admin menu. 1709 * 1710 * @since 3.1.0 1711 * 1712 * @global array $menu 1713 * 1714 * @param string $menu_slug The slug of the menu. 1715 * @return array|bool The removed menu on success, false if not found. 1716 */ 1717 function remove_menu_page( $menu_slug ) { 1718 global $menu; 1719 1720 foreach ( $menu as $i => $item ) { 1721 if ( $menu_slug == $item[2] ) { 1722 unset( $menu[ $i ] ); 1723 return $item; 1724 } 1725 } 1726 1727 return false; 1728 } 1729 1730 /** 1731 * Remove an admin submenu. 1732 * 1733 * @since 3.1.0 1734 * 1735 * @global array $submenu 1736 * 1737 * @param string $menu_slug The slug for the parent menu. 1738 * @param string $submenu_slug The slug of the submenu. 1739 * @return array|bool The removed submenu on success, false if not found. 1740 */ 1741 function remove_submenu_page( $menu_slug, $submenu_slug ) { 1742 global $submenu; 1743 1744 if ( ! isset( $submenu[ $menu_slug ] ) ) { 1745 return false; 1746 } 1747 1748 foreach ( $submenu[ $menu_slug ] as $i => $item ) { 1749 if ( $submenu_slug == $item[2] ) { 1750 unset( $submenu[ $menu_slug ][ $i ] ); 1751 return $item; 1752 } 1753 } 1754 1755 return false; 1756 } 1757 1758 /** 1759 * Get the URL to access a particular menu page based on the slug it was registered with. 1760 * 1761 * If the slug hasn't been registered properly, no URL will be returned. 1762 * 1763 * @since 3.0.0 1764 * 1765 * @global array $_parent_pages 1766 * 1767 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1768 * @param bool $echo Whether or not to echo the URL. Default true. 1769 * @return string The menu page URL. 1770 */ 1771 function menu_page_url( $menu_slug, $echo = true ) { 1772 global $_parent_pages; 1773 1774 if ( isset( $_parent_pages[ $menu_slug ] ) ) { 1775 $parent_slug = $_parent_pages[ $menu_slug ]; 1776 if ( $parent_slug && ! isset( $_parent_pages[ $parent_slug ] ) ) { 1777 $url = admin_url( add_query_arg( 'page', $menu_slug, $parent_slug ) ); 1778 } else { 1779 $url = admin_url( 'admin.php?page=' . $menu_slug ); 1780 } 1781 } else { 1782 $url = ''; 1783 } 1784 1785 $url = esc_url( $url ); 1786 1787 if ( $echo ) { 1788 echo $url; 1789 } 1790 1791 return $url; 1792 } 1793 1794 // 1795 // Pluggable Menu Support -- Private 1796 // 1797 /** 1798 * @global string $parent_file 1799 * @global array $menu 1800 * @global array $submenu 1801 * @global string $pagenow 1802 * @global string $typenow 1803 * @global string $plugin_page 1804 * @global array $_wp_real_parent_file 1805 * @global array $_wp_menu_nopriv 1806 * @global array $_wp_submenu_nopriv 1807 * 1808 * @return string 1809 */ 1810 function get_admin_page_parent( $parent = '' ) { 1811 global $parent_file, $menu, $submenu, $pagenow, $typenow, 1812 $plugin_page, $_wp_real_parent_file, $_wp_menu_nopriv, $_wp_submenu_nopriv; 1813 1814 if ( ! empty( $parent ) && 'admin.php' != $parent ) { 1815 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1816 $parent = $_wp_real_parent_file[ $parent ]; 1817 } 1818 return $parent; 1819 } 1820 1821 if ( $pagenow == 'admin.php' && isset( $plugin_page ) ) { 1822 foreach ( (array) $menu as $parent_menu ) { 1823 if ( $parent_menu[2] == $plugin_page ) { 1824 $parent_file = $plugin_page; 1825 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1826 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1827 } 1828 return $parent_file; 1829 } 1830 } 1831 if ( isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 1832 $parent_file = $plugin_page; 1833 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1834 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1835 } 1836 return $parent_file; 1837 } 1838 } 1839 1840 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 1841 $parent_file = $pagenow; 1842 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1843 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1844 } 1845 return $parent_file; 1846 } 1847 1848 foreach ( array_keys( (array) $submenu ) as $parent ) { 1849 foreach ( $submenu[ $parent ] as $submenu_array ) { 1850 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1851 $parent = $_wp_real_parent_file[ $parent ]; 1852 } 1853 if ( ! empty( $typenow ) && ( $submenu_array[2] == "$pagenow?post_type=$typenow" ) ) { 1854 $parent_file = $parent; 1855 return $parent; 1856 } elseif ( $submenu_array[2] == $pagenow && empty( $typenow ) && ( empty( $parent_file ) || false === strpos( $parent_file, '?' ) ) ) { 1857 $parent_file = $parent; 1858 return $parent; 1859 } elseif ( isset( $plugin_page ) && ( $plugin_page == $submenu_array[2] ) ) { 1860 $parent_file = $parent; 1861 return $parent; 1862 } 1863 } 1864 } 1865 1866 if ( empty( $parent_file ) ) { 1867 $parent_file = ''; 1868 } 1869 return ''; 1870 } 1871 1872 /** 1873 * @global string $title 1874 * @global array $menu 1875 * @global array $submenu 1876 * @global string $pagenow 1877 * @global string $plugin_page 1878 * @global string $typenow 1879 * 1880 * @return string 1881 */ 1882 function get_admin_page_title() { 1883 global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow; 1884 1885 if ( ! empty( $title ) ) { 1886 return $title; 1887 } 1888 1889 $hook = get_plugin_page_hook( $plugin_page, $pagenow ); 1890 1891 $parent = get_admin_page_parent(); 1892 $parent1 = $parent; 1893 1894 if ( empty( $parent ) ) { 1895 foreach ( (array) $menu as $menu_array ) { 1896 if ( isset( $menu_array[3] ) ) { 1897 if ( $menu_array[2] == $pagenow ) { 1898 $title = $menu_array[3]; 1899 return $menu_array[3]; 1900 } elseif ( isset( $plugin_page ) && ( $plugin_page == $menu_array[2] ) && ( $hook == $menu_array[3] ) ) { 1901 $title = $menu_array[3]; 1902 return $menu_array[3]; 1903 } 1904 } else { 1905 $title = $menu_array[0]; 1906 return $title; 1907 } 1908 } 1909 } else { 1910 foreach ( array_keys( $submenu ) as $parent ) { 1911 foreach ( $submenu[ $parent ] as $submenu_array ) { 1912 if ( isset( $plugin_page ) && 1913 ( $plugin_page == $submenu_array[2] ) && 1914 ( 1915 ( $parent == $pagenow ) || 1916 ( $parent == $plugin_page ) || 1917 ( $plugin_page == $hook ) || 1918 ( $pagenow == 'admin.php' && $parent1 != $submenu_array[2] ) || 1919 ( ! empty( $typenow ) && $parent == $pagenow . '?post_type=' . $typenow ) 1920 ) 1921 ) { 1922 $title = $submenu_array[3]; 1923 return $submenu_array[3]; 1924 } 1925 1926 if ( $submenu_array[2] != $pagenow || isset( $_GET['page'] ) ) { // not the current page 1927 continue; 1928 } 1929 1930 if ( isset( $submenu_array[3] ) ) { 1931 $title = $submenu_array[3]; 1932 return $submenu_array[3]; 1933 } else { 1934 $title = $submenu_array[0]; 1935 return $title; 1936 } 1937 } 1938 } 1939 if ( empty( $title ) ) { 1940 foreach ( $menu as $menu_array ) { 1941 if ( isset( $plugin_page ) && 1942 ( $plugin_page == $menu_array[2] ) && 1943 ( $pagenow == 'admin.php' ) && 1944 ( $parent1 == $menu_array[2] ) ) { 1945 $title = $menu_array[3]; 1946 return $menu_array[3]; 1947 } 1948 } 1949 } 1950 } 1951 1952 return $title; 1953 } 1954 1955 /** 1956 * @since 2.3.0 1957 * 1958 * @param string $plugin_page The slug name of the plugin page. 1959 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1960 * WordPress admin page). 1961 * @return string|null Hook attached to the plugin page, null otherwise. 1962 */ 1963 function get_plugin_page_hook( $plugin_page, $parent_page ) { 1964 $hook = get_plugin_page_hookname( $plugin_page, $parent_page ); 1965 if ( has_action( $hook ) ) { 1966 return $hook; 1967 } else { 1968 return null; 1969 } 1970 } 1971 1972 /** 1973 * @global array $admin_page_hooks 1974 * 1975 * @param string $plugin_page The slug name of the plugin page. 1976 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1977 * WordPress admin page). 1978 * @return string Hook name for the plugin page. 1979 */ 1980 function get_plugin_page_hookname( $plugin_page, $parent_page ) { 1981 global $admin_page_hooks; 1982 1983 $parent = get_admin_page_parent( $parent_page ); 1984 1985 $page_type = 'admin'; 1986 if ( empty( $parent_page ) || 'admin.php' == $parent_page || isset( $admin_page_hooks[ $plugin_page ] ) ) { 1987 if ( isset( $admin_page_hooks[ $plugin_page ] ) ) { 1988 $page_type = 'toplevel'; 1989 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 1990 $page_type = $admin_page_hooks[ $parent ]; 1991 } 1992 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 1993 $page_type = $admin_page_hooks[ $parent ]; 1994 } 1995 1996 $plugin_name = preg_replace( '!\.php!', '', $plugin_page ); 1997 1998 return $page_type . '_page_' . $plugin_name; 1999 } 2000 2001 /** 2002 * @global string $pagenow 2003 * @global array $menu 2004 * @global array $submenu 2005 * @global array $_wp_menu_nopriv 2006 * @global array $_wp_submenu_nopriv 2007 * @global string $plugin_page 2008 * @global array $_registered_pages 2009 * 2010 * @return bool Whether the current user can access the current admin page. 2011 */ 2012 function user_can_access_admin_page() { 2013 global $pagenow, $menu, $submenu, $_wp_menu_nopriv, $_wp_submenu_nopriv, 2014 $plugin_page, $_registered_pages; 2015 2016 $parent = get_admin_page_parent(); 2017 2018 if ( ! isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $parent ][ $pagenow ] ) ) { 2019 return false; 2020 } 2021 2022 if ( isset( $plugin_page ) ) { 2023 if ( isset( $_wp_submenu_nopriv[ $parent ][ $plugin_page ] ) ) { 2024 return false; 2025 } 2026 2027 $hookname = get_plugin_page_hookname( $plugin_page, $parent ); 2028 2029 if ( ! isset( $_registered_pages[ $hookname ] ) ) { 2030 return false; 2031 } 2032 } 2033 2034 if ( empty( $parent ) ) { 2035 if ( isset( $_wp_menu_nopriv[ $pagenow ] ) ) { 2036 return false; 2037 } 2038 if ( isset( $_wp_submenu_nopriv[ $pagenow ][ $pagenow ] ) ) { 2039 return false; 2040 } 2041 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 2042 return false; 2043 } 2044 if ( isset( $plugin_page ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2045 return false; 2046 } 2047 foreach ( array_keys( $_wp_submenu_nopriv ) as $key ) { 2048 if ( isset( $_wp_submenu_nopriv[ $key ][ $pagenow ] ) ) { 2049 return false; 2050 } 2051 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $key ][ $plugin_page ] ) ) { 2052 return false; 2053 } 2054 } 2055 return true; 2056 } 2057 2058 if ( isset( $plugin_page ) && ( $plugin_page == $parent ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2059 return false; 2060 } 2061 2062 if ( isset( $submenu[ $parent ] ) ) { 2063 foreach ( $submenu[ $parent ] as $submenu_array ) { 2064 if ( isset( $plugin_page ) && ( $submenu_array[2] == $plugin_page ) ) { 2065 if ( current_user_can( $submenu_array[1] ) ) { 2066 return true; 2067 } else { 2068 return false; 2069 } 2070 } elseif ( $submenu_array[2] == $pagenow ) { 2071 if ( current_user_can( $submenu_array[1] ) ) { 2072 return true; 2073 } else { 2074 return false; 2075 } 2076 } 2077 } 2078 } 2079 2080 foreach ( $menu as $menu_array ) { 2081 if ( $menu_array[2] == $parent ) { 2082 if ( current_user_can( $menu_array[1] ) ) { 2083 return true; 2084 } else { 2085 return false; 2086 } 2087 } 2088 } 2089 2090 return true; 2091 } 2092 2093 /* Whitelist functions */ 2094 2095 /** 2096 * Refreshes the value of the options whitelist available via the 'whitelist_options' hook. 2097 * 2098 * See the {@see 'whitelist_options'} filter. 2099 * 2100 * @since 2.7.0 2101 * 2102 * @global array $new_whitelist_options 2103 * 2104 * @param array $options 2105 * @return array 2106 */ 2107 function option_update_filter( $options ) { 2108 global $new_whitelist_options; 2109 2110 if ( is_array( $new_whitelist_options ) ) { 2111 $options = add_option_whitelist( $new_whitelist_options, $options ); 2112 } 2113 2114 return $options; 2115 } 2116 2117 /** 2118 * Adds an array of options to the options whitelist. 2119 * 2120 * @since 2.7.0 2121 * 2122 * @global array $whitelist_options 2123 * 2124 * @param array $new_options 2125 * @param string|array $options 2126 * @return array 2127 */ 2128 function add_option_whitelist( $new_options, $options = '' ) { 2129 if ( $options == '' ) { 2130 global $whitelist_options; 2131 } else { 2132 $whitelist_options = $options; 2133 } 2134 2135 foreach ( $new_options as $page => $keys ) { 2136 foreach ( $keys as $key ) { 2137 if ( ! isset( $whitelist_options[ $page ] ) || ! is_array( $whitelist_options[ $page ] ) ) { 2138 $whitelist_options[ $page ] = array(); 2139 $whitelist_options[ $page ][] = $key; 2140 } else { 2141 $pos = array_search( $key, $whitelist_options[ $page ] ); 2142 if ( $pos === false ) { 2143 $whitelist_options[ $page ][] = $key; 2144 } 2145 } 2146 } 2147 } 2148 2149 return $whitelist_options; 2150 } 2151 2152 /** 2153 * Removes a list of options from the options whitelist. 2154 * 2155 * @since 2.7.0 2156 * 2157 * @global array $whitelist_options 2158 * 2159 * @param array $del_options 2160 * @param string|array $options 2161 * @return array 2162 */ 2163 function remove_option_whitelist( $del_options, $options = '' ) { 2164 if ( $options == '' ) { 2165 global $whitelist_options; 2166 } else { 2167 $whitelist_options = $options; 2168 } 2169 2170 foreach ( $del_options as $page => $keys ) { 2171 foreach ( $keys as $key ) { 2172 if ( isset( $whitelist_options[ $page ] ) && is_array( $whitelist_options[ $page ] ) ) { 2173 $pos = array_search( $key, $whitelist_options[ $page ] ); 2174 if ( $pos !== false ) { 2175 unset( $whitelist_options[ $page ][ $pos ] ); 2176 } 2177 } 2178 } 2179 } 2180 2181 return $whitelist_options; 2182 } 2183 2184 /** 2185 * Output nonce, action, and option_page fields for a settings page. 2186 * 2187 * @since 2.7.0 2188 * 2189 * @param string $option_group A settings group name. This should match the group name 2190 * used in register_setting(). 2191 */ 2192 function settings_fields( $option_group ) { 2193 echo "<input type='hidden' name='option_page' value='" . esc_attr( $option_group ) . "' />"; 2194 echo '<input type="hidden" name="action" value="update" />'; 2195 wp_nonce_field( "$option_group-options" ); 2196 } 2197 2198 /** 2199 * Clears the plugins cache used by get_plugins() and by default, the plugin updates cache. 2200 * 2201 * @since 3.7.0 2202 * 2203 * @param bool $clear_update_cache Whether to clear the plugin updates cache. Default true. 2204 */ 2205 function wp_clean_plugins_cache( $clear_update_cache = true ) { 2206 if ( $clear_update_cache ) { 2207 delete_site_transient( 'update_plugins' ); 2208 } 2209 wp_cache_delete( 'plugins', 'plugins' ); 2210 } 2211 2212 /** 2213 * Load a given plugin attempt to generate errors. 2214 * 2215 * @since 3.0.0 2216 * @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file. 2217 * 2218 * @param string $plugin Path to the plugin file relative to the plugins directory. 2219 */ 2220 function plugin_sandbox_scrape( $plugin ) { 2221 if ( ! defined( 'WP_SANDBOX_SCRAPING' ) ) { 2222 define( 'WP_SANDBOX_SCRAPING', true ); 2223 } 2224 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin ); 2225 include( WP_PLUGIN_DIR . '/' . $plugin ); 2226 } 2227 2228 /** 2229 * Helper function for adding content to the Privacy Policy Guide. 2230 * 2231 * Plugins and themes should suggest text for inclusion in the site's privacy policy. 2232 * The suggested text should contain information about any functionality that affects user privacy, 2233 * and will be shown on the Privacy Policy Guide screen. 2234 * 2235 * A plugin or theme can use this function multiple times as long as it will help to better present 2236 * the suggested policy content. For example modular plugins such as WooCommerse or Jetpack 2237 * can add or remove suggested content depending on the modules/extensions that are enabled. 2238 * For more information see the Plugin Handbook: 2239 * https://developer.wordpress.org/plugins/privacy/suggesting-text-for-the-site-privacy-policy/. 2240 * 2241 * Intended for use with the `'admin_init'` action. 2242 * 2243 * @since 4.9.6 2244 * 2245 * @param string $plugin_name The name of the plugin or theme that is suggesting content 2246 * for the site's privacy policy. 2247 * @param string $policy_text The suggested content for inclusion in the policy. 2248 */ 2249 function wp_add_privacy_policy_content( $plugin_name, $policy_text ) { 2250 if ( ! is_admin() ) { 2251 _doing_it_wrong( 2252 __FUNCTION__, 2253 sprintf( 2254 /* translators: %s: admin_init */ 2255 __( 'The suggested privacy policy content should be added only in wp-admin by using the %s (or later) action.' ), 2256 '<code>admin_init</code>' 2257 ), 2258 '4.9.7' 2259 ); 2260 return; 2261 } elseif ( ! doing_action( 'admin_init' ) && ! did_action( 'admin_init' ) ) { 2262 _doing_it_wrong( 2263 __FUNCTION__, 2264 sprintf( 2265 /* translators: %s: admin_init */ 2266 __( 'The suggested privacy policy content should be added by using the %s (or later) action. Please see the inline documentation.' ), 2267 '<code>admin_init</code>' 2268 ), 2269 '4.9.7' 2270 ); 2271 return; 2272 } 2273 2274 if ( ! class_exists( 'WP_Privacy_Policy_Content' ) ) { 2275 require_once( ABSPATH . 'wp-admin/includes/class-wp-privacy-policy-content.php' ); 2276 } 2277 2278 WP_Privacy_Policy_Content::add( $plugin_name, $policy_text ); 2279 } 2280 2281 /** 2282 * Determines whether a plugin is technically active but was paused while 2283 * loading. 2284 * 2285 * For more information on this and similar theme functions, check out 2286 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 2287 * Conditional Tags} article in the Theme Developer Handbook. 2288 * 2289 * @since 5.2.0 2290 * 2291 * @param string $plugin Path to the plugin file relative to the plugins directory. 2292 * @return bool True, if in the list of paused plugins. False, if not in the list. 2293 */ 2294 function is_plugin_paused( $plugin ) { 2295 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2296 return false; 2297 } 2298 2299 if ( ! is_plugin_active( $plugin ) ) { 2300 return false; 2301 } 2302 2303 list( $plugin ) = explode( '/', $plugin ); 2304 2305 return array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ); 2306 } 2307 2308 /** 2309 * Gets the error that was recorded for a paused plugin. 2310 * 2311 * @since 5.2.0 2312 * 2313 * @param string $plugin Path to the plugin file relative to the plugins directory. 2314 * @return array|false Array of error information as returned by `error_get_last()`, 2315 * or false if none was recorded. 2316 */ 2317 function wp_get_plugin_error( $plugin ) { 2318 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2319 return false; 2320 } 2321 2322 list( $plugin ) = explode( '/', $plugin ); 2323 2324 if ( ! array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ) ) { 2325 return false; 2326 } 2327 2328 return $GLOBALS['_paused_plugins'][ $plugin ]; 2329 } 2330 2331 /** 2332 * Tries to resume a single plugin. 2333 * 2334 * If a redirect was provided, we first ensure the plugin does not throw fatal 2335 * errors anymore. 2336 * 2337 * The way it works is by setting the redirection to the error before trying to 2338 * include the plugin file. If the plugin fails, then the redirection will not 2339 * be overwritten with the success message and the plugin will not be resumed. 2340 * 2341 * @since 5.2.0 2342 * 2343 * @param string $plugin Single plugin to resume. 2344 * @param string $redirect Optional. URL to redirect to. Default empty string. 2345 * @return bool|WP_Error True on success, false if `$plugin` was not paused, 2346 * `WP_Error` on failure. 2347 */ 2348 function resume_plugin( $plugin, $redirect = '' ) { 2349 /* 2350 * We'll override this later if the plugin could be resumed without 2351 * creating a fatal error. 2352 */ 2353 if ( ! empty( $redirect ) ) { 2354 wp_redirect( 2355 add_query_arg( 2356 '_error_nonce', 2357 wp_create_nonce( 'plugin-resume-error_' . $plugin ), 2358 $redirect 2359 ) 2360 ); 2361 2362 // Load the plugin to test whether it throws a fatal error. 2363 ob_start(); 2364 plugin_sandbox_scrape( $plugin ); 2365 ob_clean(); 2366 } 2367 2368 list( $extension ) = explode( '/', $plugin ); 2369 2370 $result = wp_paused_plugins()->delete( $extension ); 2371 2372 if ( ! $result ) { 2373 return new WP_Error( 2374 'could_not_resume_plugin', 2375 __( 'Could not resume the plugin.' ) 2376 ); 2377 } 2378 2379 return true; 2380 } 2381 2382 /** 2383 * Renders an admin notice in case some plugins have been paused due to errors. 2384 * 2385 * @since 5.2.0 2386 */ 2387 function paused_plugins_notice() { 2388 if ( 'plugins.php' === $GLOBALS['pagenow'] ) { 2389 return; 2390 } 2391 2392 if ( ! current_user_can( 'resume_plugins' ) ) { 2393 return; 2394 } 2395 2396 if ( ! isset( $GLOBALS['_paused_plugins'] ) || empty( $GLOBALS['_paused_plugins'] ) ) { 2397 return; 2398 } 2399 2400 printf( 2401 '<div class="notice notice-error"><p><strong>%s</strong><br>%s</p><p><a href="%s">%s</a></p></div>', 2402 __( 'One or more plugins failed to load properly.' ), 2403 __( 'You can find more details and make changes on the Plugins screen.' ), 2404 esc_url( admin_url( 'plugins.php?plugin_status=paused' ) ), 2405 __( 'Go to the Plugins screen' ) 2406 ); 2407 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Tue Nov 19 01:00:03 2019 | Cross-referenced by PHPXref 0.7.1 |