Don't forget to flush your … rewrite rules

Before we get into this subject you should know that this is gonna be a technical article about pretty permalinks and their cache options in WordPress. You know what is WordPress right ? The CMS/blogging platform? No? Nothing familiar? If the answer is still “no” you are certainly in the wrong place.

The “Why?”!

As a WordPress developer I usually don’t give too much attention to the pretty permalinks, I just trust WordPress to do his job and build me some “pretty permalinks” as the option itself says. This actually works well if you don’t have any crazy idea about your own url rules or if you don’t implement some weird structure which you have in mind since your first grade. But I was working on a WordPress website and found myself into one slippery issue when my custom post type supposed to have its own archive like these parameters says :

register_post_type( 'project', array(
    'public' => true,
    'publicly_queryable' => true,
    'show_ui' => true,
    'show_in_menu' => true,
    'query_var' => true,
    'rewrite' => array( 'slug' => 'project' ),
    'capability_type' => 'post',
    'has_archive' => 'portfolio', //'has_archive' => true,
    'hierarchical' => true,
    'supports' => array( 'title', 'editor', 'thumbnail', 'comments' ))

Of course I was foolish enough to think that this will magically work. No, you need to flush the rewrite permalinks to make this work because WordPress caches this setting into an option in the database (to be more specific in table ‘wp_options’ @ ‘rewrite_rules’ field ) and it will not be refreshed until you manually flush the permalinks.

The “When?”!

This issue can appear whenever the rewrite url settings are modified. Let’s take a simple case when you have a very poor  pretty permalink rule like this:

This rule will say “Hey replace all the boring stuff from my url with the post title”. OK, WordPress will do so but you don’t have just posts into your website no? You have categories, maybe some custom post types or custom taxonomies or God knows what you have there. The problem is that different entities might have similar names ( more specific “slugs” ). With the above permalink setting, a post called “Portfolio” will certainly have a conflict with a category called “Portfolios”. I don’t know the result, sometimes I get the post displayed or maybe a dead simple 404 page but this mistake is very easy to be done … multiple times ( self slapping now ). You might say “That’s not a problem, I will rename the post title and the post slug and everything will be fine”. OK, if you thought this, now is the time to go UP and read the title of this article again, and again. To avoid these kind of issues you might want to hit it from the start. Define a proper permalink rule like so :

Now you have the category in front of the post title, there can’t be a conflict now. Still you might have a custom taxonomy or a custom post type archive slug with similar names but you should really avoid this case from the start, don’t wait for a miracle from WordPress. Another case that can trigger this issue is this. A full documentation about url operations in WordPress can be found here [quote] WordPress gurus suggest that pretty permalinks should start with a number (something about optimizing the speed of queries ) [/quote]

The Fix!

The easy way is just two clicks away because whenever you save the permalinks the rewrite rules are flushed ( yes that setting in Dashboard->Settings->Permalinks ). But what if this doesn’t work, what if for example a plugin which caches permalinks by its own rewrite rules ( I have a suspect but I need to study more to be sure ) or the web server, on nginx you don’t have .htaccess and this may cause some tricky bugs. Another simple solution: go and empty  the field in phpMyAdmin as I already said you can find this in wp_options searching %rewrite%; clear it, WordPress will regenerate a new one for you. delete_wp_options_rewrite_rules Well you can have more bad luck that what I’ve described above. What if you don’t have access to phpMyAdmin or you have a phobia for this panel ? (ha ha, that’s me back in time when I was a PHP apprentice ). There is a WordPress/PHP solution which you can throw in your theme’s “functions.php”

/* I've lied to you, there are 2 solutions */

/* A function: */

// And a method of the global object $wp_rewrite
global $wp_rewrite;

[quote text_size=”small” link=”#” author_title=”Careful”]

Remember there is a reason why WordPress is caching these settings, they cost a lot in performance terms and you should use this code only when you need it but definitely remove it after the job is done.


Other tips or further reading

Wanna know more about WordPress permalinks or you want to become a guru of pretty urls?

Closing the stage!

I hope you found this helpful or interesting if you came into contact with the subject for the first time. I would be glad to have some feedback and more then happy to get some critics or other tips. Cheers!

7 thoughts on “Don't forget to flush your … rewrite rules

  1. So… getting a 404 on a post type after using some other plugins… Guess what? rewrite_rules isn’t even and option_name under wp_options. Can’t find it. Tried the function, no avail. Any ideas?

  2. I appreciate, lead to I discovered exactly what I was looking for. You have ended my four day long hunt! God Bless you man. Have a great day. Bye

Leave a Reply