Changeset 47122 for trunk/src/wp-admin/includes/upgrade.php

Timestamp:

01/29/2020 12:43:23 AM (5 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-admin/includes/upgrade.php (modified) (44 diffs)

trunk/src/wp-admin/includes/upgrade.php

@@ -155 +155 @@
         global $wpdb, $wp_rewrite, $table_prefix;
 
-        // Default category
+        // Default category.
         $cat_name = __( 'Uncategorized' );
         /* translators: Default category slug. */
@@ -200 +200 @@
         $cat_tt_id = $wpdb->insert_id;
 
-        // First post
+        // First post.
         $now             = current_time( 'mysql' );
         $now_gmt         = current_time( 'mysql', 1 );
@@ -220 +220 @@
             );
 
-            // Back-compat for pre-4.4
+            // Back-compat for pre-4.4.
             $first_post = str_replace( 'SITE_URL', esc_url( network_home_url() ), $first_post );
             $first_post = str_replace( 'SITE_NAME', get_network()->site_name, $first_post );
@@ -258 +258 @@
         );
 
-        // Default comment
+        // Default comment.
         if ( is_multisite() ) {
             $first_comment_author = get_site_option( 'first_comment_author' );
@@ -287 +287 @@
         );
 
-        // First Page
+        // First page.
         if ( is_multisite() ) {
             $first_page = get_site_option( 'first_page' );
@@ -353 +353 @@
         );
 
-        // Privacy Policy page
+        // Privacy Policy page.
         if ( is_multisite() ) {
             // Disable by default unless the suggested content is provided.
@@ -494 +494 @@
             $wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->usermeta WHERE user_id != %d AND meta_key = %s", $user_id, $table_prefix . 'capabilities' ) );
 
-            // Delete any caps that snuck into the previously active blog. (Hardcoded to blog 1 for now.) TODO: Get previous_blog_id.
+            // Delete any caps that snuck into the previously active blog. (Hardcoded to blog 1 for now.)
+            // TODO: Get previous_blog_id.
             if ( ! is_super_admin( $user_id ) && $user_id != 1 ) {
                 $wpdb->delete(
@@ -551 +552 @@
         $test_url = '';
 
-        // Test against a real WordPress Post
+        // Test against a real WordPress post.
         $first_post = get_page_by_path( sanitize_title( _x( 'hello-world', 'Default post slug' ) ), OBJECT, 'post' );
         if ( $first_post ) {
@@ -853 +854 @@
     global $wpdb;
 
-    // Get the title and ID of every post, post_name to check if it already has a value
+    // Get the title and ID of every post, post_name to check if it already has a value.
     $posts = $wpdb->get_results( "SELECT ID, post_title, post_name FROM $wpdb->posts WHERE post_name = ''" );
     if ( $posts ) {
@@ -892 +893 @@
     if ( $allposts ) :
         foreach ( $allposts as $post ) {
-            // Check to see if it's already been imported
+            // Check to see if it's already been imported.
             $cat = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->post2cat WHERE post_id = %d AND category_id = %d", $post->ID, $post->post_category ) );
-            if ( ! $cat && 0 != $post->post_category ) { // If there's no result
+            if ( ! $cat && 0 != $post->post_category ) { // If there's no result.
                 $wpdb->insert(
                     $wpdb->post2cat,
@@ -918 +919 @@
     global $wpdb;
 
-    // Clean up indices, add a few
+    // Clean up indices, add a few.
     add_clean_index( $wpdb->posts, 'post_name' );
     add_clean_index( $wpdb->posts, 'post_status' );
@@ -955 +956 @@
     }
 
-    // Get the GMT offset, we'll use that later on
+    // Get the GMT offset, we'll use that later on.
     $all_options = get_alloptions_110();
 
@@ -969 +970 @@
     $gmt_offset            = -$diff_gmt_weblogger;
 
-    // Add a gmt_offset option, with value $gmt_offset
+    // Add a gmt_offset option, with value $gmt_offset.
     add_option( 'gmt_offset', $gmt_offset );
 
-    // Check if we already set the GMT fields (if we did, then
-    // MAX(post_date_gmt) can't be '0000-00-00 00:00:00'
-    // <michel_v> I just slapped myself silly for not thinking about it earlier
+    /*
+     * Check if we already set the GMT fields. If we did, then
+     * MAX(post_date_gmt) can't be '0000-00-00 00:00:00'.
+     * <michel_v> I just slapped myself silly for not thinking about it earlier.
+     */
     $got_gmt_fields = ! ( $wpdb->get_var( "SELECT MAX(post_date_gmt) FROM $wpdb->posts" ) == '0000-00-00 00:00:00' );
 
     if ( ! $got_gmt_fields ) {
 
-        // Add or subtract time to all dates, to get GMT dates
+        // Add or subtract time to all dates, to get GMT dates.
         $add_hours   = intval( $diff_gmt_weblogger );
         $add_minutes = intval( 60 * ( $diff_gmt_weblogger - $add_hours ) );
@@ -1053 +1056 @@
     }
 
-    // Obsolete tables
+    // Obsolete tables.
     $wpdb->query( 'DROP TABLE IF EXISTS ' . $wpdb->prefix . 'optionvalues' );
     $wpdb->query( 'DROP TABLE IF EXISTS ' . $wpdb->prefix . 'optiontypes' );
@@ -1059 +1062 @@
     $wpdb->query( 'DROP TABLE IF EXISTS ' . $wpdb->prefix . 'optiongroup_options' );
 
-    // Update comments table to use comment_type
+    // Update comments table to use comment_type.
     $wpdb->query( "UPDATE $wpdb->comments SET comment_type='trackback', comment_content = REPLACE(comment_content, '<trackback />', '') WHERE comment_content LIKE '<trackback />%'" );
     $wpdb->query( "UPDATE $wpdb->comments SET comment_type='pingback', comment_content = REPLACE(comment_content, '<pingback />', '') WHERE comment_content LIKE '<pingback />%'" );
 
-    // Some versions have multiple duplicate option_name rows with the same values
+    // Some versions have multiple duplicate option_name rows with the same values.
     $options = $wpdb->get_results( "SELECT option_name, COUNT(option_name) AS dupes FROM `$wpdb->options` GROUP BY option_name" );
     foreach ( $options as $option ) {
@@ -1371 +1374 @@
         /*
          * Create link_category terms for link categories. Create a map of link
-         * cat IDs to link_category terms.
+         * category IDs to link_category terms.
          */
         $link_cat_id_map  = array();
@@ -1412 +1415 @@
         }
 
-        // Associate links to cats.
+        // Associate links to categories.
         $links = $wpdb->get_results( "SELECT link_id, link_category FROM $wpdb->links" );
         if ( ! empty( $links ) ) {
@@ -1461 +1464 @@
 
     if ( $wp_current_db_version < 4772 ) {
-        // Obsolete linkcategories table
+        // Obsolete linkcategories table.
         $wpdb->query( 'DROP TABLE IF EXISTS ' . $wpdb->prefix . 'linkcategories' );
     }
 
-    // Recalculate all counts
+    // Recalculate all counts.
     $terms = $wpdb->get_results( "SELECT term_taxonomy_id, taxonomy FROM $wpdb->term_taxonomy" );
     foreach ( (array) $terms as $term ) {
@@ -1587 +1590 @@
     }
 
-    // Update post_date for unpublished posts with empty timestamp
+    // Update post_date for unpublished posts with empty timestamp.
     if ( $wp_current_db_version < 8921 ) {
         $wpdb->query( "UPDATE $wpdb->posts SET post_date = post_modified WHERE post_date = '0000-00-00 00:00:00'" );
@@ -1638 +1641 @@
 
     if ( $wp_current_db_version < 11958 ) {
-        // Previously, setting depth to 1 would redundantly disable threading, but now 2 is the minimum depth to avoid confusion
+        // Previously, setting depth to 1 would redundantly disable threading,
+        // but now 2 is the minimum depth to avoid confusion.
         if ( get_option( 'thread_comments_depth' ) == '1' ) {
             update_option( 'thread_comments_depth', 2 );
@@ -1770 +1774 @@
             unset( $_sidebars_widgets );
 
-            // intentional fall-through to upgrade to the next version.
+            // Intentional fall-through to upgrade to the next version.
         case 2:
             $sidebars_widgets                  = retrieve_widgets();
@@ -1828 +1832 @@
 
     if ( $wp_current_db_version < 22006 && $wpdb->get_var( "SELECT link_id FROM $wpdb->links LIMIT 1" ) ) {
-        update_option( 'link_manager_enabled', 1 ); // Previously set to 0 by populate_options()
+        update_option( 'link_manager_enabled', 1 ); // Previously set to 0 by populate_options().
     }
 
@@ -2022 +2026 @@
  */
 function upgrade_431() {
-    // Fix incorrect cron entries for term splitting
+    // Fix incorrect cron entries for term splitting.
     $cron_array = _get_cron_array();
     if ( isset( $cron_array['wp_batch_split_terms'] ) ) {
@@ -2139 +2143 @@
  */
 function upgrade_530() {
-    // The `admin_email_lifespan` option may have been set by an admin that just logged in,
-    // saw the verification screen, clicked on a button there, and is now upgrading the db,
-    // or by populate_options() that is called earlier in upgrade_all().
-    // In the second case `admin_email_lifespan` should be reset so the verification screen
-    // is shown next time an admin logs in.
+    /*
+     * The `admin_email_lifespan` option may have been set by an admin that just logged in,
+     * saw the verification screen, clicked on a button there, and is now upgrading the db,
+     * or by populate_options() that is called earlier in upgrade_all().
+     * In the second case `admin_email_lifespan` should be reset so the verification screen
+     * is shown next time an admin logs in.
+     */
     if ( function_exists( 'current_user_can' ) && ! current_user_can( 'manage_options' ) ) {
         update_option( 'admin_email_lifespan', 0 );
@@ -2160 +2166 @@
     global $wp_current_db_version, $wpdb;
 
-    // Always clear expired transients
+    // Always clear expired transients.
     delete_expired_transients( true );
 
-    // 2.8.
+    // 2.8
     if ( $wp_current_db_version < 11549 ) {
         $wpmu_sitewide_plugins   = get_site_option( 'wpmu_sitewide_plugins' );
@@ -2302 +2308 @@
 
 //
-// General functions we use to actually do stuff
+// General functions we use to actually do stuff.
 //
 
@@ -2329 +2335 @@
     }
 
-    // Didn't find it try to create it..
+    // Didn't find it, so try to create it.
     $wpdb->query( $create_ddl );
 
@@ -2354 +2360 @@
     $wpdb->hide_errors();
     $wpdb->query( "ALTER TABLE `$table` DROP INDEX `$index`" );
-    // Now we need to take out all the extra ones we may have created
+    // Now we need to take out all the extra ones we may have created.
     for ( $i = 0; $i < 25; $i++ ) {
         $wpdb->query( "ALTER TABLE `$table` DROP INDEX `{$index}_$i`" );
@@ -2400 +2406 @@
     }
 
-    // Didn't find it try to create it.
+    // Didn't find it, so try to create it.
     $wpdb->query( $create_ddl );
 
@@ -2567 +2573 @@
     }
 
-    // Separate individual queries into an array
+    // Separate individual queries into an array.
     if ( ! is_array( $queries ) ) {
         $queries = explode( ';', $queries );
@@ -2582 +2588 @@
     $queries = apply_filters( 'dbdelta_queries', $queries );
 
-    $cqueries   = array(); // Creation Queries
-    $iqueries   = array(); // Insertion Queries
+    $cqueries   = array(); // Creation queries.
+    $iqueries   = array(); // Insertion queries.
     $for_update = array();
 
-    // Create a tablename index for an array ($cqueries) of queries
+    // Create a tablename index for an array ($cqueries) of queries.
     foreach ( $queries as $qry ) {
         if ( preg_match( '|CREATE TABLE ([^ ]*)|', $qry, $matches ) ) {
@@ -2598 +2604 @@
             $iqueries[] = $qry;
         } else {
-            // Unrecognized query type
+            // Unrecognized query type.
         }
     }
@@ -2635 +2641 @@
         }
 
-        // Fetch the table column structure from the database
+        // Fetch the table column structure from the database.
         $suppress    = $wpdb->suppress_errors();
         $tablefields = $wpdb->get_results( "DESCRIBE {$table};" );
@@ -2783 +2789 @@
             $tablefield_type_lowercased  = strtolower( $tablefield->Type );
 
-            // If the table field exists in the field array ...
+            // If the table field exists in the field array...
             if ( array_key_exists( $tablefield_field_lowercased, $cfields ) ) {
 
@@ -2808 +2814 @@
                     if ( $do_change ) {
                         // Add a query to change the column type.
-                        $cqueries[]                                      = "ALTER TABLE {$table} CHANGE COLUMN `{$tablefield->Field}` " . $cfields[ $tablefield_field_lowercased ];
+                        $cqueries[] = "ALTER TABLE {$table} CHANGE COLUMN `{$tablefield->Field}` " . $cfields[ $tablefield_field_lowercased ];
+
                         $for_update[ $table . '.' . $tablefield->Field ] = "Changed type of {$table}.{$tablefield->Field} from {$tablefield->Type} to {$fieldtype}";
                     }
@@ -2818 +2825 @@
                     if ( $tablefield->Default != $default_value ) {
                         // Add a query to change the column's default value
-                        $cqueries[]                                      = "ALTER TABLE {$table} ALTER COLUMN `{$tablefield->Field}` SET DEFAULT '{$default_value}'";
+                        $cqueries[] = "ALTER TABLE {$table} ALTER COLUMN `{$tablefield->Field}` SET DEFAULT '{$default_value}'";
+
                         $for_update[ $table . '.' . $tablefield->Field ] = "Changed default value of {$table}.{$tablefield->Field} from {$tablefield->Default} to {$default_value}";
                     }
@@ -2833 +2841 @@
         foreach ( $cfields as $fieldname => $fielddef ) {
             // Push a query line into $cqueries that adds the field to that table.
-            $cqueries[]                              = "ALTER TABLE {$table} ADD COLUMN $fielddef";
+            $cqueries[] = "ALTER TABLE {$table} ADD COLUMN $fielddef";
+
             $for_update[ $table . '.' . $fieldname ] = 'Added column ' . $table . '.' . $fieldname;
         }
@@ -2846 +2855 @@
             // For every index in the table.
             foreach ( $tableindices as $tableindex ) {
+                $keyname = strtolower( $tableindex->Key_name );
 
                 // Add the index to the index data array.
-                $keyname                             = strtolower( $tableindex->Key_name );
                 $index_ary[ $keyname ]['columns'][]  = array(
                     'fieldname' => $tableindex->Column_name,
@@ -2905 +2914 @@
         foreach ( (array) $indices as $index ) {
             // Push a query line into $cqueries that adds the index to that table.
-            $cqueries[]   = "ALTER TABLE {$table} ADD $index";
+            $cqueries[] = "ALTER TABLE {$table} ADD $index";
+
             $for_update[] = 'Added index ' . $table . ' ' . $index;
         }
@@ -3069 +3079 @@
 
     // Copy files from the default theme to the site theme.
-    //$files = array('index.php', 'comments.php', 'comments-popup.php', 'footer.php', 'header.php', 'sidebar.php', 'style.css');
+    // $files = array( 'index.php', 'comments.php', 'comments-popup.php', 'footer.php', 'header.php', 'sidebar.php', 'style.css' );
 
     $theme_dir = @opendir( $default_dir );
@@ -3270 +3280 @@
     global $wp_current_db_version, $wpdb;
 
-    // Upgrade versions prior to 2.9
+    // Upgrade versions prior to 2.9.
     if ( $wp_current_db_version < 11557 ) {
         // Delete duplicate options. Keep the option with the highest option_id.
@@ -3285 +3295 @@
     if ( $wp_current_db_version < 25448 && is_multisite() && wp_should_upgrade_global_tables() ) {
 
-        // Upgrade versions prior to 3.7
+        // Upgrade versions prior to 3.7.
         if ( $wp_current_db_version < 25179 ) {
             // New primary key for signups.
@@ -3343 +3353 @@
 ) $charset_collate;
 ";
-        // now create tables
+        // Now create tables.
         dbDelta( $ms_queries );
     }
@@ -3368 +3378 @@
 function wp_should_upgrade_global_tables() {
 
-    // Return false early if explicitly not upgrading
+    // Return false early if explicitly not upgrading.
     if ( defined( 'DO_NOT_UPGRADE_GLOBAL_TABLES' ) ) {
         return false;
     }
 
-    // Assume global tables should be upgraded
+    // Assume global tables should be upgraded.
     $should_upgrade = true;
 
-    // Set to false if not on main network (does not matter if not multi-network)
+    // Set to false if not on main network (does not matter if not multi-network).
     if ( ! is_main_network() ) {
         $should_upgrade = false;
     }
 
-    // Set to false if not on main site of current network (does not matter if not multi-site)
+    // Set to false if not on main site of current network (does not matter if not multi-site).
     if ( ! is_main_site() ) {
         $should_upgrade = false;