| [ 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 array List of files 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 Key is the plugin file path and the value is an array of the 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 Key is the mu-plugin file path and the value is an array of the mu-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 Key is the file path and the value is an array of the 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 WP_Error|null 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|array $plugins Single plugin or list of plugins to deactivate. 730 * @param bool $silent Prevent calling deactivation hooks. Default is false. 731 * @param mixed $network_wide Whether to deactivate the plugin for all sites in the network. 732 * A value of null (the default) will deactivate plugins for both the site and the network. 733 */ 734 function deactivate_plugins( $plugins, $silent = false, $network_wide = null ) { 735 if ( is_multisite() ) { 736 $network_current = get_site_option( 'active_sitewide_plugins', array() ); 737 } 738 $current = get_option( 'active_plugins', array() ); 739 $do_blog = false; 740 $do_network = false; 741 742 foreach ( (array) $plugins as $plugin ) { 743 $plugin = plugin_basename( trim( $plugin ) ); 744 if ( ! is_plugin_active( $plugin ) ) { 745 continue; 746 } 747 748 $network_deactivating = false !== $network_wide && is_plugin_active_for_network( $plugin ); 749 750 if ( ! $silent ) { 751 /** 752 * Fires before a plugin is deactivated. 753 * 754 * If a plugin is silently deactivated (such as during an update), 755 * this hook does not fire. 756 * 757 * @since 2.9.0 758 * 759 * @param string $plugin Path to the plugin file relative to the plugins directory. 760 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network 761 * or just the current site. Multisite only. Default is false. 762 */ 763 do_action( 'deactivate_plugin', $plugin, $network_deactivating ); 764 } 765 766 if ( false !== $network_wide ) { 767 if ( is_plugin_active_for_network( $plugin ) ) { 768 $do_network = true; 769 unset( $network_current[ $plugin ] ); 770 } elseif ( $network_wide ) { 771 continue; 772 } 773 } 774 775 if ( true !== $network_wide ) { 776 $key = array_search( $plugin, $current ); 777 if ( false !== $key ) { 778 $do_blog = true; 779 unset( $current[ $key ] ); 780 } 781 } 782 783 if ( $do_blog && wp_is_recovery_mode() ) { 784 list( $extension ) = explode( '/', $plugin ); 785 wp_paused_plugins()->delete( $extension ); 786 } 787 788 if ( ! $silent ) { 789 /** 790 * Fires as a specific plugin is being deactivated. 791 * 792 * This hook is the "deactivation" hook used internally by register_deactivation_hook(). 793 * The dynamic portion of the hook name, `$plugin`, refers to the plugin basename. 794 * 795 * If a plugin is silently deactivated (such as during an update), this hook does not fire. 796 * 797 * @since 2.0.0 798 * 799 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network 800 * or just the current site. Multisite only. Default is false. 801 */ 802 do_action( "deactivate_{$plugin}", $network_deactivating ); 803 804 /** 805 * Fires after a plugin is deactivated. 806 * 807 * If a plugin is silently deactivated (such as during an update), 808 * this hook does not fire. 809 * 810 * @since 2.9.0 811 * 812 * @param string $plugin Path to the plugin file relative to the plugins directory. 813 * @param bool $network_deactivating Whether the plugin is deactivated for all sites in the network. 814 * or just the current site. Multisite only. Default false. 815 */ 816 do_action( 'deactivated_plugin', $plugin, $network_deactivating ); 817 } 818 } 819 820 if ( $do_blog ) { 821 update_option( 'active_plugins', $current ); 822 } 823 if ( $do_network ) { 824 update_site_option( 'active_sitewide_plugins', $network_current ); 825 } 826 } 827 828 /** 829 * Activate multiple plugins. 830 * 831 * When WP_Error is returned, it does not mean that one of the plugins had 832 * errors. It means that one or more of the plugins file path was invalid. 833 * 834 * The execution will be halted as soon as one of the plugins has an error. 835 * 836 * @since 2.6.0 837 * 838 * @param string|array $plugins Single plugin or list of plugins to activate. 839 * @param string $redirect Redirect to page after successful activation. 840 * @param bool $network_wide Whether to enable the plugin for all sites in the network. 841 * @param bool $silent Prevent calling activation hooks. Default is false. 842 * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation. 843 */ 844 function activate_plugins( $plugins, $redirect = '', $network_wide = false, $silent = false ) { 845 if ( ! is_array( $plugins ) ) { 846 $plugins = array( $plugins ); 847 } 848 849 $errors = array(); 850 foreach ( $plugins as $plugin ) { 851 if ( ! empty( $redirect ) ) { 852 $redirect = add_query_arg( 'plugin', $plugin, $redirect ); 853 } 854 $result = activate_plugin( $plugin, $redirect, $network_wide, $silent ); 855 if ( is_wp_error( $result ) ) { 856 $errors[ $plugin ] = $result; 857 } 858 } 859 860 if ( ! empty( $errors ) ) { 861 return new WP_Error( 'plugins_invalid', __( 'One of the plugins is invalid.' ), $errors ); 862 } 863 864 return true; 865 } 866 867 /** 868 * Remove directory and files of a plugin for a list of plugins. 869 * 870 * @since 2.6.0 871 * 872 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass. 873 * 874 * @param string[] $plugins List of plugin paths to delete, relative to the plugins directory. 875 * @param string $deprecated Not used. 876 * @return bool|null|WP_Error True on success, false if `$plugins` is empty, `WP_Error` on failure. 877 * `null` if filesystem credentials are required to proceed. 878 */ 879 function delete_plugins( $plugins, $deprecated = '' ) { 880 global $wp_filesystem; 881 882 if ( empty( $plugins ) ) { 883 return false; 884 } 885 886 $checked = array(); 887 foreach ( $plugins as $plugin ) { 888 $checked[] = 'checked[]=' . $plugin; 889 } 890 891 $url = wp_nonce_url( 'plugins.php?action=delete-selected&verify-delete=1&' . implode( '&', $checked ), 'bulk-plugins' ); 892 893 ob_start(); 894 $credentials = request_filesystem_credentials( $url ); 895 $data = ob_get_clean(); 896 897 if ( false === $credentials ) { 898 if ( ! empty( $data ) ) { 899 include_once( ABSPATH . 'wp-admin/admin-header.php' ); 900 echo $data; 901 include( ABSPATH . 'wp-admin/admin-footer.php' ); 902 exit; 903 } 904 return; 905 } 906 907 if ( ! WP_Filesystem( $credentials ) ) { 908 ob_start(); 909 request_filesystem_credentials( $url, '', true ); // Failed to connect, Error and request again. 910 $data = ob_get_clean(); 911 912 if ( ! empty( $data ) ) { 913 include_once( ABSPATH . 'wp-admin/admin-header.php' ); 914 echo $data; 915 include( ABSPATH . 'wp-admin/admin-footer.php' ); 916 exit; 917 } 918 return; 919 } 920 921 if ( ! is_object( $wp_filesystem ) ) { 922 return new WP_Error( 'fs_unavailable', __( 'Could not access filesystem.' ) ); 923 } 924 925 if ( is_wp_error( $wp_filesystem->errors ) && $wp_filesystem->errors->has_errors() ) { 926 return new WP_Error( 'fs_error', __( 'Filesystem error.' ), $wp_filesystem->errors ); 927 } 928 929 // Get the base plugin folder. 930 $plugins_dir = $wp_filesystem->wp_plugins_dir(); 931 if ( empty( $plugins_dir ) ) { 932 return new WP_Error( 'fs_no_plugins_dir', __( 'Unable to locate WordPress plugin directory.' ) ); 933 } 934 935 $plugins_dir = trailingslashit( $plugins_dir ); 936 937 $plugin_translations = wp_get_installed_translations( 'plugins' ); 938 939 $errors = array(); 940 941 foreach ( $plugins as $plugin_file ) { 942 // Run Uninstall hook. 943 if ( is_uninstallable_plugin( $plugin_file ) ) { 944 uninstall_plugin( $plugin_file ); 945 } 946 947 /** 948 * Fires immediately before a plugin deletion attempt. 949 * 950 * @since 4.4.0 951 * 952 * @param string $plugin_file Path to the plugin file relative to the plugins directory. 953 */ 954 do_action( 'delete_plugin', $plugin_file ); 955 956 $this_plugin_dir = trailingslashit( dirname( $plugins_dir . $plugin_file ) ); 957 958 // If plugin is in its own directory, recursively delete the directory. 959 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 960 $deleted = $wp_filesystem->delete( $this_plugin_dir, true ); 961 } else { 962 $deleted = $wp_filesystem->delete( $plugins_dir . $plugin_file ); 963 } 964 965 /** 966 * Fires immediately after a plugin deletion attempt. 967 * 968 * @since 4.4.0 969 * 970 * @param string $plugin_file Path to the plugin file relative to the plugins directory. 971 * @param bool $deleted Whether the plugin deletion was successful. 972 */ 973 do_action( 'deleted_plugin', $plugin_file, $deleted ); 974 975 if ( ! $deleted ) { 976 $errors[] = $plugin_file; 977 continue; 978 } 979 980 // Remove language files, silently. 981 $plugin_slug = dirname( $plugin_file ); 982 if ( '.' !== $plugin_slug && ! empty( $plugin_translations[ $plugin_slug ] ) ) { 983 $translations = $plugin_translations[ $plugin_slug ]; 984 985 foreach ( $translations as $translation => $data ) { 986 $wp_filesystem->delete( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '.po' ); 987 $wp_filesystem->delete( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '.mo' ); 988 989 $json_translation_files = glob( WP_LANG_DIR . '/plugins/' . $plugin_slug . '-' . $translation . '-*.json' ); 990 if ( $json_translation_files ) { 991 array_map( array( $wp_filesystem, 'delete' ), $json_translation_files ); 992 } 993 } 994 } 995 } 996 997 // Remove deleted plugins from the plugin updates list. 998 $current = get_site_transient( 'update_plugins' ); 999 if ( $current ) { 1000 // Don't remove the plugins that weren't deleted. 1001 $deleted = array_diff( $plugins, $errors ); 1002 1003 foreach ( $deleted as $plugin_file ) { 1004 unset( $current->response[ $plugin_file ] ); 1005 } 1006 1007 set_site_transient( 'update_plugins', $current ); 1008 } 1009 1010 if ( ! empty( $errors ) ) { 1011 if ( 1 === count( $errors ) ) { 1012 /* translators: %s: Plugin filename. */ 1013 $message = __( 'Could not fully remove the plugin %s.' ); 1014 } else { 1015 /* translators: %s: Comma-separated list of plugin filenames. */ 1016 $message = __( 'Could not fully remove the plugins %s.' ); 1017 } 1018 1019 return new WP_Error( 'could_not_remove_plugin', sprintf( $message, implode( ', ', $errors ) ) ); 1020 } 1021 1022 return true; 1023 } 1024 1025 /** 1026 * Validate active plugins 1027 * 1028 * Validate all active plugins, deactivates invalid and 1029 * returns an array of deactivated ones. 1030 * 1031 * @since 2.5.0 1032 * @return array invalid plugins, plugin as key, error as value 1033 */ 1034 function validate_active_plugins() { 1035 $plugins = get_option( 'active_plugins', array() ); 1036 // Validate vartype: array. 1037 if ( ! is_array( $plugins ) ) { 1038 update_option( 'active_plugins', array() ); 1039 $plugins = array(); 1040 } 1041 1042 if ( is_multisite() && current_user_can( 'manage_network_plugins' ) ) { 1043 $network_plugins = (array) get_site_option( 'active_sitewide_plugins', array() ); 1044 $plugins = array_merge( $plugins, array_keys( $network_plugins ) ); 1045 } 1046 1047 if ( empty( $plugins ) ) { 1048 return array(); 1049 } 1050 1051 $invalid = array(); 1052 1053 // Invalid plugins get deactivated. 1054 foreach ( $plugins as $plugin ) { 1055 $result = validate_plugin( $plugin ); 1056 if ( is_wp_error( $result ) ) { 1057 $invalid[ $plugin ] = $result; 1058 deactivate_plugins( $plugin, true ); 1059 } 1060 } 1061 return $invalid; 1062 } 1063 1064 /** 1065 * Validate the plugin path. 1066 * 1067 * Checks that the main plugin file exists and is a valid plugin. See validate_file(). 1068 * 1069 * @since 2.5.0 1070 * 1071 * @param string $plugin Path to the plugin file relative to the plugins directory. 1072 * @return WP_Error|int 0 on success, WP_Error on failure. 1073 */ 1074 function validate_plugin( $plugin ) { 1075 if ( validate_file( $plugin ) ) { 1076 return new WP_Error( 'plugin_invalid', __( 'Invalid plugin path.' ) ); 1077 } 1078 if ( ! file_exists( WP_PLUGIN_DIR . '/' . $plugin ) ) { 1079 return new WP_Error( 'plugin_not_found', __( 'Plugin file does not exist.' ) ); 1080 } 1081 1082 $installed_plugins = get_plugins(); 1083 if ( ! isset( $installed_plugins[ $plugin ] ) ) { 1084 return new WP_Error( 'no_plugin_header', __( 'The plugin does not have a valid header.' ) ); 1085 } 1086 return 0; 1087 } 1088 1089 /** 1090 * Validate the plugin requirements for WP version and PHP version. 1091 * 1092 * @since 5.2.0 1093 * 1094 * @param string $plugin Path to the plugin file relative to the plugins directory. 1095 * @return true|WP_Error True if requirements are met, WP_Error on failure. 1096 */ 1097 function validate_plugin_requirements( $plugin ) { 1098 $readme_file = WP_PLUGIN_DIR . '/' . dirname( $plugin ) . '/readme.txt'; 1099 $plugin_data = array( 1100 'requires' => '', 1101 'requires_php' => '', 1102 ); 1103 1104 if ( file_exists( $readme_file ) ) { 1105 $plugin_data = get_file_data( 1106 $readme_file, 1107 array( 1108 'requires' => 'Requires at least', 1109 'requires_php' => 'Requires PHP', 1110 ), 1111 'plugin' 1112 ); 1113 } 1114 1115 $plugin_data = array_merge( $plugin_data, get_plugin_data( WP_PLUGIN_DIR . '/' . $plugin ) ); 1116 1117 // Check for headers in the plugin's PHP file, give precedence to the plugin headers. 1118 $plugin_data['requires'] = ! empty( $plugin_data['RequiresWP'] ) ? $plugin_data['RequiresWP'] : $plugin_data['requires']; 1119 $plugin_data['requires_php'] = ! empty( $plugin_data['RequiresPHP'] ) ? $plugin_data['RequiresPHP'] : $plugin_data['requires_php']; 1120 1121 $plugin_data['wp_compatible'] = is_wp_version_compatible( $plugin_data['requires'] ); 1122 $plugin_data['php_compatible'] = is_php_version_compatible( $plugin_data['requires_php'] ); 1123 1124 if ( ! $plugin_data['wp_compatible'] && ! $plugin_data['php_compatible'] ) { 1125 return new WP_Error( 1126 'plugin_wp_php_incompatible', 1127 sprintf( 1128 /* translators: %s: Plugin name. */ 1129 __( '<strong>Error:</strong> Current WordPress and PHP versions do not meet minimum requirements for %s.' ), 1130 $plugin_data['Name'] 1131 ) 1132 ); 1133 } elseif ( ! $plugin_data['php_compatible'] ) { 1134 return new WP_Error( 1135 'plugin_php_incompatible', 1136 sprintf( 1137 /* translators: %s: Plugin name. */ 1138 __( '<strong>Error:</strong> Current PHP version does not meet minimum requirements for %s.' ), 1139 $plugin_data['Name'] 1140 ) 1141 ); 1142 } elseif ( ! $plugin_data['wp_compatible'] ) { 1143 return new WP_Error( 1144 'plugin_wp_incompatible', 1145 sprintf( 1146 /* translators: %s: Plugin name. */ 1147 __( '<strong>Error:</strong> Current WordPress version does not meet minimum requirements for %s.' ), 1148 $plugin_data['Name'] 1149 ) 1150 ); 1151 } 1152 1153 return true; 1154 } 1155 1156 /** 1157 * Whether the plugin can be uninstalled. 1158 * 1159 * @since 2.7.0 1160 * 1161 * @param string $plugin Path to the plugin file relative to the plugins directory. 1162 * @return bool Whether plugin can be uninstalled. 1163 */ 1164 function is_uninstallable_plugin( $plugin ) { 1165 $file = plugin_basename( $plugin ); 1166 1167 $uninstallable_plugins = (array) get_option( 'uninstall_plugins' ); 1168 if ( isset( $uninstallable_plugins[ $file ] ) || file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) { 1169 return true; 1170 } 1171 1172 return false; 1173 } 1174 1175 /** 1176 * Uninstall a single plugin. 1177 * 1178 * Calls the uninstall hook, if it is available. 1179 * 1180 * @since 2.7.0 1181 * 1182 * @param string $plugin Path to the plugin file relative to the plugins directory. 1183 * @return true True if a plugin's uninstall.php file has been found and included. 1184 */ 1185 function uninstall_plugin( $plugin ) { 1186 $file = plugin_basename( $plugin ); 1187 1188 $uninstallable_plugins = (array) get_option( 'uninstall_plugins' ); 1189 1190 /** 1191 * Fires in uninstall_plugin() immediately before the plugin is uninstalled. 1192 * 1193 * @since 4.5.0 1194 * 1195 * @param string $plugin Path to the plugin file relative to the plugins directory. 1196 * @param array $uninstallable_plugins Uninstallable plugins. 1197 */ 1198 do_action( 'pre_uninstall_plugin', $plugin, $uninstallable_plugins ); 1199 1200 if ( file_exists( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ) ) { 1201 if ( isset( $uninstallable_plugins[ $file ] ) ) { 1202 unset( $uninstallable_plugins[ $file ] ); 1203 update_option( 'uninstall_plugins', $uninstallable_plugins ); 1204 } 1205 unset( $uninstallable_plugins ); 1206 1207 define( 'WP_UNINSTALL_PLUGIN', $file ); 1208 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file ); 1209 include( WP_PLUGIN_DIR . '/' . dirname( $file ) . '/uninstall.php' ); 1210 1211 return true; 1212 } 1213 1214 if ( isset( $uninstallable_plugins[ $file ] ) ) { 1215 $callable = $uninstallable_plugins[ $file ]; 1216 unset( $uninstallable_plugins[ $file ] ); 1217 update_option( 'uninstall_plugins', $uninstallable_plugins ); 1218 unset( $uninstallable_plugins ); 1219 1220 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $file ); 1221 include( WP_PLUGIN_DIR . '/' . $file ); 1222 1223 add_action( "uninstall_{$file}", $callable ); 1224 1225 /** 1226 * Fires in uninstall_plugin() once the plugin has been uninstalled. 1227 * 1228 * The action concatenates the 'uninstall_' prefix with the basename of the 1229 * plugin passed to uninstall_plugin() to create a dynamically-named action. 1230 * 1231 * @since 2.7.0 1232 */ 1233 do_action( "uninstall_{$file}" ); 1234 } 1235 } 1236 1237 // 1238 // Menu 1239 // 1240 1241 /** 1242 * Add a top-level menu page. 1243 * 1244 * This function takes a capability which will be used to determine whether 1245 * or not a page is included in the menu. 1246 * 1247 * The function which is hooked in to handle the output of the page must check 1248 * that the user has the required capability as well. 1249 * 1250 * @since 1.5.0 1251 * 1252 * @global array $menu 1253 * @global array $admin_page_hooks 1254 * @global array $_registered_pages 1255 * @global array $_parent_pages 1256 * 1257 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1258 * @param string $menu_title The text to be used for the menu. 1259 * @param string $capability The capability required for this menu to be displayed to the user. 1260 * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu page and only 1261 * include lowercase alphanumeric, dashes, and underscores characters to be compatible 1262 * with sanitize_key(). 1263 * @param callable $function The function to be called to output the content for this page. 1264 * @param string $icon_url The URL to the icon to be used for this menu. 1265 * * Pass a base64-encoded SVG using a data URI, which will be colored to match 1266 * the color scheme. This should begin with 'data:image/svg+xml;base64,'. 1267 * * Pass the name of a Dashicons helper class to use a font icon, 1268 * e.g. 'dashicons-chart-pie'. 1269 * * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS. 1270 * @param int $position The position in the menu order this item should appear. 1271 * @return string The resulting page's hook_suffix. 1272 */ 1273 function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) { 1274 global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages; 1275 1276 $menu_slug = plugin_basename( $menu_slug ); 1277 1278 $admin_page_hooks[ $menu_slug ] = sanitize_title( $menu_title ); 1279 1280 $hookname = get_plugin_page_hookname( $menu_slug, '' ); 1281 1282 if ( ! empty( $function ) && ! empty( $hookname ) && current_user_can( $capability ) ) { 1283 add_action( $hookname, $function ); 1284 } 1285 1286 if ( empty( $icon_url ) ) { 1287 $icon_url = 'dashicons-admin-generic'; 1288 $icon_class = 'menu-icon-generic '; 1289 } else { 1290 $icon_url = set_url_scheme( $icon_url ); 1291 $icon_class = ''; 1292 } 1293 1294 $new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url ); 1295 1296 if ( null === $position ) { 1297 $menu[] = $new_menu; 1298 } elseif ( isset( $menu[ "$position" ] ) ) { 1299 $position = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ), -5 ) * 0.00001; 1300 $menu[ "$position" ] = $new_menu; 1301 } else { 1302 $menu[ $position ] = $new_menu; 1303 } 1304 1305 $_registered_pages[ $hookname ] = true; 1306 1307 // No parent as top level 1308 $_parent_pages[ $menu_slug ] = false; 1309 1310 return $hookname; 1311 } 1312 1313 /** 1314 * Add a submenu page. 1315 * 1316 * This function takes a capability which will be used to determine whether 1317 * or not a page is included in the menu. 1318 * 1319 * The function which is hooked in to handle the output of the page must check 1320 * that the user has the required capability as well. 1321 * 1322 * @since 1.5.0 1323 * @since 5.3.0 Added the `$position` parameter. 1324 * 1325 * @global array $submenu 1326 * @global array $menu 1327 * @global array $_wp_real_parent_file 1328 * @global bool $_wp_submenu_nopriv 1329 * @global array $_registered_pages 1330 * @global array $_parent_pages 1331 * 1332 * @param string $parent_slug The slug name for the parent menu (or the file name of a standard 1333 * WordPress admin page). 1334 * @param string $page_title The text to be displayed in the title tags of the page when the menu 1335 * is selected. 1336 * @param string $menu_title The text to be used for the menu. 1337 * @param string $capability The capability required for this menu to be displayed to the user. 1338 * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu 1339 * and only include lowercase alphanumeric, dashes, and underscores characters 1340 * to be compatible with sanitize_key(). 1341 * @param callable $function The function to be called to output the content for this page. 1342 * @param int $position The position in the menu order this item should appear. 1343 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1344 */ 1345 function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1346 global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv, 1347 $_registered_pages, $_parent_pages; 1348 1349 $menu_slug = plugin_basename( $menu_slug ); 1350 $parent_slug = plugin_basename( $parent_slug ); 1351 1352 if ( isset( $_wp_real_parent_file[ $parent_slug ] ) ) { 1353 $parent_slug = $_wp_real_parent_file[ $parent_slug ]; 1354 } 1355 1356 if ( ! current_user_can( $capability ) ) { 1357 $_wp_submenu_nopriv[ $parent_slug ][ $menu_slug ] = true; 1358 return false; 1359 } 1360 1361 /* 1362 * If the parent doesn't already have a submenu, add a link to the parent 1363 * as the first item in the submenu. If the submenu file is the same as the 1364 * parent file someone is trying to link back to the parent manually. In 1365 * this case, don't automatically add a link back to avoid duplication. 1366 */ 1367 if ( ! isset( $submenu[ $parent_slug ] ) && $menu_slug != $parent_slug ) { 1368 foreach ( (array) $menu as $parent_menu ) { 1369 if ( $parent_menu[2] == $parent_slug && current_user_can( $parent_menu[1] ) ) { 1370 $submenu[ $parent_slug ][] = array_slice( $parent_menu, 0, 4 ); 1371 } 1372 } 1373 } 1374 1375 $new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title ); 1376 if ( null === $position ) { 1377 $submenu[ $parent_slug ][] = $new_sub_menu; 1378 } else { 1379 // If position is equal or higher than the number of items in the array, append the submenu. 1380 if ( $position >= count( $submenu[ $parent_slug ] ) ) { 1381 $submenu[ $parent_slug ][] = $new_sub_menu; 1382 } else { 1383 // Test for a negative position. 1384 $position = max( $position, 0 ); 1385 if ( 0 === $position ) { 1386 // For negative or `0` positions, prepend the submenu. 1387 array_unshift( $submenu[ $parent_slug ], $new_sub_menu ); 1388 } else { 1389 // Grab all of the items before the insertion point. 1390 $before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true ); 1391 // Grab all of the items after the insertion point. 1392 $after_items = array_slice( $submenu[ $parent_slug ], $position, null, true ); 1393 // Add the new item. 1394 $before_items[] = $new_sub_menu; 1395 // Merge the items. 1396 $submenu[ $parent_slug ] = array_merge( $before_items, $after_items ); 1397 } 1398 } 1399 } 1400 // Sort the parent array 1401 ksort( $submenu[ $parent_slug ] ); 1402 1403 $hookname = get_plugin_page_hookname( $menu_slug, $parent_slug ); 1404 if ( ! empty( $function ) && ! empty( $hookname ) ) { 1405 add_action( $hookname, $function ); 1406 } 1407 1408 $_registered_pages[ $hookname ] = true; 1409 1410 /* 1411 * Backward-compatibility for plugins using add_management_page(). 1412 * See wp-admin/admin.php for redirect from edit.php to tools.php. 1413 */ 1414 if ( 'tools.php' == $parent_slug ) { 1415 $_registered_pages[ get_plugin_page_hookname( $menu_slug, 'edit.php' ) ] = true; 1416 } 1417 1418 // No parent as top level. 1419 $_parent_pages[ $menu_slug ] = $parent_slug; 1420 1421 return $hookname; 1422 } 1423 1424 /** 1425 * Add submenu page to the Tools main menu. 1426 * 1427 * This function takes a capability which will be used to determine whether 1428 * or not a page is included in the menu. 1429 * 1430 * The function which is hooked in to handle the output of the page must check 1431 * that the user has the required capability as well. 1432 * 1433 * @since 1.5.0 1434 * @since 5.3.0 Added the `$position` parameter. 1435 * 1436 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1437 * @param string $menu_title The text to be used for the menu. 1438 * @param string $capability The capability required for this menu to be displayed to the user. 1439 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1440 * @param callable $function The function to be called to output the content for this page. 1441 * @param int $position The position in the menu order this item should appear. 1442 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1443 */ 1444 function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1445 return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1446 } 1447 1448 /** 1449 * Add submenu page to the Settings main menu. 1450 * 1451 * This function takes a capability which will be used to determine whether 1452 * or not a page is included in the menu. 1453 * 1454 * The function which is hooked in to handle the output of the page must check 1455 * that the user has the required capability as well. 1456 * 1457 * @since 1.5.0 1458 * @since 5.3.0 Added the `$position` parameter. 1459 * 1460 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1461 * @param string $menu_title The text to be used for the menu. 1462 * @param string $capability The capability required for this menu to be displayed to the user. 1463 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1464 * @param callable $function The function to be called to output the content for this page. 1465 * @param int $position The position in the menu order this item should appear. 1466 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1467 */ 1468 function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1469 return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1470 } 1471 1472 /** 1473 * Add submenu page to the Appearance main menu. 1474 * 1475 * This function takes a capability which will be used to determine whether 1476 * or not a page is included in the menu. 1477 * 1478 * The function which is hooked in to handle the output of the page must check 1479 * that the user has the required capability as well. 1480 * 1481 * @since 2.0.0 1482 * @since 5.3.0 Added the `$position` parameter. 1483 * 1484 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1485 * @param string $menu_title The text to be used for the menu. 1486 * @param string $capability The capability required for this menu to be displayed to the user. 1487 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1488 * @param callable $function The function to be called to output the content for this page. 1489 * @param int $position The position in the menu order this item should appear. 1490 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1491 */ 1492 function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1493 return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1494 } 1495 1496 /** 1497 * Add submenu page to the Plugins main menu. 1498 * 1499 * This function takes a capability which will be used to determine whether 1500 * or not a page is included in the menu. 1501 * 1502 * The function which is hooked in to handle the output of the page must check 1503 * that the user has the required capability as well. 1504 * 1505 * @since 3.0.0 1506 * @since 5.3.0 Added the `$position` parameter. 1507 * 1508 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1509 * @param string $menu_title The text to be used for the menu. 1510 * @param string $capability The capability required for this menu to be displayed to the user. 1511 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1512 * @param callable $function The function to be called to output the content for this page. 1513 * @param int $position The position in the menu order this item should appear. 1514 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1515 */ 1516 function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1517 return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1518 } 1519 1520 /** 1521 * Add submenu page to the Users/Profile main menu. 1522 * 1523 * This function takes a capability which will be used to determine whether 1524 * or not a page is included in the menu. 1525 * 1526 * The function which is hooked in to handle the output of the page must check 1527 * that the user has the required capability as well. 1528 * 1529 * @since 2.1.3 1530 * @since 5.3.0 Added the `$position` parameter. 1531 * 1532 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1533 * @param string $menu_title The text to be used for the menu. 1534 * @param string $capability The capability required for this menu to be displayed to the user. 1535 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1536 * @param callable $function The function to be called to output the content for this page. 1537 * @param int $position The position in the menu order this item should appear. 1538 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1539 */ 1540 1541 function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1542 if ( current_user_can( 'edit_users' ) ) { 1543 $parent = 'users.php'; 1544 } else { 1545 $parent = 'profile.php'; 1546 } 1547 return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1548 } 1549 /** 1550 * Add submenu page to the Dashboard main menu. 1551 * 1552 * This function takes a capability which will be used to determine whether 1553 * or not a page is included in the menu. 1554 * 1555 * The function which is hooked in to handle the output of the page must check 1556 * that the user has the required capability as well. 1557 * 1558 * @since 2.7.0 1559 * @since 5.3.0 Added the `$position` parameter. 1560 * 1561 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1562 * @param string $menu_title The text to be used for the menu. 1563 * @param string $capability The capability required for this menu to be displayed to the user. 1564 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1565 * @param callable $function The function to be called to output the content for this page. 1566 * @param int $position The position in the menu order this item should appear. 1567 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1568 */ 1569 function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1570 return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1571 } 1572 1573 /** 1574 * Add submenu page to the Posts main menu. 1575 * 1576 * This function takes a capability which will be used to determine whether 1577 * or not a page is included in the menu. 1578 * 1579 * The function which is hooked in to handle the output of the page must check 1580 * that the user has the required capability as well. 1581 * 1582 * @since 2.7.0 1583 * @since 5.3.0 Added the `$position` parameter. 1584 * 1585 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1586 * @param string $menu_title The text to be used for the menu. 1587 * @param string $capability The capability required for this menu to be displayed to the user. 1588 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1589 * @param callable $function The function to be called to output the content for this page. 1590 * @param int $position The position in the menu order this item should appear. 1591 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1592 */ 1593 function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1594 return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1595 } 1596 1597 /** 1598 * Add submenu page to the Media main menu. 1599 * 1600 * This function takes a capability which will be used to determine whether 1601 * or not a page is included in the menu. 1602 * 1603 * The function which is hooked in to handle the output of the page must check 1604 * that the user has the required capability as well. 1605 * 1606 * @since 2.7.0 1607 * @since 5.3.0 Added the `$position` parameter. 1608 * 1609 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1610 * @param string $menu_title The text to be used for the menu. 1611 * @param string $capability The capability required for this menu to be displayed to the user. 1612 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1613 * @param callable $function The function to be called to output the content for this page. 1614 * @param int $position The position in the menu order this item should appear. 1615 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1616 */ 1617 function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1618 return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1619 } 1620 1621 /** 1622 * Add submenu page to the Links main menu. 1623 * 1624 * This function takes a capability which will be used to determine whether 1625 * or not a page is included in the menu. 1626 * 1627 * The function which is hooked in to handle the output of the page must check 1628 * that the user has the required capability as well. 1629 * 1630 * @since 2.7.0 1631 * @since 5.3.0 Added the `$position` parameter. 1632 * 1633 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1634 * @param string $menu_title The text to be used for the menu. 1635 * @param string $capability The capability required for this menu to be displayed to the user. 1636 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1637 * @param callable $function The function to be called to output the content for this page. 1638 * @param int $position The position in the menu order this item should appear. 1639 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1640 */ 1641 function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1642 return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1643 } 1644 1645 /** 1646 * Add submenu page to the Pages main menu. 1647 * 1648 * This function takes a capability which will be used to determine whether 1649 * or not a page is included in the menu. 1650 * 1651 * The function which is hooked in to handle the output of the page must check 1652 * that the user has the required capability as well. 1653 * 1654 * @since 2.7.0 1655 * @since 5.3.0 Added the `$position` parameter. 1656 * 1657 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1658 * @param string $menu_title The text to be used for the menu. 1659 * @param string $capability The capability required for this menu to be displayed to the user. 1660 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1661 * @param callable $function The function to be called to output the content for this page. 1662 * @param int $position The position in the menu order this item should appear. 1663 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1664 */ 1665 function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1666 return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1667 } 1668 1669 /** 1670 * Add submenu page to the Comments main menu. 1671 * 1672 * This function takes a capability which will be used to determine whether 1673 * or not a page is included in the menu. 1674 * 1675 * The function which is hooked in to handle the output of the page must check 1676 * that the user has the required capability as well. 1677 * 1678 * @since 2.7.0 1679 * @since 5.3.0 Added the `$position` parameter. 1680 * 1681 * @param string $page_title The text to be displayed in the title tags of the page when the menu is selected. 1682 * @param string $menu_title The text to be used for the menu. 1683 * @param string $capability The capability required for this menu to be displayed to the user. 1684 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu). 1685 * @param callable $function The function to be called to output the content for this page. 1686 * @param int $position The position in the menu order this item should appear. 1687 * @return false|string The resulting page's hook_suffix, or false if the user does not have the capability required. 1688 */ 1689 function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) { 1690 return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position ); 1691 } 1692 1693 /** 1694 * Remove a top-level admin menu. 1695 * 1696 * @since 3.1.0 1697 * 1698 * @global array $menu 1699 * 1700 * @param string $menu_slug The slug of the menu. 1701 * @return array|bool The removed menu on success, false if not found. 1702 */ 1703 function remove_menu_page( $menu_slug ) { 1704 global $menu; 1705 1706 foreach ( $menu as $i => $item ) { 1707 if ( $menu_slug == $item[2] ) { 1708 unset( $menu[ $i ] ); 1709 return $item; 1710 } 1711 } 1712 1713 return false; 1714 } 1715 1716 /** 1717 * Remove an admin submenu. 1718 * 1719 * @since 3.1.0 1720 * 1721 * @global array $submenu 1722 * 1723 * @param string $menu_slug The slug for the parent menu. 1724 * @param string $submenu_slug The slug of the submenu. 1725 * @return array|bool The removed submenu on success, false if not found. 1726 */ 1727 function remove_submenu_page( $menu_slug, $submenu_slug ) { 1728 global $submenu; 1729 1730 if ( ! isset( $submenu[ $menu_slug ] ) ) { 1731 return false; 1732 } 1733 1734 foreach ( $submenu[ $menu_slug ] as $i => $item ) { 1735 if ( $submenu_slug == $item[2] ) { 1736 unset( $submenu[ $menu_slug ][ $i ] ); 1737 return $item; 1738 } 1739 } 1740 1741 return false; 1742 } 1743 1744 /** 1745 * Get the url to access a particular menu page based on the slug it was registered with. 1746 * 1747 * If the slug hasn't been registered properly no url will be returned 1748 * 1749 * @since 3.0.0 1750 * 1751 * @global array $_parent_pages 1752 * 1753 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu) 1754 * @param bool $echo Whether or not to echo the url - default is true 1755 * @return string the url 1756 */ 1757 function menu_page_url( $menu_slug, $echo = true ) { 1758 global $_parent_pages; 1759 1760 if ( isset( $_parent_pages[ $menu_slug ] ) ) { 1761 $parent_slug = $_parent_pages[ $menu_slug ]; 1762 if ( $parent_slug && ! isset( $_parent_pages[ $parent_slug ] ) ) { 1763 $url = admin_url( add_query_arg( 'page', $menu_slug, $parent_slug ) ); 1764 } else { 1765 $url = admin_url( 'admin.php?page=' . $menu_slug ); 1766 } 1767 } else { 1768 $url = ''; 1769 } 1770 1771 $url = esc_url( $url ); 1772 1773 if ( $echo ) { 1774 echo $url; 1775 } 1776 1777 return $url; 1778 } 1779 1780 // 1781 // Pluggable Menu Support -- Private 1782 // 1783 /** 1784 * @global string $parent_file 1785 * @global array $menu 1786 * @global array $submenu 1787 * @global string $pagenow 1788 * @global string $typenow 1789 * @global string $plugin_page 1790 * @global array $_wp_real_parent_file 1791 * @global array $_wp_menu_nopriv 1792 * @global array $_wp_submenu_nopriv 1793 * 1794 * @return string 1795 */ 1796 function get_admin_page_parent( $parent = '' ) { 1797 global $parent_file, $menu, $submenu, $pagenow, $typenow, 1798 $plugin_page, $_wp_real_parent_file, $_wp_menu_nopriv, $_wp_submenu_nopriv; 1799 1800 if ( ! empty( $parent ) && 'admin.php' != $parent ) { 1801 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1802 $parent = $_wp_real_parent_file[ $parent ]; 1803 } 1804 return $parent; 1805 } 1806 1807 if ( $pagenow == 'admin.php' && isset( $plugin_page ) ) { 1808 foreach ( (array) $menu as $parent_menu ) { 1809 if ( $parent_menu[2] == $plugin_page ) { 1810 $parent_file = $plugin_page; 1811 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1812 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1813 } 1814 return $parent_file; 1815 } 1816 } 1817 if ( isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 1818 $parent_file = $plugin_page; 1819 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1820 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1821 } 1822 return $parent_file; 1823 } 1824 } 1825 1826 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 1827 $parent_file = $pagenow; 1828 if ( isset( $_wp_real_parent_file[ $parent_file ] ) ) { 1829 $parent_file = $_wp_real_parent_file[ $parent_file ]; 1830 } 1831 return $parent_file; 1832 } 1833 1834 foreach ( array_keys( (array) $submenu ) as $parent ) { 1835 foreach ( $submenu[ $parent ] as $submenu_array ) { 1836 if ( isset( $_wp_real_parent_file[ $parent ] ) ) { 1837 $parent = $_wp_real_parent_file[ $parent ]; 1838 } 1839 if ( ! empty( $typenow ) && ( $submenu_array[2] == "$pagenow?post_type=$typenow" ) ) { 1840 $parent_file = $parent; 1841 return $parent; 1842 } elseif ( $submenu_array[2] == $pagenow && empty( $typenow ) && ( empty( $parent_file ) || false === strpos( $parent_file, '?' ) ) ) { 1843 $parent_file = $parent; 1844 return $parent; 1845 } elseif ( isset( $plugin_page ) && ( $plugin_page == $submenu_array[2] ) ) { 1846 $parent_file = $parent; 1847 return $parent; 1848 } 1849 } 1850 } 1851 1852 if ( empty( $parent_file ) ) { 1853 $parent_file = ''; 1854 } 1855 return ''; 1856 } 1857 1858 /** 1859 * @global string $title 1860 * @global array $menu 1861 * @global array $submenu 1862 * @global string $pagenow 1863 * @global string $plugin_page 1864 * @global string $typenow 1865 * 1866 * @return string 1867 */ 1868 function get_admin_page_title() { 1869 global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow; 1870 1871 if ( ! empty( $title ) ) { 1872 return $title; 1873 } 1874 1875 $hook = get_plugin_page_hook( $plugin_page, $pagenow ); 1876 1877 $parent = get_admin_page_parent(); 1878 $parent1 = $parent; 1879 1880 if ( empty( $parent ) ) { 1881 foreach ( (array) $menu as $menu_array ) { 1882 if ( isset( $menu_array[3] ) ) { 1883 if ( $menu_array[2] == $pagenow ) { 1884 $title = $menu_array[3]; 1885 return $menu_array[3]; 1886 } elseif ( isset( $plugin_page ) && ( $plugin_page == $menu_array[2] ) && ( $hook == $menu_array[3] ) ) { 1887 $title = $menu_array[3]; 1888 return $menu_array[3]; 1889 } 1890 } else { 1891 $title = $menu_array[0]; 1892 return $title; 1893 } 1894 } 1895 } else { 1896 foreach ( array_keys( $submenu ) as $parent ) { 1897 foreach ( $submenu[ $parent ] as $submenu_array ) { 1898 if ( isset( $plugin_page ) && 1899 ( $plugin_page == $submenu_array[2] ) && 1900 ( 1901 ( $parent == $pagenow ) || 1902 ( $parent == $plugin_page ) || 1903 ( $plugin_page == $hook ) || 1904 ( $pagenow == 'admin.php' && $parent1 != $submenu_array[2] ) || 1905 ( ! empty( $typenow ) && $parent == $pagenow . '?post_type=' . $typenow ) 1906 ) 1907 ) { 1908 $title = $submenu_array[3]; 1909 return $submenu_array[3]; 1910 } 1911 1912 if ( $submenu_array[2] != $pagenow || isset( $_GET['page'] ) ) { // not the current page 1913 continue; 1914 } 1915 1916 if ( isset( $submenu_array[3] ) ) { 1917 $title = $submenu_array[3]; 1918 return $submenu_array[3]; 1919 } else { 1920 $title = $submenu_array[0]; 1921 return $title; 1922 } 1923 } 1924 } 1925 if ( empty( $title ) ) { 1926 foreach ( $menu as $menu_array ) { 1927 if ( isset( $plugin_page ) && 1928 ( $plugin_page == $menu_array[2] ) && 1929 ( $pagenow == 'admin.php' ) && 1930 ( $parent1 == $menu_array[2] ) ) { 1931 $title = $menu_array[3]; 1932 return $menu_array[3]; 1933 } 1934 } 1935 } 1936 } 1937 1938 return $title; 1939 } 1940 1941 /** 1942 * @since 2.3.0 1943 * 1944 * @param string $plugin_page The slug name of the plugin page. 1945 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1946 * WordPress admin page). 1947 * @return string|null Hook attached to the plugin page, null otherwise. 1948 */ 1949 function get_plugin_page_hook( $plugin_page, $parent_page ) { 1950 $hook = get_plugin_page_hookname( $plugin_page, $parent_page ); 1951 if ( has_action( $hook ) ) { 1952 return $hook; 1953 } else { 1954 return null; 1955 } 1956 } 1957 1958 /** 1959 * @global array $admin_page_hooks 1960 * 1961 * @param string $plugin_page The slug name of the plugin page. 1962 * @param string $parent_page The slug name for the parent menu (or the file name of a standard 1963 * WordPress admin page). 1964 * @return string Hook name for the plugin page. 1965 */ 1966 function get_plugin_page_hookname( $plugin_page, $parent_page ) { 1967 global $admin_page_hooks; 1968 1969 $parent = get_admin_page_parent( $parent_page ); 1970 1971 $page_type = 'admin'; 1972 if ( empty( $parent_page ) || 'admin.php' == $parent_page || isset( $admin_page_hooks[ $plugin_page ] ) ) { 1973 if ( isset( $admin_page_hooks[ $plugin_page ] ) ) { 1974 $page_type = 'toplevel'; 1975 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 1976 $page_type = $admin_page_hooks[ $parent ]; 1977 } 1978 } elseif ( isset( $admin_page_hooks[ $parent ] ) ) { 1979 $page_type = $admin_page_hooks[ $parent ]; 1980 } 1981 1982 $plugin_name = preg_replace( '!\.php!', '', $plugin_page ); 1983 1984 return $page_type . '_page_' . $plugin_name; 1985 } 1986 1987 /** 1988 * @global string $pagenow 1989 * @global array $menu 1990 * @global array $submenu 1991 * @global array $_wp_menu_nopriv 1992 * @global array $_wp_submenu_nopriv 1993 * @global string $plugin_page 1994 * @global array $_registered_pages 1995 * 1996 * @return bool Whether the current user can access the current admin page. 1997 */ 1998 function user_can_access_admin_page() { 1999 global $pagenow, $menu, $submenu, $_wp_menu_nopriv, $_wp_submenu_nopriv, 2000 $plugin_page, $_registered_pages; 2001 2002 $parent = get_admin_page_parent(); 2003 2004 if ( ! isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $parent ][ $pagenow ] ) ) { 2005 return false; 2006 } 2007 2008 if ( isset( $plugin_page ) ) { 2009 if ( isset( $_wp_submenu_nopriv[ $parent ][ $plugin_page ] ) ) { 2010 return false; 2011 } 2012 2013 $hookname = get_plugin_page_hookname( $plugin_page, $parent ); 2014 2015 if ( ! isset( $_registered_pages[ $hookname ] ) ) { 2016 return false; 2017 } 2018 } 2019 2020 if ( empty( $parent ) ) { 2021 if ( isset( $_wp_menu_nopriv[ $pagenow ] ) ) { 2022 return false; 2023 } 2024 if ( isset( $_wp_submenu_nopriv[ $pagenow ][ $pagenow ] ) ) { 2025 return false; 2026 } 2027 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $pagenow ][ $plugin_page ] ) ) { 2028 return false; 2029 } 2030 if ( isset( $plugin_page ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2031 return false; 2032 } 2033 foreach ( array_keys( $_wp_submenu_nopriv ) as $key ) { 2034 if ( isset( $_wp_submenu_nopriv[ $key ][ $pagenow ] ) ) { 2035 return false; 2036 } 2037 if ( isset( $plugin_page ) && isset( $_wp_submenu_nopriv[ $key ][ $plugin_page ] ) ) { 2038 return false; 2039 } 2040 } 2041 return true; 2042 } 2043 2044 if ( isset( $plugin_page ) && ( $plugin_page == $parent ) && isset( $_wp_menu_nopriv[ $plugin_page ] ) ) { 2045 return false; 2046 } 2047 2048 if ( isset( $submenu[ $parent ] ) ) { 2049 foreach ( $submenu[ $parent ] as $submenu_array ) { 2050 if ( isset( $plugin_page ) && ( $submenu_array[2] == $plugin_page ) ) { 2051 if ( current_user_can( $submenu_array[1] ) ) { 2052 return true; 2053 } else { 2054 return false; 2055 } 2056 } elseif ( $submenu_array[2] == $pagenow ) { 2057 if ( current_user_can( $submenu_array[1] ) ) { 2058 return true; 2059 } else { 2060 return false; 2061 } 2062 } 2063 } 2064 } 2065 2066 foreach ( $menu as $menu_array ) { 2067 if ( $menu_array[2] == $parent ) { 2068 if ( current_user_can( $menu_array[1] ) ) { 2069 return true; 2070 } else { 2071 return false; 2072 } 2073 } 2074 } 2075 2076 return true; 2077 } 2078 2079 /* Whitelist functions */ 2080 2081 /** 2082 * Refreshes the value of the options whitelist available via the 'whitelist_options' hook. 2083 * 2084 * See the {@see 'whitelist_options'} filter. 2085 * 2086 * @since 2.7.0 2087 * 2088 * @global array $new_whitelist_options 2089 * 2090 * @param array $options 2091 * @return array 2092 */ 2093 function option_update_filter( $options ) { 2094 global $new_whitelist_options; 2095 2096 if ( is_array( $new_whitelist_options ) ) { 2097 $options = add_option_whitelist( $new_whitelist_options, $options ); 2098 } 2099 2100 return $options; 2101 } 2102 2103 /** 2104 * Adds an array of options to the options whitelist. 2105 * 2106 * @since 2.7.0 2107 * 2108 * @global array $whitelist_options 2109 * 2110 * @param array $new_options 2111 * @param string|array $options 2112 * @return array 2113 */ 2114 function add_option_whitelist( $new_options, $options = '' ) { 2115 if ( $options == '' ) { 2116 global $whitelist_options; 2117 } else { 2118 $whitelist_options = $options; 2119 } 2120 2121 foreach ( $new_options as $page => $keys ) { 2122 foreach ( $keys as $key ) { 2123 if ( ! isset( $whitelist_options[ $page ] ) || ! is_array( $whitelist_options[ $page ] ) ) { 2124 $whitelist_options[ $page ] = array(); 2125 $whitelist_options[ $page ][] = $key; 2126 } else { 2127 $pos = array_search( $key, $whitelist_options[ $page ] ); 2128 if ( $pos === false ) { 2129 $whitelist_options[ $page ][] = $key; 2130 } 2131 } 2132 } 2133 } 2134 2135 return $whitelist_options; 2136 } 2137 2138 /** 2139 * Removes a list of options from the options whitelist. 2140 * 2141 * @since 2.7.0 2142 * 2143 * @global array $whitelist_options 2144 * 2145 * @param array $del_options 2146 * @param string|array $options 2147 * @return array 2148 */ 2149 function remove_option_whitelist( $del_options, $options = '' ) { 2150 if ( $options == '' ) { 2151 global $whitelist_options; 2152 } else { 2153 $whitelist_options = $options; 2154 } 2155 2156 foreach ( $del_options as $page => $keys ) { 2157 foreach ( $keys as $key ) { 2158 if ( isset( $whitelist_options[ $page ] ) && is_array( $whitelist_options[ $page ] ) ) { 2159 $pos = array_search( $key, $whitelist_options[ $page ] ); 2160 if ( $pos !== false ) { 2161 unset( $whitelist_options[ $page ][ $pos ] ); 2162 } 2163 } 2164 } 2165 } 2166 2167 return $whitelist_options; 2168 } 2169 2170 /** 2171 * Output nonce, action, and option_page fields for a settings page. 2172 * 2173 * @since 2.7.0 2174 * 2175 * @param string $option_group A settings group name. This should match the group name used in register_setting(). 2176 */ 2177 function settings_fields( $option_group ) { 2178 echo "<input type='hidden' name='option_page' value='" . esc_attr( $option_group ) . "' />"; 2179 echo '<input type="hidden" name="action" value="update" />'; 2180 wp_nonce_field( "$option_group-options" ); 2181 } 2182 2183 /** 2184 * Clears the Plugins cache used by get_plugins() and by default, the Plugin Update cache. 2185 * 2186 * @since 3.7.0 2187 * 2188 * @param bool $clear_update_cache Whether to clear the Plugin updates cache 2189 */ 2190 function wp_clean_plugins_cache( $clear_update_cache = true ) { 2191 if ( $clear_update_cache ) { 2192 delete_site_transient( 'update_plugins' ); 2193 } 2194 wp_cache_delete( 'plugins', 'plugins' ); 2195 } 2196 2197 /** 2198 * Load a given plugin attempt to generate errors. 2199 * 2200 * @since 3.0.0 2201 * @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file. 2202 * 2203 * @param string $plugin Path to the plugin file relative to the plugins directory. 2204 */ 2205 function plugin_sandbox_scrape( $plugin ) { 2206 if ( ! defined( 'WP_SANDBOX_SCRAPING' ) ) { 2207 define( 'WP_SANDBOX_SCRAPING', true ); 2208 } 2209 wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin ); 2210 include( WP_PLUGIN_DIR . '/' . $plugin ); 2211 } 2212 2213 /** 2214 * Helper function for adding content to the Privacy Policy Guide. 2215 * 2216 * Plugins and themes should suggest text for inclusion in the site's privacy policy. 2217 * The suggested text should contain information about any functionality that affects user privacy, 2218 * and will be shown on the Privacy Policy Guide screen. 2219 * 2220 * A plugin or theme can use this function multiple times as long as it will help to better present 2221 * the suggested policy content. For example modular plugins such as WooCommerse or Jetpack 2222 * can add or remove suggested content depending on the modules/extensions that are enabled. 2223 * For more information see the Plugin Handbook: 2224 * https://developer.wordpress.org/plugins/privacy/suggesting-text-for-the-site-privacy-policy/. 2225 * 2226 * Intended for use with the `'admin_init'` action. 2227 * 2228 * @since 4.9.6 2229 * 2230 * @param string $plugin_name The name of the plugin or theme that is suggesting content for the site's privacy policy. 2231 * @param string $policy_text The suggested content for inclusion in the policy. 2232 */ 2233 function wp_add_privacy_policy_content( $plugin_name, $policy_text ) { 2234 if ( ! is_admin() ) { 2235 _doing_it_wrong( 2236 __FUNCTION__, 2237 sprintf( 2238 /* translators: %s: admin_init */ 2239 __( 'The suggested privacy policy content should be added only in wp-admin by using the %s (or later) action.' ), 2240 '<code>admin_init</code>' 2241 ), 2242 '4.9.7' 2243 ); 2244 return; 2245 } elseif ( ! doing_action( 'admin_init' ) && ! did_action( 'admin_init' ) ) { 2246 _doing_it_wrong( 2247 __FUNCTION__, 2248 sprintf( 2249 /* translators: %s: admin_init */ 2250 __( 'The suggested privacy policy content should be added by using the %s (or later) action. Please see the inline documentation.' ), 2251 '<code>admin_init</code>' 2252 ), 2253 '4.9.7' 2254 ); 2255 return; 2256 } 2257 2258 if ( ! class_exists( 'WP_Privacy_Policy_Content' ) ) { 2259 require_once( ABSPATH . 'wp-admin/includes/class-wp-privacy-policy-content.php' ); 2260 } 2261 2262 WP_Privacy_Policy_Content::add( $plugin_name, $policy_text ); 2263 } 2264 2265 /** 2266 * Determines whether a plugin is technically active but was paused while 2267 * loading. 2268 * 2269 * For more information on this and similar theme functions, check out 2270 * the {@link https://developer.wordpress.org/themes/basics/conditional-tags/ 2271 * Conditional Tags} article in the Theme Developer Handbook. 2272 * 2273 * @since 5.2.0 2274 * 2275 * @param string $plugin Path to the plugin file relative to the plugins directory. 2276 * @return bool True, if in the list of paused plugins. False, not in the list. 2277 */ 2278 function is_plugin_paused( $plugin ) { 2279 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2280 return false; 2281 } 2282 2283 if ( ! is_plugin_active( $plugin ) ) { 2284 return false; 2285 } 2286 2287 list( $plugin ) = explode( '/', $plugin ); 2288 2289 return array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ); 2290 } 2291 2292 /** 2293 * Gets the error that was recorded for a paused plugin. 2294 * 2295 * @since 5.2.0 2296 * 2297 * @param string $plugin Path to the plugin file relative to the plugins 2298 * directory. 2299 * @return array|false Array of error information as it was returned by 2300 * `error_get_last()`, or false if none was recorded. 2301 */ 2302 function wp_get_plugin_error( $plugin ) { 2303 if ( ! isset( $GLOBALS['_paused_plugins'] ) ) { 2304 return false; 2305 } 2306 2307 list( $plugin ) = explode( '/', $plugin ); 2308 2309 if ( ! array_key_exists( $plugin, $GLOBALS['_paused_plugins'] ) ) { 2310 return false; 2311 } 2312 2313 return $GLOBALS['_paused_plugins'][ $plugin ]; 2314 } 2315 2316 /** 2317 * Tries to resume a single plugin. 2318 * 2319 * If a redirect was provided, we first ensure the plugin does not throw fatal 2320 * errors anymore. 2321 * 2322 * The way it works is by setting the redirection to the error before trying to 2323 * include the plugin file. If the plugin fails, then the redirection will not 2324 * be overwritten with the success message and the plugin will not be resumed. 2325 * 2326 * @since 5.2.0 2327 * 2328 * @param string $plugin Single plugin to resume. 2329 * @param string $redirect Optional. URL to redirect to. Default empty string. 2330 * @return bool|WP_Error True on success, false if `$plugin` was not paused, 2331 * `WP_Error` on failure. 2332 */ 2333 function resume_plugin( $plugin, $redirect = '' ) { 2334 /* 2335 * We'll override this later if the plugin could be resumed without 2336 * creating a fatal error. 2337 */ 2338 if ( ! empty( $redirect ) ) { 2339 wp_redirect( 2340 add_query_arg( 2341 '_error_nonce', 2342 wp_create_nonce( 'plugin-resume-error_' . $plugin ), 2343 $redirect 2344 ) 2345 ); 2346 2347 // Load the plugin to test whether it throws a fatal error. 2348 ob_start(); 2349 plugin_sandbox_scrape( $plugin ); 2350 ob_clean(); 2351 } 2352 2353 list( $extension ) = explode( '/', $plugin ); 2354 2355 $result = wp_paused_plugins()->delete( $extension ); 2356 2357 if ( ! $result ) { 2358 return new WP_Error( 2359 'could_not_resume_plugin', 2360 __( 'Could not resume the plugin.' ) 2361 ); 2362 } 2363 2364 return true; 2365 } 2366 2367 /** 2368 * Renders an admin notice in case some plugins have been paused due to errors. 2369 * 2370 * @since 5.2.0 2371 */ 2372 function paused_plugins_notice() { 2373 if ( 'plugins.php' === $GLOBALS['pagenow'] ) { 2374 return; 2375 } 2376 2377 if ( ! current_user_can( 'resume_plugins' ) ) { 2378 return; 2379 } 2380 2381 if ( ! isset( $GLOBALS['_paused_plugins'] ) || empty( $GLOBALS['_paused_plugins'] ) ) { 2382 return; 2383 } 2384 2385 printf( 2386 '<div class="notice notice-error"><p><strong>%s</strong><br>%s</p><p><a href="%s">%s</a></p></div>', 2387 __( 'One or more plugins failed to load properly.' ), 2388 __( 'You can find more details and make changes on the Plugins screen.' ), 2389 esc_url( admin_url( 'plugins.php?plugin_status=paused' ) ), 2390 __( 'Go to the Plugins screen' ) 2391 ); 2392 }
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sat Sep 21 01:00:03 2019 | Cross-referenced by PHPXref 0.7.1 |