If you’ve ever been faced with 404’s and broken links after a site migration or web address change – then this post is for you!
You can prevent this from ever happening again with future-proofed links. Future-proofed links are links that are written with the future in mind. So in our case, the future might be that the site moves from it’s current place and/or the web address changes. And in the event that either one of those situations happen, these future-proofed links will automatically update and prevent broken links. No more 404’s – hurray!
Great, so how do we create these future-proofed WordPress links? Easy peasy. ( I never say easy peasy in real life, writing does that to you… ) Here are a few code snippets to help you out.
Before we get started, this quick post assumes that you have a permalink setup that is anything, but the default – “pretty permalinks” as some call it.
Future-proofing in the Theme
When building or editing an existing WordPress theme, the first practice you’ll want to stop doing is hardcoding urls. What I mean by this is writing out the urls manually. Here’s an example of what you don’t want to do anymore:
<a href="www.myawesomesite.com/about">About Me</a>
The problem with the above is if you decide somewhere down the road that you want your domain to be www.myreallycoolsite.com instead of www.myawesomesite.com, all those links will point to the old address and break. No bueno.
Or if you move a site from your local (computer) to a live server, then your localhost/awesomesite/wp (whatever your local url is) is going to be a dead end on your now live site living at www.awesome.com. Of course, you can go in and painstakingly, tediously, and manually fix them, but why do that if you don’t have to?
So this is what we want to do. We want to future-proof WordPress links using PHP functions instead of writing out urls in our theme. WordPress has a few of them depending on what you need. Here are some of them and what they output:
home_url or get_home_url:
<?php
/* *
* Outputs www.myawesomesite.com/about
*/
echo home_url('about');
/* *
* Outputs the same thing as the first example except adding "about" at the end is a bit different
*/
echo get_home_url() . '/about' ;
?>
Keep in mind that your “home” url is whatever the url is for your main posts. So if you’ve assigned your posts to be on another page on your dashboard, then this will be the url you get. Because this is something so easily changed on the dashboard, I personally don’t like to use home_url and instead opt for our next example, site_url…
Also, if you’re not sure whether your main posts have been assigned to another page, check out this how to video from wpbeginner, “How to create a separate page for blog posts…“.
site_url or get_site_url:
<?php
/* *
* Outputs www.myawesomesite.com/contact
*/
echo site_url('contact');
/* *
* Outputs the same thing as the above except adding "contact" at the end is a bit different
*/
echo get_site_url() . '/contact' ;
?>
The site url is the url of the site’s front page, meaning the site address itself regardless of what you’ve set as your homepage or the page that your posts live on.
<?php /* * * Outputs www.myawesomesite.com/wp-content/themes/my-theme * You can use this to refer to images or files * This is normally what's used for enqueueing files and within plugins */ echo get_template_directory_uri(); ?> <img src="<?php echo get_template_directory_uri() . '/images/img-candy.jpg'; ?>" alt="carnival candy"/>
This points to your site’s activated theme and can be used to link to images, enqueue files, and so on. Keep in mind however, that using this prevents others from overriding with a child theme because it will always refer to the parent. If you’re enqueuing files in your functions.php, and you want others to override your functions within a child theme, then you may want to use the next option, get_stylesheet_directory_uri.
If you’re already working in a child theme and try using this, it’s going to point to the parent theme and not your child. So if you’re trying to link to an image in your child theme that doesn’t exist in the parent, using get_template_directory_uri isn’t going to work. Instead, you’ll have to use get_stylesheet_directory_uri.
Speaking of that, let’s move on.
<?php /* * * Outputs www.myawesomesite.com/wp-content/themes/my-theme * HOWEVER this works in child themes and also allows the parent to be overwritten by child themes * Therefore this will be guaranteed to refer to the child theme instead of the parent */ echo echo get_stylesheet_directory_uri(); ?> <img src="<?php echo get_stylesheet_directory_uri() . '/images/img-candy.jpg'; ?>" alt="carnival candy"/>
This function will return the child theme path if a child theme is being used – if not, it will use the currently activated theme. Using this will enable others to override your functions in your parent theme. If you’re in a child theme, this ensures that the url you’re getting is the child, not the parent. If you want to refer to the parent while in a child theme on purpose, then you’d use get_template_directory_uri instead.
Those are the basics! These should be enough to cover most links within your WordPress theme. However, there are more WordPress urls functions here.
Future-proofing in the Text Editor
Now that we’ve gone over how to keep links from breaking with PHP, PHP has one big problem. It can’t be used within the text-editor. So if you have blog posts or page content that link to other places within your site, then during a migration or web address change, these will have to be manually fixed. But that’s a pain! There’s only so much we can do and odds are, unless this site is for yourself, we can only give users the tools and hope that they make use of them.
So first, advise clients or your users to avoid clicking that handy “add link” button in the text-editor. It’s located in the first row of the visual editor.
Second, offer them a shortcode as an option instead. Here are two simple shortcodes that can be dropped into your theme’s functions.php.
Site Url Shortcode:
The first example is using site_url that we went over earlier in this post. This will give users an easy way to link to the site itself or another page easily. The shortcode below has the option to append, meaning to add a slug or continue the path after the site-url function, and to change the default “Go Home” text that I’ve written there as a fallback.
// EXAMPLE 1: OUTPUT SITE URL W/ OPTIONAL APPEND/TEXT
// Add Shortcode
function site_url_shortcode( $atts ) {
// Attributes
extract( shortcode_atts( array(
'append' => '', //optional append to url
'text' => 'Go Home' //fallback text if none is provided
), $atts ) );
$site_link = '<a href="'. site_url( esc_attr( $append ) ) .'">' . esc_attr( $text ). '</a>';
return $site_link;
//use like this in the text-editor:
//[site-url append="about" text="My About Page"]
}
add_shortcode( 'site-url', 'site_url_shortcode' );
Get Permalink Shortcode:
This second example is for linking to another post with get_permalink. All the user has to do is to enter the post slug when using this shortcode. I used the slug instead of the ID as that’s less likely to change when a site moves. Just like the first shortcode, you also have the option to change the default text which is “My Other Post”. I was running out of creative names – I’m sorry! Feel free to make it sparkly and clever.
//EXAMPLE 2: POST LINK BY SLUG W/ OPTIONAL TEXT
// Add Shortcode
function post_link_shortcode( $atts ) {
// Attributes
extract( shortcode_atts( array(
'slug' => '', //required slug for permalink to function to another post
'text' => 'My Other Post'
), $atts ) );
//Checks if slug exists before outputting
if ( isset( $slug ) ) {
$post_link = '<a href="' . get_permalink( esc_attr( $slug ) ) . '">' . esc_attr( $text ) . '</a>';
return $post_link;
}
//use like this in the text-editor:
//[post-link slug="about-me" text="My About Page"]
}
add_shortcode( 'post-link', 'post_link_shortcode' );
You can expand or build off of these two shortcode examples. I used Bill Erickson’s post as a reference. You can also save time writing shortcodes by using Generate WordPress.
If you’re already in a position where the site has moved or the address has already changed, and the damage is already done, might want to try a plugin like Velvet Blues Update Urls. I haven’t had the need to use this personally, but the reviews and download number look promising!
But once your urls are changed, it might be in your best interest to go through them and swap them out for shortcodes – that is unless you either a) expect a theme change or b) there’s way too many posts to do this manually and if that’s the case, well we’re only human. As for the theme change, you can just move your shortcode functions to the new theme, but that would be up to you.
PHP FTW!
And that’s it! By going the PHP route, you ensure that your site will be 404, migration, and web address safe from that point onward. Your future-proofed links will automatically update and prevent broken links on their own.
Let’s go over our basic PHP toolkit for inside the theme files again:
- site_url or get_site_url – This retrieves your site’s actual address regardless of what you set your home page to on the dashboard settings.
- get_template_directory_uri – This retrieves the path to your active theme root, and if there is a child theme, this function will always retrieve the parent.
- get_stylesheet_directory_uri – This retrieves the path to your active theme root whether or not it’s a parent or child.
In our text-editor, we also have the option to use a shortcode, use a plugin, or go the risky find/replace route in a database file. I highly caution against that last option. The only urls you should be going into a database for are the site and home urls. Anything aside from that is risk not worth taking, trust me, I still have nightmares from the experiences! But hey, at least now you can sleep easy knowing your links are future-proofed with PHP.
Have any other ideas? Suggestions? I’d love to hear ’em!
Be First to Comment