How to change WordPress slugs with WP-CLI commands and avoid 404 – wordpress

Changing names like page titles or tag names are safe operations, they won’t lead to 404 errors. But changing slugs needs to be careful, for slugs are meant to be used as part of URLs. Changing slugs would bring 404 errors if without redirecting the old URLs to the new ones. Good news is WordPress takes care of slug changing for posts and automatically redirect the old post URLs, but not for others.

Let’s see how to handle changing slugs properly for all the types with considering the impacts for SEO.

Impacts of changing slugs

Before you start

In the following sections, for simplicity we use wp-cli command to do the job. Of course you can do that in the admin pages.

WP-CLI

WP-CLI is a command line tool to manage your WordPress site. You can run it remotely.

See Run wp-cli remotely over SSH.

Remember to make redirects for changed(or removed) slugs except posts to avoid 404 errors. See how to do that in the “Set up 301 redirects for renamed or removed slugs” section at bottom.

Change post or page slugs (post_name)

An example that changes post_name of a post:

# Update post slug (post_name) of the post with ID 123
$ wp post update 123 --post_name=something-else
Success: Updated post 123.

As mentioned before, WordPress would try to redirect the old URL to the new one for posts whose slugs are changed. But you’d better update the old internal URLs across your site to avoid unnecessary redirects.

Note if you intend to change slugs of pages, you need to set up redirects for them.

Category or tag slugs

Change category or tag slugs

Examples that changes, deletes category/tag slugs:

# Update category name and slug for the category with ID 12
$ wp term update category 12 --name=site-performance --slug=site-performance
Success: Term updated.

# Update tag name and slug for the tag with slug 'sample'
$ wp term update post_tag sample --by=slug --name=js-sample --slug=js-sample
Success: Term updated.

# Delete a tag
$ wp term delete post_tag sample --by=slug
Deleted post_tag 17.
Success: Deleted 1 of 1 term

You can specify the category/tag to update by ID or slug, without --by option it will be ID.

By default, the slug is generated from the name, like the slug for a tag name Site Performance will be site-performance.

Note if you set tags of a post like below, it is safe. The operation just associate the post to the specified tags.

# Set tags of the post.
$ wp post term set 94 post_tag new-tag1 new-tag2
Success: Set term.

Delete category or tag slugs

Before you remove a tag/category, make sure there are no posts under that category/tag, and there are no sub categories under that category.

Examples that deletes category/tag slugs

# Remove a category

# 1. Make sure there are no posts or subcategories under the category 
#    to delete.
# List all the categories and limit output to the specified fields
$ wp term list category --fields=term_id,name,slug,parent,count
+---------+-------------+---------------+--------+-------+
| term_id | name        | slug          | parent | count |
+---------+-------------+---------------+--------+-------+
| 39      | speed       | speed         | 0      | 0     |
...
+---------+-------------+---------------+--------+-------+

# 2. Delete the term
$ wp term delete 39

# Remove a post tag with slug 'hook'

# Make sure there are no posts under the tag
$ wp term  list post_tag --slug=hook
+---------+------------------+------+------+-------------+--------+-------+
| term_id | term_taxonomy_id | name | slug | description | parent | count |
+---------+------------------+------+------+-------------+--------+-------+
| 17      | 17               | hook | hook |             | 0      | 0     |
+---------+------------------+------+------+-------------+--------+-------+

# Remove the tag
$ wp term delete 17

SEO weight of tags

Tags are mainly used to organize the content. They does not contribute much value to SEO. And SEO plugin like Yoast has not stopped to use tags as keyword meta because Google says it does not use the keywords meta tag in web ranking.

Set up 301 redirects for renamed or removed slugs to avoid 404

As mentioned before, without redirecting the old URLs to the new URLs after you change slugs, there will be 404 errors. And many 404 errors hurt our site ranking and may bring performance issues.

Find all the 404 errors

You can find all the 404 errors in the Google search console.

For changed slugs, you need to redirect the old URLs to new. For removed slugs, you can redirect them to some related URLs or just redirect them to the home URL to avoid 404.

If you intend to make redirects by yourself without installing a plugin like Redirection, you can do that inside the .htaccess, or a plugin, a child theme.

Redirect with config inside `.htaccess`

Below command in .htaccess redirects the old URL to the new URL:

Redirect 301 /oldurl/? https://www.my-site.com/newurl/

RewriteRule can also be used to change the querying URL. If you have many redirects that needs different rewrite rules, such configuration may look mess.

Redirect with PHP inside a plugin / child theme

Below are examples that set up redirections in a plugin or a child theme.

An example that redirects the old tag URLs to the new URLs:

// Redirect the old tag URLs to the new URLs for renamed tags.
function mycustom_redirect_renamed_tag_slugs($result) {
    $tag_redirects = array(
        'old-tag-slug-1' => 'new-tag-slug-1',
    );

    $tag = get_query_var('tag'); // The tag slug if it is querying tag archive.
    if ($tag && isset($tag_redirects[$tag])) {
        wp_redirect(home_url('/tag/' . $tag_redirects . '/'), 301);
        exit;
    }

    return $result;
}
add_filter('pre_handle_404', 'mycustom_redirect_renamed_tag_slugs');

Note you can also add your function to the action template_redirect. But it fires more later, just before WordPress determines which template page to load. At this point, more queries may have been tried.

An example that redirects the not found tags to the home page:

// Redirect unfound tag URLs to home URL for removed tags.
function mycustom_redirect_removed_tags($result) {
    $tag_redirects = array(
        'removed-tag-slug-1' => true,
    );

    // If it querying a tag page and the tag does not exist.
    if (get_query_var('tag') && !get_query_var('tag_id')) {
        wp_redirect( home_url('/'), 301);
        exit;
    }

    return $result;
}
add_filter('pre_handle_404', 'mycustom_redirect_removed_tag_slugs');

See more at [How to create your own plugin to custom WordPress](/wordpress-custo m/).

Resource

WordPress Glossary: Slug