Migrate From Attribute?

[outrank-james]

Is there a tool built in to migrate from an Attribute we've already got set up for Brands?

Or do we need to do a bulk Export / Import to utilise the new brand taxonomy?

[jimjasson]

Hey @outrank-james,

Thanks for the question!

In another thread in this board, we discussed the concept of migrating from a custom attribute to the new Brands taxonomy. In short:

All the brands logic that is now part of core was previously offered by the WooCommerce Brands plugin. Users of this plugin will automatically see all their brands migrated to core without any further action, as that the same taxonomy is used. If a store created brands using a custom taxonomy, attribute or any other way, then this would require custom work, as we cannot account for all the custom brands implementations that have been created and craft a universal migration tool.

If you decide to do the migration programmatically, instead of manually, and have any questions about the structure of core's Brands taxonomy, let us know!

[WiredWonder]

@jimjasson what is the name of the taxonomy slug used by this new addition to core? It would be nice of any of the announcement doco actually mentioned this.

Does the team consider how are site admins will migrate from custom plugins to core functionality when there are no tools, pathways or sample code given? Both this and GTIN have been handled terribly for existing users of your product.

[jimjasson]

Hey @WiredWonder,

Thank you for your question!

The new taxonomy that was added to represent brands is product_brand -- here's the function that registers this taxonomy: https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/includes/class-wc-brands.php#L237.

As for migration, there are a couple of ways forward depending on what kind of solution you were previously using.

If you were using the WooCommerce Brands plugin, then all your brands will be migrated automatically.

If you were using a custom taxonomy or a different Brands plugin that used a custom taxonomy, then some users have found this migration tool useful: #54720 (reply in thread).

If you were using a custom attribute to represent brands, then you could either migrate brands manually or create a custom script specific to your custom attribute implementation.

Finally, if you would like to keep using your own solution for organizing products by brands in your store, then you can disable WooCommerce core's Brands functionality by running the following WP CLI command: wp option update wc_feature_woocommerce_brands_enabled 'no', as described in this developer blog post.

Let me know if you have any specific questions about the above! :)

[WiredWonder]

@jimjasson Thanks for the very practical reply

Adding features is all goodness, but I do hope the core team take more note of these types of rollouts to map out expected (both desired & undesired) user behaviour for existing users of WooCommerce when adding a feature. We users have had to resort to plugins for things like Brand and GTIN due to core limitations, and if core is now adding the feature, your goal should be to get the majority of users onto core functionality to make the ecosystem more streamlined. This process requires planning, compatibility testing and suggesting migration tools or processes to allow merchants to take advantage of your work, and this should be publicised or linked from the release notes to avoid user community confusion.

I think many users will have used an Attribute to store Brand as we did, and there is no path to migrate ~7000 products to the new feature.

[jimjasson]

@WiredWonder Thank you for your insightful feedback.

I completely agree that essential merchandising functionality was missing from WooCommerce core for a while now, and this led to the creation of plugins or custom solutions that filled that gap. Our goal is to merge some of those plugins into core, in order to decrease the number of plugins users have to buy and maintain to launch their store.

Given the variety of different plugins or custom solutions, it is not always possible to create a migration tool that works for all users.

That's why:

• we did a gradual roll-out of the Brands feature, starting with WooCommerce v9.4: https://developer.woocommerce.com/2024/10/01/introducing-brands/, to give users many months in advance to test the new feature and share feedback and;
• we tested the new feature with other Brands plugins to ensure that there aren't any significant compatibility issues, like fatal errors or data losses, when both were active at the same time.

Before releasing a new feature, our team goes through numerous real-world scenarios to test the feature, identify potential issues and make adjustments. However, feedback and insight from users, like you, can help reveal a different perspective or a use case that we might haven't considered. That's why I encourage you to join the WooCommerce community Slack: https://woocommerce.com/community-slack/ and share your thoughts every time a new beta/RC WooCommerce version is released. Thank you in advance for your contribution!

[WiredWonder]

@jimjasson I am on a slack called woocommercecommunity -- I think something changed and the channel is now dead.

One comment on the rollout plan --

we did a gradual roll-out of the Brands feature, starting with WooCommerce v9.4: https://developer.woocommerce.com/2024/10/01/introducing-brands/, to give users many months in advance to test the new feature and share feedback

Two and a bit months (Oct-Jan) between introduction and enabled by default is not what I'd call a long time. Store owners are busy running their businesses, not sitting around waiting for new software to test 😅

I feel that (possibly) breaking changes like this keep merchants from being able to stay up to date with releases, because store testing is required before they can upgrade, and in cases like this data migration or even custom development. This skillset is not something most store owners have, so if core have not allowed for these scenarios in the software then this requires the store owner to engage third parties at cost. This is I think a point where the core team can make a huge difference to uptake/reputation and make the platform feel more like a SaaS where upgrades can be seamless. </end rant>

If anyone has a reference or example on how to migrate from a Product Attribute to a Taxonomy please share :)

[panopticdesign]

I second this comment. Also, rolling out new functions and features during the busy holiday season (December) is horrible.

[jamesckemp]

Hey, we hear you. I've set up a discussion over here for anyone to provide feedback on how we can improve communications!

[damiankrzyz]

Here is a code I used to migrate from attributes pa_brand to new product_brand. Hope it works for you.

<?php
// Prevent direct access to this file
if (!defined('ABSPATH')) {
    exit;
}

// Add menu under WooCommerce
add_action('admin_menu', function() {
    add_submenu_page(
        'woocommerce',           // Parent slug (WooCommerce menu)
        'Migrate Brands',        // Page title
        'Migrate Brands',        // Menu title
        'manage_woocommerce',    // Capability required
        'wc-migrate-brands',     // Menu slug
        'render_brand_migration_page' // Callback function
    );
});

function render_brand_migration_page() {
    ?>
    <div class="wrap">
        <h1>WooCommerce Brand Migration Tool</h1>
        
        <?php
        if (isset($_POST['migrate_brands']) && check_admin_referer('migrate_brands_nonce')) {
            $results = migrate_brands_to_woo_core();
            
            if ($results) {
                echo '<div class="notice notice-success"><p>';
                echo sprintf('Successfully migrated %d brands<br>', count($results['success']));
                echo sprintf('Updated %d products<br>', $results['products_updated']);
                echo sprintf('Skipped existing brands: %d', count($results['skipped']));
                echo '</p></div>';
                
                if (!empty($results['skipped'])) {
                    echo '<div class="notice notice-warning"><p>Skipped brands (already exist):<br>';
                    foreach ($results['skipped'] as $skipped) {
                        echo esc_html("- {$skipped}<br>");
                    }
                    echo '</p></div>';
                }
            }
        }
        ?>
        
        <div class="card" style="max-width: 600px; margin-top: 20px; padding: 20px;">
            <h2>Migration Details</h2>
            <p>This tool will:</p>
            <ul style="list-style-type: disc; margin-left: 20px;">
                <li>Move all brands from product attributes (pa_brand) to the new WooCommerce Brands system</li>
                <li>Update products to maintain their original brand relationships</li>
                <li>Skip any brands that already exist in the new system</li>
            </ul>
            
            <div style="background: #fff8e5; border-left: 4px solid #ffb900; padding: 12px; margin: 20px 0;">
                <strong>Important:</strong> Please back up your database before proceeding with the migration.
            </div>
            
            <?php
            // Check if old brands exist
            $old_brands = get_terms(array(
                'taxonomy' => 'pa_brand',
                'hide_empty' => false,
            ));
            
            if (!is_wp_error($old_brands) && !empty($old_brands)) {
                echo '<p><strong>Found ' . count($old_brands) . ' brands to migrate.</strong></p>';
                ?>
                <form method="post">
                    <?php wp_nonce_field('migrate_brands_nonce'); ?>
                    <button type="submit" name="migrate_brands" class="button button-primary" 
                            onclick="return confirm('Are you sure you want to start the migration? Make sure you have a backup.');">
                        Start Migration
                    </button>
                </form>
                <?php
            } else {
                echo '<div class="notice notice-warning"><p>No brands found in the old pa_brand attribute system.</p></div>';
            }
            ?>
        </div>
    </div>
    <?php
}

function migrate_brands_to_woo_core() {
    global $wpdb;
    
    // Get all products that have brand attributes
    $products = wc_get_products(array(
        'limit' => -1,
        'status' => 'any',
    ));
    
    $migration_log = array(
        'success' => array(),
        'skipped' => array(),
        'products_updated' => 0
    );
    
    $brand_term_mapping = array(); // Cache for brand term mapping
    
    foreach ($products as $product) {
        $attributes = $product->get_attributes();
        
        // Check if product has brand attribute
        if (!isset($attributes['pa_brand'])) {
            continue;
        }
        
        $brand_attribute = $attributes['pa_brand'];
        $brand_options = $brand_attribute->get_options();
        
        if (empty($brand_options)) {
            continue;
        }
        
        // Get the first brand term (assuming one brand per product)
        $old_brand_term = get_term_by('id', $brand_options[0], 'pa_brand');
        if (!$old_brand_term) {
            continue;
        }
        
        // Check cache first
        if (isset($brand_term_mapping[$old_brand_term->name])) {
            $new_term_id = $brand_term_mapping[$old_brand_term->name];
        } else {
            // Check if brand already exists in new system
            $existing_brand = get_term_by('name', $old_brand_term->name, 'product_brand');
            
            if ($existing_brand) {
                $migration_log['skipped'][] = $old_brand_term->name;
                $new_term_id = $existing_brand->term_id;
            } else {
                // Create new brand term
                $new_brand = wp_insert_term(
                    $old_brand_term->name,
                    'product_brand',
                    array(
                        'description' => $old_brand_term->description,
                        'slug' => $old_brand_term->slug
                    )
                );
                
                if (is_wp_error($new_brand)) {
                    continue;
                }
                
                $new_term_id = $new_brand['term_id'];
                
                // Copy term meta if exists
                $term_meta = get_term_meta($old_brand_term->term_id);
                if (!empty($term_meta)) {
                    foreach ($term_meta as $meta_key => $meta_values) {
                        foreach ($meta_values as $meta_value) {
                            add_term_meta($new_term_id, $meta_key, maybe_unserialize($meta_value));
                        }
                    }
                }
                
                $migration_log['success'][] = array(
                    'old_term_id' => $old_brand_term->term_id,
                    'new_term_id' => $new_term_id,
                    'name' => $old_brand_term->name
                );
            }
            
            // Cache the mapping
            $brand_term_mapping[$old_brand_term->name] = $new_term_id;
        }
        
        // Update product with new brand taxonomy
        wp_set_object_terms($product->get_id(), array($new_term_id), 'product_brand', false);
        $migration_log['products_updated']++;
    }
    
    return $migration_log;
}
?>