Make WordPress Core

Changeset 25859


Ignore:
Timestamp:
10/21/2013 10:28:07 PM (10 years ago)
Author:
nacin
Message:

Rename the automatic_updates_send_email filter to auto_core_update_send_email. (Final name change.)

fixes #25653. Also:

  • Fully document all new hooks, methods, and classes in the upgrader.
  • Rename 'language' to 'translation' inside the upgrader.
  • Improve the readability of the crazy do-while loop in the is_vcs_checkout() method.
Location:
trunk/src/wp-admin/includes
Files:
2 edited

Legend:

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

    r25836 r25859  
    592592 */
    593593class Automatic_Upgrader_Skin extends WP_Upgrader_Skin {
    594     private $messages = array();
     594    protected $messages = array();
    595595
    596596    function request_filesystem_credentials( $error = false, $context = '' ) {
  • trunk/src/wp-admin/includes/class-wp-upgrader.php

    r25851 r25859  
    10981098
    10991099add_action( 'upgrader_process_complete', array( 'Language_Pack_Upgrader', 'async_upgrade' ), 20 );
     1100
     1101/**
     1102 * Language pack upgrader, for updating translations of plugins, themes, and core.
     1103 *
     1104 * @package WordPress
     1105 * @subpackage Upgrader
     1106 * @since 3.7.0
     1107 */
    11001108class Language_Pack_Upgrader extends WP_Upgrader {
    11011109
     
    15691577
    15701578/**
    1571  * WordPress automatic background updater.
     1579 * The WordPress automatic background updater.
    15721580 *
     1581 * @package WordPress
     1582 * @subpackage Upgrader
    15731583 * @since 3.7.0
    15741584 */
    15751585class WP_Automatic_Updater {
    15761586
     1587    /**
     1588     * Tracks update results during processing.
     1589     *
     1590     * @var array
     1591     */
    15771592    protected $update_results = array();
    15781593
    1579     function is_disabled() {
     1594    /**
     1595     * Whether the entire automatic updater is disabled.
     1596     *
     1597     * @since 3.7.0
     1598     */
     1599    public function is_disabled() {
    15801600        // Background updates are disabled if you don't want file changes.
    15811601        if ( defined( 'DISALLOW_FILE_MODS' ) && DISALLOW_FILE_MODS )
     
    15881608        $disabled = defined( 'AUTOMATIC_UPDATER_DISABLED' ) && AUTOMATIC_UPDATER_DISABLED;
    15891609
     1610        /**
     1611         * Filter whether to entirely disable background updates.
     1612         *
     1613         * There are more fine-grained filters and controls for selective disabling.
     1614         * This filter parallels the AUTOMATIC_UPDATER_DISABLED constant in name.
     1615         *
     1616         * @since 3.7.0
     1617         * @param bool $disabled Whether the updater should be disabled.
     1618         */
    15901619        return apply_filters( 'automatic_updater_disabled', $disabled );
    15911620    }
    15921621
    15931622    /**
    1594      * Check for GIT/SVN checkouts.
     1623     * Check for version control checkouts.
     1624     *
     1625     * Checks for Subversion, Git, Mercurial, and Bazaar. It recursively looks up the
     1626     * filesystem to the top of the drive, erring on the side of detecting a VCS
     1627     * checkout somewhere.
     1628     *
     1629     * ABSPATH is always checked in addition to whatever $context is (which may be the
     1630     * wp-content directory, for example). The underlying assumption is that if you are
     1631     * using version control *anywhere*, then you should be making decisions for
     1632     * how things get updated.
     1633     *
     1634     * @since 3.7.0
     1635     *
     1636     * @param string $context The filesystem path to check, in addition to ABSPATH.
    15951637     */
    1596     function is_vcs_checkout( $context ) {
     1638    public function is_vcs_checkout( $context ) {
    15971639        $context_dirs = array( untrailingslashit( $context ) );
    15981640        if ( $context !== ABSPATH )
     
    16061648            do {
    16071649                $check_dirs[] = $context_dir;
    1608             } while ( $context_dir != dirname( $context_dir ) && $context_dir = dirname( $context_dir ) );
     1650
     1651                // Once we've hit '/' or 'C:\', we need to stop. dirname will keep returning the input here.
     1652                if ( $context_dir == dirname( $context_dir ) )
     1653                    break;
     1654
     1655            // Continue one level at a time.
     1656            } while ( $context_dir = dirname( $context_dir ) );
    16091657        }
    16101658
     
    16181666            }
    16191667        }
     1668
     1669        /**
     1670         * Filter whether the automatic updater should consider a filesystem location to be potentially
     1671         * managed by a version control system.
     1672         *
     1673         * @since 3.7.0
     1674         *
     1675         * @param bool $checkout  Whether a VCS checkout was discovered at $context or ABSPATH, or anywhere higher.
     1676         * @param string $context The filesystem context (a path) against which filesystem status should be checked.
     1677         */
    16201678        return apply_filters( 'automatic_updates_is_vcs_checkout', $checkout, $context );
    16211679    }
     
    16231681    /**
    16241682     * Tests to see if we can and should update a specific item.
     1683     *
     1684     * @since 3.7.0
     1685     *
     1686     * @param string $type    The type of update being checked: 'core', 'theme', 'plugin', 'translation'.
     1687     * @param object $item    The update offer.
     1688     * @param string $context The filesystem context (a path) against which filesystem access and status
     1689     *                        should be checked.
    16251690     */
    1626     function should_update( $type, $item, $context ) {
     1691    public function should_update( $type, $item, $context ) {
    16271692        if ( $this->is_disabled() )
    16281693            return false;
     
    16421707            $update = ! empty( $item->autoupdate );
    16431708
    1644         // And does the user / plugins want it?
    1645         // Plugins may filter on 'auto_update_plugin', and check the 2nd param, $item, to only enable it for certain Plugins/Themes
     1709        /**
     1710         * Filter whether to automatically update core, a plugin, a theme, or a language.
     1711         *
     1712         * The dynamic portion of the hook name, $type, refers to the type of update
     1713         * being checked. Can be 'core', 'theme', 'plugin', or 'translation'.
     1714         *
     1715         * Generally speaking, plugins, themes, and major core versions are not updated by default,
     1716         * while translations and minor and development versions for core are updated by default.
     1717         *
     1718         * See the filters allow_dev_auto_core_updates, allow_minor_auto_core_updates, and
     1719         * allow_major_auto_core_updates more straightforward filters to adjust core updates.
     1720         *
     1721         * @since 3.7.0
     1722         *
     1723         * @param bool   $update Whether to update.
     1724         * @param object $item   The update offer.
     1725         */
    16461726        $update = apply_filters( 'auto_update_' . $type, $update, $item );
    16471727
     
    16801760    }
    16811761
    1682     function update( $type, $item ) {
    1683 
     1762    /**
     1763     * Update an item, if appropriate.
     1764     *
     1765     * @since 3.7.0
     1766     *
     1767     * @param string $type The type of update being checked: 'core', 'theme', 'plugin', 'translation'.
     1768     * @param object $item The update offer.
     1769     */
     1770    public function update( $type, $item ) {
    16841771        $skin = new Automatic_Upgrader_Skin;
    16851772
     
    16991786                $context  = get_theme_root( $item );
    17001787                break;
    1701             case 'language':
     1788            case 'translation':
    17021789                $upgrader = new Language_Pack_Upgrader( $skin );
    17031790                $context  = WP_CONTENT_DIR; // WP_LANG_DIR;
     
    17241811                $skin->feedback( __( 'Updating plugin: %s' ), $item_name );
    17251812                break;
    1726             case 'language':
     1813            case 'translation':
    17271814                $language_item_name = $upgrader->get_name_for_update( $item );
    17281815                $item_name = sprintf( __( 'Translations for %s' ), $language_item_name );
     
    17581845
    17591846    /**
    1760      * Kicks off a update request for each item in the update "queue".
     1847     * Kicks off the background update process, looping through all pending updates.
     1848     *
     1849     * @since 3.7.0
    17611850     */
    1762     function run() {
     1851    public function run() {
    17631852        global $wpdb, $wp_version;
    17641853
     
    18511940        if ( $language_updates ) {
    18521941            foreach ( $language_updates as $update ) {
    1853                 $this->update( 'language', $update );
     1942                $this->update( 'translation', $update );
    18541943            }
    18551944
     
    18671956        if ( ! empty( $this->update_results ) ) {
    18681957            $development_version = false !== strpos( $wp_version, '-' );
     1958            /**
     1959             * Filter whether to send a debugging email for each automatic background update.
     1960             *
     1961             * @since 3.7.0
     1962             * @param bool $development_version By default, emails are sent if the install is a development version.
     1963             *                                  Return false to avoid the email.
     1964             */
    18691965            if ( apply_filters( 'automatic_updates_send_debug_email', $development_version ) )
    18701966                $this->send_debug_email();
     
    18811977     * If we tried to perform a core update, check if we should send an email,
    18821978     * and if we need to avoid processing future updates.
     1979     *
     1980     * @param object $update_result The result of the core update. Includes the update offer and result.
    18831981     */
    18841982    protected function after_core_update( $update_result ) {
     
    19572055    }
    19582056
     2057    /**
     2058     * Sends an email upon the completion or failure of a background core update.
     2059     *
     2060     * @since 3.7.0
     2061     *
     2062     * @param string $type        The type of update being checked: 'core', 'theme', 'plugin', 'translation'.
     2063     * @param object $core_update The update offer that was attempted.
     2064     * @param mixed  $result      Optional. The result for the core update. Can be WP_Error.
     2065     */
    19592066    protected function send_email( $type, $core_update, $result = null ) {
    19602067        update_site_option( 'auto_core_update_notified', array(
     
    19652072        ) );
    19662073
    1967         if ( ! apply_filters( 'automatic_updates_send_email', true, $type, $core_update, $result ) )
     2074        /**
     2075         * Filter whether to send an email following an automatic background core update.
     2076         *
     2077         * @since 3.7.0
     2078         *
     2079         * @param bool   $send        Whether to send the email. Default true.
     2080         * @param string $type        The type of email to send. Can be one of 'success', 'fail', 'manual', 'critical'.
     2081         * @param object $core_update The update offer that was attempted.
     2082         * @param mixed  $result      The result for the core update. Can be WP_Error.
     2083         */
     2084        if ( ! apply_filters( 'auto_core_update_send_email', true, $type, $core_update, $result ) )
    19682085            return;
    19692086
     
    20562173        $headers = '';
    20572174
    2058         $email = compact( 'to', 'body', 'subject', 'headers' );
    2059         $email = apply_filters( 'automatic_update_send_email', $email, $type, $core_update, $result );
     2175        $email = compact( 'to', 'subject', 'body', 'headers' );
     2176        /**
     2177         * Filter the email sent following an automatic background core update.
     2178         *
     2179         * @since 3.7.0
     2180         *
     2181         * @param array $email {
     2182         *     Array of email arguments that will be passed to wp_mail().
     2183         *
     2184         *     @type string $to      The email recipient. An array of emails can be returned, as handled by wp_mail().
     2185         *     @type string $subject The email's subject.
     2186         *     @type string $body    The email message body.
     2187         *     @type string $headers Any email headers, defaults to no headers.
     2188         * }   
     2189         * @param string $type        The type of email being sent. Can be one of 'success', 'fail', 'manual', 'critical'.
     2190         * @param object $core_update The update offer that was attempted.
     2191         * @param mixed  $result      The result for the core update. Can be WP_Error.
     2192         */
     2193        $email = apply_filters( 'auto_core_update_email', $email, $type, $core_update, $result );
    20602194
    20612195        wp_mail( $email['to'], $email['subject'], $email['body'], $email['headers'] );
    20622196    }
    20632197
     2198    /**
     2199     * Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
     2200     *
     2201     * @since 3.7.0
     2202     */
    20642203    protected function send_debug_email() {
    20652204        $update_count = 0;
     
    20842223        }
    20852224
    2086         // Plugins, Themes, Languages
    2087         foreach ( array( 'plugin', 'theme', 'language' ) as $type ) {
     2225        // Plugins, Themes, Translations
     2226        foreach ( array( 'plugin', 'theme', 'translation' ) as $type ) {
    20882227            if ( ! isset( $this->update_results[ $type ] ) )
    20892228                continue;
     
    21292268        $body[] = '';
    21302269
    2131         foreach ( array( 'core', 'plugin', 'theme', 'language' ) as $type ) {
     2270        foreach ( array( 'core', 'plugin', 'theme', 'translation' ) as $type ) {
    21322271            if ( ! isset( $this->update_results[ $type ] ) )
    21332272                continue;
Note: See TracChangeset for help on using the changeset viewer.