WordPress.org

Make WordPress Core

Changeset 27673


Ignore:
Timestamp:
03/24/2014 02:59:36 AM (8 years ago)
Author:
DrewAPicture
Message:

Inline documentation for wp-admin/includes/class-wp-upgrader.php.

Props kpdesign for some minor cleanup.
Fixes #27436.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/class-wp-upgrader.php

    r27369 r27673  
    114114         * @since 3.7.0
    115115         *
    116          * @param bool    $reply   Whether to bail without returning the package. Default is false.
    117          * @param string  $package The package file name.
    118          * @param object  $this    The WP_Upgrader instance.
     116         * @param bool        $reply   Whether to bail without returning the package.
     117         *                             Default false.
     118         * @param string      $package The package file name.
     119         * @param WP_Upgrader $this    The WP_Upgrader instance.
    119120         */
    120121        $reply = apply_filters( 'upgrader_pre_download', false, $package, $this );
     
    199200        $this->skin->feedback('installing_package');
    200201
    201         $res = apply_filters('upgrader_pre_install', true, $hook_extra);
     202        /**
     203         * Filter the install response before the installation has started.
     204         *
     205         * Returning a truthy value, or one that could be evaluated as a WP_Error
     206         * will effectively short-circuit the installation, returning that value
     207         * instead.
     208         *
     209         * @since 2.8.0
     210         *
     211         * @param bool|WP_Error $response   Response.
     212         * @param array         $hook_extra Extra arguments passed to hooked filters.
     213         */
     214        $res = apply_filters( 'upgrader_pre_install', true, $hook_extra );
    202215        if ( is_wp_error($res) )
    203216            return $res;
     
    218231            $source = trailingslashit($source);
    219232
    220         //Hook ability to change the source file location..
    221         $source = apply_filters('upgrader_source_selection', $source, $remote_source, $this);
     233        /**
     234         * Filter the source file location for the upgrade package.
     235         *
     236         * @since 2.8.0
     237         *
     238         * @param string      $source        File source location.
     239         * @param string      $remote_source Remove file source location.
     240         * @param WP_Upgrader $this          WP_Upgrader instance.
     241         */
     242        $source = apply_filters( 'upgrader_source_selection', $source, $remote_source, $this );
    222243        if ( is_wp_error($source) )
    223244            return $source;
     
    244265            if ( $wp_filesystem->exists($remote_destination) )
    245266                $removed = $wp_filesystem->delete($remote_destination, true);
    246             $removed = apply_filters('upgrader_clear_destination', $removed, $local_destination, $remote_destination, $hook_extra);
     267
     268            /**
     269             * Filter whether the upgrader cleared the destination.
     270             *
     271             * @since 2.8.0
     272             *
     273             * @param bool   $removed            Whether the destination was cleared.
     274             * @param string $local_destination  The local package destination.
     275             * @param string $remote_destination The remote package destination.
     276             * @param array  $hook_extra         Extra arguments passed to hooked filters.
     277             */
     278            $removed = apply_filters( 'upgrader_clear_destination', $removed, $local_destination, $remote_destination, $hook_extra );
    247279
    248280            if ( is_wp_error($removed) )
     
    283315        $this->result = compact('local_source', 'source', 'source_name', 'source_files', 'destination', 'destination_name', 'local_destination', 'remote_destination', 'clear_destination', 'delete_source_dir');
    284316
    285         $res = apply_filters('upgrader_post_install', true, $hook_extra, $this->result);
     317        /**
     318         * Filter the install response after the installation has finished.
     319         *
     320         * @since 2.8.0
     321         *
     322         * @param bool  $response   Install response.
     323         * @param array $hook_extra Extra arguments passed to hooked filters.
     324         * @param array $result     Installation result data.
     325         */
     326        $res = apply_filters( 'upgrader_post_install', true, $hook_extra, $this->result );
     327
    286328        if ( is_wp_error($res) ) {
    287329            $this->result = $res;
     
    374416
    375417        if ( ! $is_multi ) {
     418
     419            /** This action is documented in wp-admin/includes/class-wp-upgrader.php */
    376420            do_action( 'upgrader_process_complete', $this, $hook_extra );
    377421            $this->skin->footer();
     
    594638        $this->maintenance_mode(false);
    595639
     640        /**
     641         * Fires when the bulk upgrader process is complete.
     642         *
     643         * @since 3.6.0
     644         *
     645         * @param Plugin_Upgrader $this Plugin_Upgrader instance. In other contexts, $this, might
     646         *                              be a Theme_Upgrader or Core_Upgrade instance.
     647         * @param array           $data {
     648         *     Array of bulk item update data.
     649         *
     650         *     @type string $action   Type of action. Default 'update'.
     651         *     @type string $type     Type of update process. Accepts 'plugin', 'theme', or 'core'.
     652         *     @type bool   $bulk     Whether the update process is a bulk update. Default true.
     653         *     @type array  $packages Array of plugin, theme, or core packages to update.
     654         * }
     655         */
    596656        do_action( 'upgrader_process_complete', $this, array(
    597657            'action' => 'update',
     
    9771037        $this->maintenance_mode(false);
    9781038
     1039        /** This action is documented in wp-admin/includes/class-wp-upgrader.php */
    9791040        do_action( 'upgrader_process_complete', $this, array(
    9801041            'action' => 'update',
     
    13471408            $partial = false;
    13481409
    1349         // If partial update is returned from the API, use that, unless we're doing a reinstall.
    1350         // If we cross the new_bundled version number, then use the new_bundled zip.
    1351         // Don't though if the constant is set to skip bundled items.
    1352         // If the API returns a no_content zip, go with it. Finally, default to the full zip.
     1410        /*
     1411         * If partial update is returned from the API, use that, unless we're doing
     1412         * a reinstall. If we cross the new_bundled version number, then use
     1413         * the new_bundled zip. Don't though if the constant is set to skip bundled items.
     1414         * If the API returns a no_content zip, go with it. Finally, default to the full zip.
     1415         */
    13531416        if ( $parsed_args['do_rollback'] && $current->packages->rollback )
    13541417            $to_download = 'rollback';
     
    14041467                /** This filter is documented in wp-admin/includes/update-core.php */
    14051468                apply_filters( 'update_feedback', $result );
     1469
    14061470                /** This filter is documented in wp-admin/includes/update-core.php */
    14071471                apply_filters( 'update_feedback', $this->strings['start_rollback'] );
     
    14141478        }
    14151479
     1480        /** This action is documented in wp-admin/includes/class-wp-upgrader.php */
    14161481        do_action( 'upgrader_process_complete', $this, array( 'action' => 'update', 'type' => 'core' ) );
    14171482
     
    15091574        // 3: 3.7-alpha-25000 -> 3.7-alpha-25678 -> 3.7-beta1 -> 3.7-beta2
    15101575        if ( $current_is_development_version ) {
     1576
     1577            /**
     1578             * Filter whether to enable automatic core updates for development versions.
     1579             *
     1580             * @since 3.7.0
     1581             *
     1582             * @param bool $upgrade_dev Whether to enable automatic updates for
     1583             *                          development versions.
     1584             */
    15111585            if ( ! apply_filters( 'allow_dev_auto_core_updates', $upgrade_dev ) )
    15121586                return false;
     
    15151589
    15161590        // 4: Minor In-branch updates (3.7.0 -> 3.7.1 -> 3.7.2 -> 3.7.4)
    1517         if ( $current_branch == $new_branch )
     1591        if ( $current_branch == $new_branch ) {
     1592
     1593            /**
     1594             * Filter whether to enable minor automatic core updates.
     1595             *
     1596             * @since 3.7.0
     1597             *
     1598             * @param bool $upgrade_minor Whether to enable minor automatic core updates.
     1599             */
    15181600            return apply_filters( 'allow_minor_auto_core_updates', $upgrade_minor );
     1601        }
    15191602
    15201603        // 5: Major version updates (3.7.0 -> 3.8.0 -> 3.9.1)
    1521         if ( version_compare( $new_branch, $current_branch, '>' ) )
     1604        if ( version_compare( $new_branch, $current_branch, '>' ) ) {
     1605
     1606            /**
     1607             * Filter whether to enable major automatic core updates.
     1608             *
     1609             * @since 3.7.0
     1610             *
     1611             * @param bool $upgrade_major Whether to enable major automatic core updates.
     1612             */
    15221613            return apply_filters( 'allow_major_auto_core_updates', $upgrade_major );
     1614        }
    15231615
    15241616        // If we're not sure, we don't want it
     
    16611753         *
    16621754         * @since 3.7.0
     1755         *
    16631756         * @param bool $disabled Whether the updater should be disabled.
    16641757         */
     
    17141807
    17151808        /**
    1716          * Filter whether the automatic updater should consider a filesystem location to be potentially
    1717          * managed by a version control system.
     1809         * Filter whether the automatic updater should consider a filesystem
     1810         * location to be potentially managed by a version control system.
    17181811         *
    17191812         * @since 3.7.0
    17201813         *
    1721          * @param bool $checkout  Whether a VCS checkout was discovered at $context or ABSPATH, or anywhere higher.
    1722          * @param string $context The filesystem context (a path) against which filesystem status should be checked.
     1814         * @param bool $checkout  Whether a VCS checkout was discovered at $context
     1815         *                        or ABSPATH, or anywhere higher.
     1816         * @param string $context The filesystem context (a path) against which
     1817         *                        filesystem status should be checked.
    17231818         */
    17241819        return apply_filters( 'automatic_updates_is_vcs_checkout', $checkout, $context );
     
    17301825     * @since 3.7.0
    17311826     *
    1732      * @param string $type    The type of update being checked: 'core', 'theme', 'plugin', 'translation'.
     1827     * @param string $type    The type of update being checked: 'core', 'theme',
     1828     *                        'plugin', 'translation'.
    17331829     * @param object $item    The update offer.
    1734      * @param string $context The filesystem context (a path) against which filesystem access and status
    1735      *                        should be checked.
     1830     * @param string $context The filesystem context (a path) against which filesystem
     1831     *                        access and status should be checked.
    17361832     */
    17371833    public function should_update( $type, $item, $context ) {
     
    17611857         * being checked. Can be 'core', 'theme', 'plugin', or 'translation'.
    17621858         *
    1763          * Generally speaking, plugins, themes, and major core versions are not updated by default,
    1764          * while translations and minor and development versions for core are updated by default.
    1765          *
    1766          * See the filters allow_dev_auto_core_updates, allow_minor_auto_core_updates, and
    1767          * allow_major_auto_core_updates more straightforward filters to adjust core updates.
     1859         * Generally speaking, plugins, themes, and major core versions are not updated
     1860         * by default, while translations and minor and development versions for core
     1861         * are updated by default.
     1862         *
     1863         * See the allow_dev_auto_core_updates, allow_minor_auto_core_updates, and
     1864         * allow_major_auto_core_updates filters for a more straightforward way to
     1865         * adjust core updates.
    17681866         *
    17691867         * @since 3.7.0
     
    18161914
    18171915        /**
    1818          * Whether to notify the site administrator of a new core update.
    1819          *
    1820          * By default, administrators are notified when the update offer received from WordPress.org
    1821          * sets a particular flag. This allows for discretion in if and when to notify.
    1822          *
    1823          * This filter only fires once per release -- if the same email address was already
    1824          * notified of the same new version, we won't repeatedly email the administrator.
    1825          *
    1826          * This filter is also used on about.php to check if a plugin has disabled these notifications.
     1916         * Filter whether to notify the site administrator of a new core update.
     1917         *
     1918         * By default, administrators are notified when the update offer received
     1919         * from WordPress.org sets a particular flag. This allows some discretion
     1920         * in if and when to notify.
     1921         *
     1922         * This filter is only evaluated once per release. If the same email address
     1923         * was already notified of the same new version, WordPress won't repeatedly
     1924         * email the administrator.
     1925         *
     1926         * This filter is also used on about.php to check if a plugin has disabled
     1927         * these notifications.
    18271928         *
    18281929         * @since 3.7.0
    18291930         *
    1830          * @param bool $notify Whether the site administrator is notified.
    1831          * @param object $item The update offer.
     1931         * @param bool   $notify Whether the site administrator is notified.
     1932         * @param object $item   The update offer.
    18321933         */
    18331934        if ( ! apply_filters( 'send_core_update_notification_email', $notify, $item ) )
     
    20212122        if ( ! empty( $this->update_results ) ) {
    20222123            $development_version = false !== strpos( $wp_version, '-' );
     2124
    20232125            /**
    20242126             * Filter whether to send a debugging email for each automatic background update.
    20252127             *
    20262128             * @since 3.7.0
    2027              * @param bool $development_version By default, emails are sent if the install is a development version.
     2129             *
     2130             * @param bool $development_version By default, emails are sent if the
     2131             *                                  install is a development version.
    20282132             *                                  Return false to avoid the email.
    20292133             */
     
    20352139
    20362140            /**
    2037              * Action triggered after all automatic updates have run.
    2038              *
    2039              * @since 3.8.0
    2040              *
    2041              * @param array $update_results The results of all attempted updates.
    2042              */
     2141             * Fires after all automatic updates have run.
     2142             *
     2143             * @since 3.8.0
     2144             *
     2145             * @param array $update_results The results of all attempted updates.
     2146             */
    20432147            do_action( 'automatic_updates_complete', $this->update_results );
    20442148        }
     
    21632267         *
    21642268         * @param bool   $send        Whether to send the email. Default true.
    2165          * @param string $type        The type of email to send. Can be one of 'success', 'fail', 'critical'.
     2269         * @param string $type        The type of email to send. Can be one of
     2270         *                            'success', 'fail', 'critical'.
    21662271         * @param object $core_update The update offer that was attempted.
    21672272         * @param mixed  $result      The result for the core update. Can be WP_Error.
     
    22942399
    22952400        $email = compact( 'to', 'subject', 'body', 'headers' );
     2401
    22962402        /**
    22972403         * Filter the email sent following an automatic background core update.
     
    23022408         *     Array of email arguments that will be passed to wp_mail().
    23032409         *
    2304          *     @type string $to      The email recipient. An array of emails can be returned, as handled by wp_mail().
     2410         *     @type string $to      The email recipient. An array of emails
     2411         *                            can be returned, as handled by wp_mail().
    23052412         *     @type string $subject The email's subject.
    23062413         *     @type string $body    The email message body.
    23072414         *     @type string $headers Any email headers, defaults to no headers.
    23082415         * }
    2309          * @param string $type        The type of email being sent. Can be one of 'success', 'fail', 'manual', 'critical'.
     2416         * @param string $type        The type of email being sent. Can be one of
     2417         *                            'success', 'fail', 'manual', 'critical'.
    23102418         * @param object $core_update The update offer that was attempted.
    23112419         * @param mixed  $result      The result for the core update. Can be WP_Error.
     
    24442552
    24452553        /**
    2446          * Filter the debug email that can be sent following an automatic background core update.
     2554         * Filter the debug email that can be sent following an automatic
     2555         * background core update.
    24472556         *
    24482557         * @since 3.8.0
     
    24512560         *     Array of email arguments that will be passed to wp_mail().
    24522561         *
    2453          *     @type string $to      The email recipient. An array of emails can be returned,
    2454          *                           as handled by wp_mail().
     2562         *     @type string $to      The email recipient. An array of emails
     2563         *                           can be returned, as handled by wp_mail().
    24552564         *     @type string $subject Email subject.
    24562565         *     @type string $body    Email message body.
Note: See TracChangeset for help on using the changeset viewer.