Spring Sale! Save 30% on all books w/ code: PLANET24
Web Dev + WordPress + Security

How to Write Valid URL Query String Parameters

When building web pages, it is often necessary to add links that require parameterized query strings. For example, when adding links to the various validation services, you may find yourself linking to an accessibility checker, such as the freely available Cynthia service:

<a href="http://www.contentquality.com/mynewtester/cynthia.exe?Url1=http://domain.tld/&rptmode=2">WCAG Accessibility Check</a>

Another example is seen when linking your feed to a feed validation service:

<a href="http://validator.w3.org/feed/check.cgi?url=http://feeds.feedburner.com/domainfeed">RSS Feed Validation</a>

And one final example showing a more complex query string:

<a href="http://delicious.com/post?url=http://domain.tld/&title=The title of a post">Bookmark at Delicious</a>

As is, however, these links won’t validate due to a number of issues. Let’s fix ‘em up with a few quick-and-easy changes.

Replace ampersands with “&amp;”

One of the reasons these links aren’t validating is because they contain non-encoded ampersand ( & ) characters. Ampersands are often used in URL query strings to demarcate granular chunks of information, for example:

http://domain.tld/function.cgi?url=http://fonzi.com/&name=Fonzi&mood=happy&coat=leather

..which provides several different chunks of information about everybody’s favorite hellion. To get this code to validate, we need to encode the ampersands with &, for example:

http://domain.tld/function.cgi?url=http://fonzi.com/&name=Fonzi&mood=happy&coat=leather

Replacing the ampersand characters with encoded equivalents does not change the functionality of the query string, but it does produce completely valid code.

Encode other special characters

Let’s return to our Delicious example for a moment:

<a href="http://delicious.com/post?url=http://domain.tld/&title=The title of a post">Bookmark at Delicious</a>

The ampersand has been fixed, but this code still won’t validate due to the blank spaces in the title parameter. To fix this, we need to encode those blank spaces with their escaped hexadecimal equivalents, like so:

<a href="http://delicious.com/post?url=http://domain.tld/&title=The%20title%20of%20a%20post">Bookmark at Delicious</a>

..such that

&title=The title of a post

becomes

&title=The%20title%20of%20a%20post

..which is to say that a blank space is equivalent to “%20”.

Likewise, you should also encode any other special characters. For example, here is that previous feed validation link:

<a href="http://validator.w3.org/feed/check.cgi?url=http://feeds.feedburner.com/domainfeed">RSS Feed Validation</a>

If needed, we could encode the special characters in the url parameter like so:

<a href="http://validator.w3.org/feed/check.cgi?url=http%3A%2F%2Ffeeds.feedburner.com%2Fperishablepress">RSS Feed Validation</a>

As you can see, we have made the following replacements:

: with %3A
/ with %2F

As before, the encoded values function just as well as the non-encoded characters, with the added bonus that your code will validate!

Here is a good list of URL character codes

Tips and Tricks

The previous examples demonstrate the logic and technique behind writing valid URL query string parameters, but there are easier, more efficient ways to produce valid, dynamic links. First of all, rather than manually replacing each and every special character with its encoded equivalent, we can use the magical powers of PHP’s urlencode() function.

Let’s take an example from my recent article, Fully Valid, SEO-Friendly Social Media Links for WordPress:

<a href="http://twitter.com/home?status=Currently reading: <?php the_permalink(); ?>">Tweet this!</a>

This example provides a link to enable users to quickly post the URL of your posts to their Twitter feed. As is, the blank spaces in the status parameter render the code invalid. To change this, we use the urlencode() function like:

<a href="http://twitter.com/home?status=<?php echo urlencode("Currently reading: "); ?><?php the_permalink(); ?>">Tweet this!</a>

..which is now completely valid. Using this technique, we can encode any character string dynamically and easily. For WordPress users, we can even use urlencode() to dynamically encode various template tags such as get_the_title(), for example:

<a href="http://delicious.com/post?url=<?php the_permalink(); ?>&title=<?php echo urlencode(get_the_title($id)); ?>">Bookmark at Delicious</a>

This technique makes it possible to include sitewide, post-specific, parameterized links using a single line of code. And best of all? The code is completely valid! Nice :)

About the Author
Jeff Starr = Designer. Developer. Producer. Writer. Editor. Etc.
BBQ Pro: The fastest firewall to protect your WordPress.

28 responses to “How to Write Valid URL Query String Parameters”

  1. And in the end, the URL just becomes god-awful ugly. It’s necessary, nonetheless.

  2. Speaking of good-looking URL, I’ve always admired the way Wikipedia handles the latters.

  3. Another option if couldn’t do it until the client side for some reason would be the JavaScript encodeURIComponent() Function.

    http://www.w3schools.com/jsref/jsref_encodeURIComponent.asp

  4. Jeff Starr 2008/11/30 3:26 pm

    @John: True, but ugly, valid URLs are always better than less-ugly invalid URLs!

    @Bill: Thanks for the tip! Will definitely come in handy! :)

    @Louis: Are you referring to Wikipedia’s URL formatting, or something else?

  5. Loïc Hoguin 2008/11/30 5:50 pm

    You might want to take a look at http_build_query too.

  6. @Jeff: I’m referring to their UTF-8-ish URL style. Here’s an example of Cool URL:

    http://uk.wikipedia.org/wiki/Уніфікований_ідентифікатор_ресурсів

  7. Jamp Mark 2008/12/02 7:06 am

    always use urlencode() when dealing with query parameter values.

  8. Jeff Starr 2008/12/02 8:42 am

    @Loïc Hoguin: that is a great function for building URL query parameters, but I am not sure that it automatically encodes anything..

    @Louis: ah, I see.. yes those are very sweet looking, but they certainly don’t validate. I would love to peak at their URL scripts!

    @Jamp Mark: yes, that pretty much sums it up! ;)

    Update (2015/05/24): years later the “cool” URL is a garbled mess of gibberish. Probably due to the many server migrations that happened along the way, lol!

  9. Jonathan Ellse 2009/04/19 10:47 pm

    Brilliant post. This really clears up all the queries I had about url encoding etc.

    Thanks again Jeff

  10. Jeff Starr 2009/04/20 9:14 am

    My pleasure, Jonathan — glad to be of service! :)

  11. Eli Geske 2009/12/09 4:35 pm

    I have a peculiar situation that I am seeking some input on.

    I am building a custom content management tool using a separate database outside of wordpress, but the client still wants the skin to be wordpress. I created my own controller that gets included() in a custom template page. I use /%category%/%postname%/ for pretty permalinks. This all works fine. But I need to pass custom parameters via the URL to trigger some of my data on my custom template page that has nothing to do with wordpress. for example:

    http://mysite.com/my-wp-pagename?myparam=myvalue&moreparam=moremyvalues.

    Well WordPress thinks I am trying to select something from the database out of wp-categories, which doesnt even exist. This only shows up in the Apache error log. But if using header redirects crashes the site and timesout.

    QUESTION: Any ideas on how to pass custom parameters in the URL without having wordpress thinking their for wordpress????

    Any help on this one would be great.

    Thanks. If i find resolve I ll reply back.

  12. Hi Eli, that’s a new one for me – haven’t done that before. I would be surprised if there wasn’t something posted somewhere about that on the Web (but certainly you’ve already searched)..

    Definitely let us know if you find a solution – I’m sure it would help others in the same situation.

Comments are closed for this post. Something to add? Let me know.
Welcome
Perishable Press is operated by Jeff Starr, a professional web developer and book author with two decades of experience. Here you will find posts about web development, WordPress, security, and more »
WP Themes In Depth: Build and sell awesome WordPress themes.
Thoughts
I live right next door to the absolute loudest car in town. And the owner loves to drive it.
8G Firewall now out of beta testing, ready for use on production sites.
It's all about that ad revenue baby.
Note to self: encrypting 500 GB of data on my iMac takes around 8 hours.
Getting back into things after a bit of a break. Currently 7° F outside. Chillz.
2024 is going to make 2020 look like a vacation. Prepare accordingly.
First snow of the year :)
Newsletter
Get news, updates, deals & tips via email.
Email kept private. Easy unsubscribe anytime.