WordPress.org

Make WordPress Core

Ticket #7527: 7527.plugin.r8762.diff

File 7527.plugin.r8762.diff, 6.6 KB (added by santosj, 10 years ago)

Plugin.php inline documentation based off of r8762

  • plugin.php

     
    9696                                );
    9797}
    9898
     99/**
     100 * Check the plugins directory and retrieve all plugin files with plugin data.
     101 *
     102 * WordPress only supports plugin files in the base plugins directory
     103 * (wp-content/plugins) and in one directory above the plugins directory
     104 * (wp-content/plugins/my-plugin). The file it looks for has the plugin data and
     105 * must be found in those two locations. It is recommended that do keep your
     106 * plugin files in directories.
     107 *
     108 * The file with the plugin data is the file that will be included and therefore
     109 * needs to have the main execution for the plugin. This does not mean
     110 * everything must be contained in the file and it is recommended that the file
     111 * be split for maintainability. Keep everything in one file for extreme
     112 * optimization purposes.
     113 *
     114 * @since unknown
     115 *
     116 * @param string $plugin_folder Optional. Relative path to single plugin folder.
     117 * @return array Key is the plugin file path and the value is an array of the plugin data.
     118 */
    99119function get_plugins($plugin_folder = '') {
    100120
    101121        if ( ! $cache_plugins = wp_cache_get('plugins', 'plugins') )
     
    169189        return in_array($plugin, get_option('active_plugins'));
    170190}
    171191
     192/**
     193 * Attempts activation of plugin in a "sandbox" and redirects on success.
     194 *
     195 * A plugin that is already activated will not attempt to be activated again.
     196 *
     197 * The way it works is by setting the redirection to the error before trying to
     198 * include the plugin file. If the plugin fails, then the redirection will not
     199 * be overwritten with the success message. Also, the options will not be
     200 * updated and the activation hook will not be called on plugin error.
     201 *
     202 * It should be noted that in no way the below code will actually prevent errors
     203 * within the file. The code should not be used elsewhere to replicate the
     204 * "sandbox", which uses redirection to work.
     205 * {@source 13 1}
     206 *
     207 * If any errors are found or text is outputted, then it will be captured to
     208 * ensure that the success redirection will update the error redirection.
     209 *
     210 * @since unknown
     211 *
     212 * @param string $plugin Plugin path to main plugin file with plugin data.
     213 * @param string $redirect Optional. URL to redirect to.
     214 * @return WP_Error|null WP_Error on invalid file or null on success.
     215 */
    172216function activate_plugin($plugin, $redirect = '') {
    173                 $current = get_option('active_plugins');
    174                 $plugin = trim($plugin);
     217        $current = get_option('active_plugins');
     218        $plugin = trim($plugin);
    175219
    176                 $valid = validate_plugin($plugin);
    177                 if ( is_wp_error($valid) )
    178                         return $valid;
     220        $valid = validate_plugin($plugin);
     221        if ( is_wp_error($valid) )
     222                return $valid;
    179223
    180                 if ( !in_array($plugin, $current) ) {
    181                         if ( !empty($redirect) )
    182                                 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
    183                         ob_start();
    184                         @include(WP_PLUGIN_DIR . '/' . $plugin);
    185                         $current[] = $plugin;
    186                         sort($current);
    187                         update_option('active_plugins', $current);
    188                         do_action('activate_' . $plugin);
    189                         ob_end_clean();
    190                 }
     224        if ( !in_array($plugin, $current) ) {
     225                if ( !empty($redirect) )
     226                        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
     227                ob_start();
     228                @include(WP_PLUGIN_DIR . '/' . $plugin);
     229                $current[] = $plugin;
     230                sort($current);
     231                update_option('active_plugins', $current);
     232                do_action('activate_' . $plugin);
     233                ob_end_clean();
     234        }
    191235
    192                 return null;
     236        return null;
    193237}
    194238
     239/**
     240 * Deactivate a single plugin or multiple plugins.
     241 *
     242 * The deactivation hook is disabled by the plugin upgrader by using the $silent
     243 * parameter.
     244 *
     245 * @since unknown
     246 *
     247 * @param string|array $plugins Single plugin or list of plugins to deactivate.
     248 * @param bool $silent Optional, default is false. Prevent calling deactivate hook.
     249 */
    195250function deactivate_plugins($plugins, $silent= false) {
    196251        $current = get_option('active_plugins');
    197252
     
    209264        update_option('active_plugins', $current);
    210265}
    211266
     267/**
     268 * Activate multiple plugins.
     269 *
     270 * When WP_Error is returned, it does not mean that one of the plugins had
     271 * errors. It means that one or more of the plugins file path was invalid.
     272 *
     273 * The execution will be halted as soon as one of the plugins has an error.
     274 *
     275 * @since unknown
     276 *
     277 * @param string|array $plugins
     278 * @param string $redirect Redirect to page after successful activation.
     279 * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation.
     280 */
    212281function activate_plugins($plugins, $redirect = '') {
    213282        if ( !is_array($plugins) )
    214283                $plugins = array($plugins);
     
    228297        return true;
    229298}
    230299
     300/**
     301 * Remove directory and files of a plugin for a single or list of plugin(s).
     302 *
     303 * If the plugins parameter list is empty, false will be returned. True when
     304 * completed.
     305 *
     306 * @since unknown
     307 *
     308 * @param array $plugins List of plugin
     309 * @param string $redirect Redirect to page when complete.
     310 * @return mixed
     311 */
    231312function delete_plugins($plugins, $redirect = '' ) {
    232313        global $wp_filesystem;
    233314
     
    331412        return $invalid;
    332413}
    333414
     415/**
     416 * Validate the plugin path.
     417 *
     418 * Checks that the file exists and {@link validate_file() is valid file}.
     419 *
     420 * @since unknown
     421 *
     422 * @param string $plugin Plugin Path
     423 * @return WP_Error|int 0 on success, WP_Error on failure.
     424 */
    334425function validate_plugin($plugin) {
    335426        if ( validate_file($plugin) )
    336427                return new WP_Error('plugin_invalid', __('Invalid plugin path.'));
     
    343434/**
    344435 * Whether the plugin can be uninstalled.
    345436 *
    346  * @since 2.7
     437 * @since 2.7.0
    347438 *
    348439 * @param string $plugin Plugin path to check.
    349440 * @return bool Whether plugin can be uninstalled.
     
    363454 *
    364455 * Calls the uninstall hook, if it is available.
    365456 *
    366  * @since 2.7
     457 * @since 2.7.0
    367458 *
    368459 * @param string $plugin Relative plugin path from Plugin Directory.
    369460 */
     
    454545        return $hookname;
    455546}
    456547
     548/**
     549 * Add sub menu page to the management main menu.
     550 *
     551 * @param string $page_title
     552 * @param unknown_type $menu_title
     553 * @param unknown_type $access_level
     554 * @param unknown_type $file
     555 * @param unknown_type $function
     556 * @return unknown
     557 */
    457558function add_management_page( $page_title, $menu_title, $access_level, $file, $function = '' ) {
    458559        return add_submenu_page( 'edit.php', $page_title, $menu_title, $access_level, $file, $function );
    459560}