Docs for page plugin.php

/wp-admin/includes/plugin.php

Description

WordPress Plugin Administration API

Functions

activate_plugin (line 518)

Attempts activation of plugin in a "sandbox" and redirects on success.

A plugin that is already activated will not attempt to be activated again.

The way it works is by setting the redirection to the error before trying to include the plugin file. If the plugin fails, then the redirection will not be overwritten with the success message. Also, the options will not be updated and the activation hook will not be called on plugin error.

It should be noted that in no way the below code will actually prevent errors within the file. The code should not be used elsewhere to replicate the "sandbox", which uses redirection to work.

if ( is_wp_error($valid) )

If any errors are found or text is outputted, then it will be captured to ensure that the success redirection will update the error redirection.

return: WP_Error on invalid file or null on success.
since: 2.5.0

WP_Error|null activate_plugin (string $plugin, [string $redirect = ''], [bool $network_wide = false], [bool $silent = false])

string $plugin: Plugin path to main plugin file with plugin data.
string $redirect: Optional. URL to redirect to.
bool $network_wide: Whether to enable the plugin for all sites in the network or just the current site. Multisite only. Default is false.
bool $silent: Prevent calling activation hooks. Optional, default is false.

activate_plugins (line 641)

Activate multiple plugins.

When WP_Error is returned, it does not mean that one of the plugins had errors. It means that one or more of the plugins file path was invalid.

The execution will be halted as soon as one of the plugins has an error.

return: True when finished or WP_Error if there were errors during a plugin activation.
since: 2.6.0

bool|WP_Error activate_plugins (string|array $plugins, [string $redirect = ''], [bool $network_wide = false], [bool $silent = false])

string|array $plugins
string $redirect: Redirect to page after successful activation.
bool $network_wide: Whether to enable the plugin for all sites in the network.
bool $silent: Prevent calling activation hooks. Default is false.

add_comments_page (line 1275)

Add sub menu page to the comments main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_comments_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_dashboard_page (line 1170)

Add sub menu page to the Dashboard main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_dashboard_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_links_page (line 1233)

Add sub menu page to the links main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_links_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_management_page (line 1062)

Add sub menu page to the tools main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_management_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_media_page (line 1212)

Add sub menu page to the media main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_media_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_menu_page (line 893)

Add a top level menu page

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix

string add_menu_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''], [string $icon_url = ''], [int $position = null])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.
string $icon_url: The url to the icon to be used for this menu. Using 'none' would leave div.wp-menu-image empty so an icon can be added as background with CSS.
int $position: The position in the menu order this one should appear

add_object_page (line 946)

Add a top level menu page in the 'objects' section

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix

string add_object_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''], [string $icon_url = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.
string $icon_url: The url to the icon to be used for this menu

add_options_page (line 1083)

Add sub menu page to the options main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_options_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_option_whitelist (line 1702)

since: 2.7.0

unknown add_option_whitelist (unknown_type $new_options, [unknown_type $options = ''])

unknown_type $new_options
unknown_type $options

add_pages_page (line 1254)

Add sub menu page to the pages main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_pages_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_plugins_page (line 1125)

Add sub menu page to the plugins main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_plugins_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_posts_page (line 1191)

Add sub menu page to the posts main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_posts_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_submenu_page (line 998)

Add a sub menu page

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_submenu_page (string $parent_slug, string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $parent_slug: The slug name for the parent menu (or the file name of a standard WordPress admin page)
string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_theme_page (line 1104)

Add sub menu page to the themes main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_theme_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_users_page (line 1146)

Add sub menu page to the Users/Profile main menu.

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix, or false if the user does not have the capability required.

string|bool add_users_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.

add_utility_page (line 972)

Add a top level menu page in the 'utility' section

This function takes a capability which will be used to determine whether or not a page is included in the menu.

The function which is hooked in to handle the output of the page must check that the user has the required capability as well.

return: The resulting page's hook_suffix

string add_utility_page (string $page_title, string $menu_title, string $capability, string $menu_slug, [callback $function = ''], [string $icon_url = ''])

string $page_title: The text to be displayed in the title tags of the page when the menu is selected
string $menu_title: The text to be used for the menu
string $capability: The capability required for this menu to be displayed to the user.
string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
callback $function: The function to be called to output the content for this page.
string $icon_url: The url to the icon to be used for this menu

deactivate_plugins (line 580)

Deactivate a single plugin or multiple plugins.

The deactivation hook is disabled by the plugin upgrader by using the $silent parameter.

since: 2.5.0

void deactivate_plugins (string|array $plugins, [bool $silent = false], [mixed $network_wide = null])

string|array $plugins: Single plugin or list of plugins to deactivate.
bool $silent: Prevent calling deactivation hooks. Default is false.
mixed $network_wide: Whether to deactivate the plugin for all sites in the network. A value of null (the default) will deactivate plugins for both the site and the network.

delete_plugins (line 672)

Remove directory and files of a plugin for a single or list of plugin(s).

If the plugins parameter list is empty, false will be returned. True when completed.

since: 2.6.0

mixed delete_plugins (array $plugins, [string $redirect = ''])

array $plugins: List of plugin
string $redirect: Redirect to page when complete.

get_admin_page_parent (line 1362)

void get_admin_page_parent ([ $parent = ''])

$parent

get_admin_page_title (line 1435)

void get_admin_page_title ()

get_dropins (line 361)

Check the wp-content directory and retrieve all drop-ins with any plugin data.

return: Key is the file path and the value is an array of the plugin data.
since: 3.0.0

array get_dropins ()

get_mu_plugins (line 304)

Check the mu-plugins directory and retrieve all mu-plugin files with any plugin data.

WordPress only includes mu-plugin files in the base mu-plugins directory (wp-content/mu-plugins).

return: Key is the mu-plugin file path and the value is an array of the mu-plugin data.
since: 3.0.0

array get_mu_plugins ()

get_plugins (line 234)

Check the plugins directory and retrieve all plugin files with plugin data.

WordPress only supports plugin files in the base plugins directory (wp-content/plugins) and in one directory above the plugins directory (wp-content/plugins/my-plugin). The file it looks for has the plugin data and must be found in those two locations. It is recommended that do keep your plugin files in directories.

The file with the plugin data is the file that will be included and therefore needs to have the main execution for the plugin. This does not mean everything must be contained in the file and it is recommended that the file be split for maintainability. Keep everything in one file for extreme optimization purposes.

return: Key is the plugin file path and the value is an array of the plugin data.
since: 1.5.0

array get_plugins ([string $plugin_folder = ''])

string $plugin_folder: Optional. Relative path to single plugin folder.

get_plugin_data (line 72)

Parse the plugin contents to retrieve plugin's metadata.

The metadata of the plugin's data searches for the following in the plugin's header. All plugin data must be on its own line. For plugin description, it must not have any newlines or only parts of the description will be displayed and the same goes for the plugin data. The below is formatted for printing.

/*
Plugin Name: Name of Plugin
Plugin URI: Link to plugin information
Description: Plugin Description
Author: Plugin author's name
Author URI: Link to the author's web site
Version: Must be set in the plugin for WordPress 2.3+
Text Domain: Optional. Unique identifier, should be same as the one used in
plugin_text_domain()
Domain Path: Optional. Only useful if the translations are located in a
folder above the plugin's base path. For example, if .mo files are
located in the locale folder then Domain Path will be "/locale/" and
must have the first slash. Defaults to the base folder the plugin is
located in.
Network: Optional. Specify "Network: true" to require that a plugin is activated
across all sites in an installation. This will prevent a plugin from being
activated on a single site when Multisite is enabled.
* / # Remove the space to close comment

Plugin data returned array contains the following: 'Name' - Name of the plugin, must be unique. 'Title' - Title of the plugin and the link to the plugin's web site. 'Description' - Description of what the plugin does and/or notes from the author. 'Author' - The author's name 'AuthorURI' - The authors web site address. 'Version' - The plugin version number. 'PluginURI' - Plugin web site address. 'TextDomain' - Plugin's text domain for localization. 'DomainPath' - Plugin's relative directory path to .mo files. 'Network' - Boolean. Whether the plugin can only be activated network wide.

Some users have issues with opening large files and manipulating the contents for want is usually the first 1kiB or 2kiB. This function stops pulling in the plugin contents when it has all of the required plugin data.

The first 8kiB of the file will be pulled in and if the plugin data is not within that first 8kiB, then the plugin author should correct their plugin and move the plugin data headers to the top.

The plugin file is assumed to have permissions to allow for scripts to read the file. This is not checked however and the file is only opened for reading.

return: See above for description.
link: http://trac.wordpress.org/ticket/5651 Previous Optimizations.
link: http://trac.wordpress.org/ticket/7372 Further and better Optimizations.
since: 1.5.0

array get_plugin_data (string $plugin_file, [bool $markup = true], [bool $translate = true])

string $plugin_file: Path to the plugin file
bool $markup: Optional. If the returned data should have HTML markup applied. Defaults to true.
bool $translate: Optional. If the returned data should be translated. Defaults to true.

get_plugin_files (line 182)

Get a list of a plugin's files.

return: List of files relative to the plugin root.
since: 2.8.0

array get_plugin_files (string $plugin)

string $plugin: Plugin ID

get_plugin_page_hook (line 1512)

void get_plugin_page_hook ( $plugin_page, $parent_page)

$plugin_page
$parent_page

get_plugin_page_hookname (line 1520)

void get_plugin_page_hookname ( $plugin_page, $parent_page)

$plugin_page
$parent_page

is_network_only_plugin (line 484)

Checks for "Network: true" in the plugin header to see if this should be activated only as a network wide plugin. The plugin would also work when Multisite is not enabled.

Checks for "Site Wide Only: true" for backwards compatibility.

return: True if plugin is network only, false otherwise.
since: 3.0.0

bool is_network_only_plugin (string $plugin)

string $plugin: Plugin to check

is_plugin_active (line 434)

Check whether the plugin is active by checking the active_plugins list.

return: True, if in the active plugins list. False, not in the list.
since: 2.5.0

bool is_plugin_active (string $plugin)

string $plugin: Base plugin path from plugins directory.

is_plugin_active_for_network (line 461)

Check whether the plugin is active for the entire network.

return: True, if active for the network, otherwise false.
since: 3.0.0

bool is_plugin_active_for_network (string $plugin)

string $plugin: Base plugin path from plugins directory.

is_plugin_inactive (line 449)

Check whether the plugin is inactive.

Reverse of is_plugin_active(). Used as a callback.

return: True if inactive. False if active.
see: is_plugin_active()
since: 3.1.0

bool is_plugin_inactive (string $plugin)

string $plugin: Base plugin path from plugins directory.

is_uninstallable_plugin (line 820)

Whether the plugin can be uninstalled.

return: Whether plugin can be uninstalled.
since: 2.7.0

bool is_uninstallable_plugin (string $plugin)

string $plugin: Plugin path to check.

menu_page_url (line 1336)

Get the url to access a particular menu page based on the slug it was registered with.

If the slug hasn't been registered properly no url will be returned

return: the url
since: 3.0

string menu_page_url (string $menu_slug, [bool $echo = true])

string $menu_slug: The slug name to refer to this menu by (should be unique for this menu)
bool $echo: Whether or not to echo the url - default is true

option_update_filter (line 1683)

since: 2.7.0

unknown option_update_filter (unknown_type $options)

unknown_type $options

register_setting (line 1627)

since: 2.7.0

unknown register_setting (string $option_group, string $option_name, [unknown_type $sanitize_callback = ''])

string $option_group: A settings group name. Should correspond to a whitelisted option key name. Default whitelisted option key names include "general," "discussion," and "reading," among others.
string $option_name: The name of an option to sanitize and save.
unknown_type $sanitize_callback: A callback function that sanitizes the option's value.

remove_menu_page (line 1287)

Remove a top level admin menu

return: The removed menu on success, False if not found
since: 3.1.0

array|bool remove_menu_page (string $menu_slug)

string $menu_slug: The slug of the menu

remove_option_whitelist (line 1733)

since: 2.7.0

unknown remove_option_whitelist (unknown_type $del_options, [unknown_type $options = ''])

unknown_type $del_options
unknown_type $options

remove_submenu_page (line 1309)

Remove an admin submenu

return: The removed submenu on success, False if not found
since: 3.1.0

array|bool remove_submenu_page (string $menu_slug, string $submenu_slug)

string $menu_slug: The slug for the parent menu
string $submenu_slug: The slug of the submenu

settings_fields (line 1759)

Output nonce, action, and option_page fields for a settings page.

since: 2.7.0

void settings_fields (string $option_group)

string $option_group: A settings group name. This should match the group name used in register_setting().

uninstall_plugin (line 839)

Uninstall a single plugin.

Calls the uninstall hook, if it is available.

since: 2.7.0

void uninstall_plugin (string $plugin)

string $plugin: Relative plugin path from Plugin Directory.

unregister_setting (line 1655)

Unregister a setting

since: 2.7.0

unknown unregister_setting (unknown_type $option_group, unknown_type $option_name, [unknown_type $sanitize_callback = ''])

unknown_type $option_group
unknown_type $option_name
unknown_type $sanitize_callback

user_can_access_admin_page (line 1541)

void user_can_access_admin_page ()

validate_active_plugins (line 761)

Validate active plugins

Validate all active plugins, deactivates invalid and returns an array of deactivated ones.

return: invalid plugins, plugin as key, error as value
since: 2.5.0

array validate_active_plugins ()

validate_plugin (line 800)

Validate the plugin path.

Checks that the file exists and is valid file.

return: 0 on success, WP_Error on failure.
since: 2.5.0

WP_Error|int validate_plugin (string $plugin)

string $plugin: Plugin Path

_get_dropins (line 406)

Returns drop-ins that WordPress uses.

Includes Multisite drop-ins only when is_multisite()

return: Key is file name. The value is an array, with the first value the purpose of the drop-in and the second value the name of the constant that must be true for the drop-in to be used, or true if no constant is required.
since: 3.0.0

array _get_dropins ()

Documentation generated on Tue, 18 Jun 2013 23:18:45 +0000 by phpDocumentor 1.4.1