WordPress.org

Make WordPress Core

Ticket #7527: 7527.plugin.r8762.diff

File 7527.plugin.r8762.diff, 6.6 KB (added by santosj, 6 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}