Integrating the New Google reCAPTCHA With YOURLS

This guide and screenshots are courtesy of Jared Stark and Erasure Web Services, originally available on their own shortener. It’s duplicated here in case their goes offline or missing but please check on the original link first in case they have updated it. Much thanks to them!

How to integrate the New Google reCAPTCHA With YOURLS

The problem

URL shortening services are often a target for automated spam form submissions. The traditional way to prevent spam bots from doing this is to require a captcha to be properly filled out before a form can be submitted. Unfortunately, captchas can significantly reduce the quality of a user experience as they require deciphering cryptic text, putting the pieces of a puzzle together, or some other action which can significantly increase the amount of time a user spends trying to complete a form.

The new Google reCAPTCHA service aims to get rid of those traditional problems with captchas by providing what they call the “No CAPTCHA reCAPTCHA experience.” This is accomplished by using an “advanced risk analysis system” which can separate actual humans from bots with just the check of a box. More information about this system can be found on the Google reCAPTCHA website.

Because of its easy of use, the new Google reCAPTCHA is ideal for URL Shortening websites since it allows users to create short URLS quickly while preventing spam at the same time. This tutorial will show you how to integrate this service into a YOURLS installation, much like what this website, uses.

The solution : tutorial

This tutorial will show how to implement the “No CAPTCHA reCAPTCHA” into the default YOURLS public interface setup. Obviously, it can be tweaked and modified for other public interfaces.

Please note that this tutorial uses the reCAPTCHA API 1.0.

  1. Visit the Google reCAPTCHA website. You will need to “Get reCAPTCHA,” which requires a Google account. After filling out the required information, you should receive your site key and secret key. Make sure to keep this information handy.
  2. In your YOURLS installation, open the file includes/functions-html.php. Copy the JavaScript client-side script from the reCAPTCHA website and place it in the described place (screenshot)
  3. Open your public interface file. On the reCAPTCHA website, copy the “sitekey” line and paste it in the described place (screenshot)
  4. Upload a copy of the captcha.php and recaptchalib.php files to the directory of your YOURLS installation that has your public user interface in it. Although those two files do not use the most recent reCAPTCHA API, they are easier to implement and will still work just fine.
  5. In the captcha.php file, paste in your secret and site keys to the indicated spots.
  6. Open your public user interface file. Paste the following under where it says “Part to be executed if FORM has been submitted:” include('captcha.php'); if ($resp != null && $resp->success) { (screenshot)
  7. Place a } at the end of the text block in the example photo: (screenshot)

This is the most basic way to get the new Google reCAPTCHA working on your YOURLS instillation. Although it will prevent spam bots from submitting automated requests, if a user fails to fill out the captcha, unfortunately, a reason to why the request failed will not be given unless more code is added.

Tutorial written by Jared Stark for

Short URL to this post:

YOURLS 1.7 and social bookmarklets

Last post in our series “What’s cool with YOURLS 1.7” — be sure to check previous posts dealing with SQL injections, security matters, HTTP improvements and other important subjects.

Today we’ll discuss about being social.

Social Bookmarklets

Bookmarklets have been polished and you have now 3 more to use. Head to the Tools page of your YOURLS install and you will discover these new buttons:


These bookmarklets will allow you to shorten a URL and share that short URL to Twitter, Facebook or Tumblr, all in one click. For extra goodness, you can also select text on the page you’re shortening before clicking the bookmarklet, and if the social site allows it, that text will serve as a highlight for your shared bit. Try it!

Oh, and of course, if you share links on social networks this way, be sure to tell your friends about YOURLS! :)

Happy shortening !

This ends the tour of new features in YOURLS 1.7. Have fun using it, shorten URLs like it’s your birthday, star the project on Github, follow @yourls for general YOURLS news and tell your friends about it.

Depending on feedback we may release a 1.7.1 if and when we feel it’s necessary. The next batch of features that will make it into 1.8 and 2.0 are currently being under development and, as usual, there is *no ETA* :)


Short URL to this post:

YOURLS 1.7 and automatically encrypted passwords

Another day, another highlight of a new feature in YOURLS 1.7. In case you weren’t there when the party started, we already covered defense against SQL injections, HTTP requests robustness, funky UTF8 charsets support, proxy support, automatic checking for a new version and a few other neat stuff.

Today will be about increased security of your credentials with automatic password encryption.

Password encryption ?

When you set up YOURLS for the first time, or when you add a new user, you edit your config.php and add a user and a password. Something like:

$yourls_user_passwords = array(
	'joe' => 'MyPassword',

Simple and easy. Now, the thing is: if someone sees that file for whatever reason, they know your YOURLS password (which is the same for most of your other stuff online, admit it).

Previously in YOURLS you could manually hack the config file to encrypt yourself passwords, using a salt and a MD5 hash. Near perfect and practically undecryptable, except that whenever something has to be done manually, well, it has to be done. And you don’t do it.

We’ve improved things in YOURLS 1.7 : encryption is now automatic.

Automatic password encryption !

After you’ve edited your config file, simply use YOURLS. Next time you’ll check your config.php, instead of a clear text password, you’ll see something like this:

$yourls_user_passwords = array(
    'joe' => 'phpass:!2a!08!gRCCvpvK22BgiNzN9q9fXOnjCXqjk88aQoZP/P0wydAj7bB2',

What happened? Using a military grade encryption library, YOURLS has silently encrypted your password to something completely and absolutely unbreakable.

Your password remains unchanged when you want to use it, so your YOURLS install is still as private as your password is secure, but that password does not exist any longer in clear text.

If you need to change your password, simply edit your config file again with a new password, and next time YOURLS will run, it will simply encrypt it again. Don’t want that to happen, for some and probably bad reason? No problem, just add define( 'YOURLS_NO_HASH_PASSWORD', true ); to your config file and you’re done.

If you have any question or problem with that feature, be sure to first check the wiki about YOURLS Usernames & Passwords.

Next time: social bookmarklets and other miscellaneous goodness.

Short URL to this post:

On YOURLS 1.7 and

In case you missed it earlier: YOURLS 1.7 is out, and I’ve started a series of posts explaining why it’s twice greater than the Great Wall of China.

Previous posts explained how protecting against SQL injections is cool, and how better HTTP requests are neat. Today, let’s discuss how awesome it is to chit chat with

“Update, dude”

One image is better than 1000 words, they say, so here’s one image:

Update, dude!

This is what you’ll see now when there’s a new version of YOURLS and you’re missing the party. That, my dear estimated YOURLS user and fan, is awesome. Since we’re now sure you won’t be missing the next update, we’ll be much less reluctant to push a X.Y.1 release when we’ve fixed a tiny annoying bug.

Your own YOURLS setup will be now chatting with the mothership (aka when it gets bored, and telling you about a new version as soon as it is available is only the visible part of the feature.

YOURLS phone home

Just like E.T., YOURLS will now phone home. What does that mean exactly?

It means that your YOURLS setup will, along with checking once in a while if there’s a new version, send a few stats to the mothership to help us understand how you have installed YOURLS and how we can improve things in the future. These stats will provide us tremendously useful insights and facts, and I’m not overstating this.

At the moment, several stats are collected, and this number will most likely decrease with every new version. Only a few hundred installs have checked in, and things will widely change as many more install YOURLS, but here are the current trends:

  • Less than 9% of you are running PHP 5.2. This is very good news, because we want to drop PHP 5.2 support as soon as possible, and a huge surprise when compared to the whole internet or to what WordPress users are running (I’m expecting this share to go way up as more update their install, though)
  • 96% have MySQLi installed, 95% have PDO. I’m very surprised and I’m not sure what to think, since I was expecting no less than 100% here.
  • Two thirds of you don’t use any plugin. It might be an indication that YOURLS could be streamlined and go on a quick diet to move a few core features into YOURLS plugins. Or maybe it just means that 66% of you just find it perfect as it is.
  • 90% use the default English locale. I think this shows we’re not promoting enough the existence of translations for YOURLS, in your language. Si. Da. Oui.
  • The average domain length running YOURLS is 11.8 characters, shortest being 5 (xx dot xx), longest being 55 and a proof that some of you are running YOURLS with completely unexpected use case (I mean, I would have imagined the whole point of running a URL shortener would be to run it off something already short, right?)
  • 51% of you have more than 1 user defined, so they’re obviously a need for user management, and this will help us eventually prioritize that feature

Future stuff from the mothership

At the moment, checking for a new version is the main job of the API server. There are a few other API available, and the list will grow with more services, the obvious one being to check for plugin updates.

Feel free to use these API in your scripts and apps, and if you have any question about usage or any issue with using it, open an issue here.

Thank you for your cooperation !

From now on, an easy way to contribute to YOURLS is to simply run YOURLS, since, doing so, you’re sending these stats that will help us make good design decisions in the future.

I can’t express it enough: this will be tremendously useful for us.

Nothing sensitive is sent (no login, no password, no cookie key) and, of course, everything collected shall be made public, for everyone’s benefit. Once we have enough stats to make numbers a bit more reliable (a couple thousands I’d say), we’ll figure a way to share them, probably on

But, you know, privacy!?

No sweat, we got you covered.

We know some of you just don’t like to report anything about their install, because they’re working on a super top secret project, or because they’re high profile military spies, or because they’re just folks with no other valid reason that they want to do it.

If you want your YOURLS install to skip phoning home, just add the following line at the end of your config.php:

define( 'YOURLS_NO_VERSION_CHECK', true );

No more checking for new version, no more sending super secret stats. Please do this only if you believe you have a reason to do this, as we’d rather have your stats in: the more we get, the more we can make out of it.

That’s it for today’s highlight! Feel free to ask here in the comments any question on this particular topic. Next time, next cool feature: username encryption!

Short URL to this post:

What’s new in YOURLS 1.7 : better HTTP requests handling

As you may know, YOURLS 1.7 was released a couple days ago (announcement). I promised a few blog posts highlighting the goodness and new features this version brings, so let’s get started.

Besides better protection against potential SQL injection attacks and overall security measures, what’s new in YOURLS 1.7?

Better HTTP requests handling

Instead of a half-baked home-grown set of functions to perform HTTP requests, YOURLS is now using the awesome PHP library Requests.

“Yeah, err, probably cool”, you’re thinking, “but how exactly is that useful for me?” I hear you, let me elaborate.

Proxy support

The first direct benefit for you, kind user, is that YOURLS is now proxy-compatible, and you can install it behind a proxy or firewall. The will primarily interest corporate users or anyone setting up a YOURLS shortener in a corporate environment. If you’re into this, be sure to check the documentation: YOURLS proxy support.

By the way, this is an excellent example of how open source projects can cross-pollinate each others. Requests is an excellent library I wanted to use, I contributed to it to add proxy support, and now it powers the inners of YOURLS.

Better support for UTF8 titles

There’s a more direct benefit for the masses of that HTTP request handling improvement. Now, YOURLS should more reliably fetch titles from pages you’re shortening, no matter how ẘεḯґ∂ and ḟüᾔḱƴ character set they’re using.

You mean people write like this? OMG.

This should work better than ever, with most combination of charsets, as declared by HTML pages or by server header.

Interactions with

And that is the one feature I’m particularly in love with. It’s so neat, it deserves its own blog post. Next time!

Short URL to this post:

YOURLS 1.7 “Tom Araya” released

I’m pleased to announce the release of YOURLS 1.7 “Tom Araya”

\m/ Tom Araya \m/

In our now centennial tradition of naming YOURLS releases after a metal vocalist, I’m dedicating this release to Tom Araya, from the most excellent badass old-school thrash band we all love, Slayer. Well, vocalist, or maybe screamist, you be the judges :) Before you continue reading, feel free to crank up some good ol’ relaxing tune.

Update now. Seriously, now\’;UPDATE `your_table` WITH `crap`

YOURLS 1.7 brings several exciting new features, and I will cover major ones in an upcoming series of short blog posts. If you’re of the TL;DR type, check the changelog.

The first feature I want to highlight is not even a feature, it’s a bugfix: in YOURLS 1.7 we have scrutinized several aspects regarding security and we have fixed a potential SQL injection vulnerability.

If you run YOURLS for your own and only use, update ASAP, but if you run a public URL shortener, update riiiiiiiiiiight nooooooooooooow (read that in Tom Araya’s voice to get the feeling)

This update is a simple drop-in replacement: download the latest archive, unzip and upload to your server, overwriting existing files. No update procedure, no DB upgrade.

Update as soon as you can, and do your friends a favor: tell them a new version of YOURLS is out and they should update, tweet and retweet the good word.

Speaking of tweets

A quick note regarding tweets: @yourls used to broadcast boring nerd stuff, aka commit messages. No more boring stuff, it’ll be limited to YOURLS news of general interest. The hardcore nerd herd can follow @yourls_dev instead, where you’ll get an idea of the coding activity and pace.

Executive summary

Update now. Blog posts about awesome features in the next days.

Short URL to this post:

YOURLS 1.6 “Till Lindemann” released

I’m thrilled to announce the release of YOURLS 1.6 “Till Lindemann”

\m/ Rammstein \m/

YOURLS released are named after a (metal) music celebrity I like and I thought a non English singer would particularly suit the main feature of this release. If you’re not familiar yet, please meet Till Lindemann, charismatic leader and vocalist of the awesome Rammstein :)

مرحبا العالم! Hej verden! 你好世界! Kumusta mundo! Ciao mondo! Hello world!

The main feature of YOURLS 1.6 is that it’s now fully translatable. Yes! Si! Oui! You can now install and use YOURLS in the language of your choice! When the language of your choice is available, that is :) As of writing there are 6 languages but that list will grow as translators will raise their hand.

If you want to translate YOURLS in your dialect: this is easy. Refer to the wiki page YOURLS in your language.

Lots of cool stuff!

On top of speaking Polish and soon Mandarin, YOURLS 1.6 brings other cool features: the usual bugfix load, security improvements, the ability to define custom API actions and to shorten URLs with other common protocols than just http, like this one. By the way, if you are running a public YOURLS install, you will want to read this: on Public Shortening.

Another new thing you may have noticed is that YOURLS development now happens on Github. Long story short: I want to learn Git on a real scale project, I dig Git’s branching, and I’m curious to see if that will bring more contributions.

And speaking of which… I’m excited to announce that the YOURLS team is finally… a team! Let me introduce Léo, who has come up with nice patches, cool suggestions and fantastic ideas. With the help of Léo as a core committer, expect the development pace to raise from… real slow? to, err… somehow faster! :)

Update now!

Don’t wait a minute: get YOURLS 1.6 and update: delete all your files except your config.php and your /user directory — or simply overwrite, and you’re good to go!

Short URL to this post:

Getting spam links in YOURLS? Read this.

I regularly get reports or call for helps about YOURLS installs that are flooded with spam links despite being configured as private (ie constant YOURLS_PRIVATE set to true, as 99% of installs should have)

In 9 cases out of 10, the “problem” is that the user also has set up an unprotected public interface through which anyone can shorten links. Seriously. PEBKAC, really.

But a kind and smart user also brought to my attention a (stupid) server default config that can make your YOURLS install spamable: on some machines, filename.php.txt is interpreted as a PHP file instead of a text file.

In other words, when loading sample-public-front-page.php.txt in your browser, instead of seeing code in a text file, you might see this:


Check right now that your server is properly configured. If that’s not the case, delete or rename those *.php.txt files and poke your server admins because I’m pretty sure that’s not how a web server is supposed to run.

Note: if you’re purposely running a public YOURLS install and you are getting spam, that is another matter. There are numerous anti spam plugins for YOURLS. Use them.

Short URL to this post:

Workshop: How to create your own translation file for YOURLS

Version 1.6 YOURLS is fully “localizable”, ie translatable, and the translation process itself is very simple. We’re going to create a translation file, but first, a very little theory.

A… “locale” ?

The default language of YOURLS is U.S. English (or, to be accurate and fair, it’s “Ozh English”: it’s not my mother tongue so a few sentences may be sometimes a bit le suck ; if so please correct me :)

In nerd speak, that language is called a “locale”: a combination of language (English) and regional dialect (US, you know, colors and colours). Hence, the default locale of YOURLS is en_US.

YOURLS uses translation files that contain the strings in English and in their translated form. There are 2 files: a PO file, which is human readable, and a MO file, which needs to be generated by a script or software.

In this example, I’ll show you how to generate a translation for France’s French (ie fr_FR) using Poedit, a simple PO file editor, but everything will be very similar using another desktop tool or web based tool such as

Generate your translation file

  1. Install Poedit. Small download, simple install, no configuration, cross platform, free.
  2. Download the YOURLS.pot template file, rename it to fr_FR.po
  3. Open your fr_FR.po with Poedit
  4. Optional : fill in some translation details. To do so: click Catalogue / Properties. Leave other fields untouched, you don’t need them.
  5. Start translating. It’s really just about entering translated text in the Translation field. Be sure to copy any HTML tag, punctuation or seemingly cryptic bits such as %s that will be replaced within YOURLS by non translatable text (a URL for instance).
  6. Once you’re done, save your work: Poedit will save your modified fr_FR.po file, which is the human readable translation file, and will generate a file, a machine readable file and what YOURLS need to translate strings.

YOURLS 1.6 contains about 270 translatable strings. Some are very short (one or a couple of words), some a longer sentences, but overall the process isn’t too long or cumbersome. As an example, creating the complete French translation, fine tuning it (and fixing a couple YOURLS bugs by the way) then creating a repository to host the files took me roughly 75 minutes.

Check and fine tune your translation file

Test your file to check translations perfectly fit the context they are used in:

  1. in your config.php, add or edit the following:
    define( 'YOURLS_LANG', 'fr_FR' );
  2. drop the two PO and MO files in user/languages
  3. Play with YOURLS and check all pages and possible uses (shorten link, edit and delete stuff, etc…)

Distribute your files

Last step: make sure others can benefit from you hard work!

  1. Upload your two PO and MO files somewhere on the interweb. I recommend using a source controlled service, such as Github: this will make your changes easy to track, your files easy to maintain, and others’ contributions easy to implement. If you don’t want to use SVN or Git, a regular hosting (your blog) will be fine
  2. Ping us! Open a pull request on awesome-yourls and tell us where your translation lives.

A list of available translations will be maintained.

Protips: what makes a good translation ?

Be fluent.
To be a good translator, you need to be very comfortable with English and the language you’ll translate to. Casual knowledge of one or both will result in a translation that will most likely sound awkward or unnatural to native speakers. In other words: this.

Don’t translate literally.
Maybe the English sentence will have a 2 part structure that won’t sound natural in your language, maybe a longer sentence or 3 smaller sentences will sound better. Adapt, refine, make it sound natural.

Keep the same tone
Some messages are very formal (eg “URL invalid” as an operation result) and some are less formal. Keep the same level of formality or informality, as it depends on the context in which string will be used.

Don’t over translate.
Some English words have become common enough that it may sound weird to translate them. For instance, it’s up to you to determine if “plugin” or “bookmarklet” have to be translated or if those words are better as is.

Bonus: Protips using Poedit

Hitting Control + Enter or Control + Down arrow will navigate to the next untranslated string. Hitting Control B will copy the source (untranslated) text to the Translation box, which can be handy if you have a few HTML tags to re-use.

Sometimes the Translation field will show a split field: it means you need to enter the singular and plural form of a sentence.

Sometimes you will also get a few hints in the Notes for translators area: these comments will help you understand the context of a string and help you pick the best translation.

Short URL to this post:

YOURLS 1.6 : translators wanted !

Change of plans for YOURLS 1.6. According to the RoadMap and previous posts here, the upcoming version 1.6 of YOURLS would introduce a new DB schema. But plans are made to be changed!


Localization has always been a long wanted feature for YOURLS (issue #58, opened more than 3 years ago in September 2009). It has always been planned, but low priority. Then, two things happened.

First, a couple month ago, I had to set up a YOURLS instance on a French corporate intranet. It immediately occured to me that the lack of translation API was going to make things a little more complicated than expected, given all the strings that were hardcoded in English. I always picture individual users such as myself not having a problem using simple software in English, but it’s a little different when you have to deal with a larger non-techie population.

Second, recently, @LeoColomb, a long time YOURLS user and prolific hacker, threw a patch in my face with the first draft of the translation API. Yep, in my face!

So, I decided to prioritize that feature. Over the last few days the committing pace has been unusually hectic and as of now, labelled 1.6-polyglot, YOURLS is ready to be fully translated.

Translators Wanted!

What does “ready for translation” mean exactly?

Instead of having hardcoded strings, such as echo "Woah awesome" and return "You are nice", YOURLS now uses the very common gettext functions, and you’ll see code like yourls_e( 'URL added' ) and return yourls__( 'You are nice' );. These functions search for the translated string in a translation file, if available, or otherwise return the original string.

More detailed documentation to help translators will be written later, but it’s a really straightforward simple process:

  1. Download YOURLS.pot, the translation file template
  2. Rename it to [your-locale].po, where [your-locale] is typically language code, underscore, country code (for instance in Portugal that would be pt_PT, while in Brazil it’d be pt_BR).
  3. Install a translation software: it’s nothing more than a text editor capable of reading .po files, showing you the untranslated string and a text box where you type in the translation, and saving a .mo file which is what PHP needs. A cross platform, simple yet complete editor is Poedit. There are also simple web based tools, such as PoEditor where you upload the .pot, translate, and download a .mo
  4. Once you have your fully translated pt_BR.po and the generated, host them somewhere (preferably on a source control enabled environment such as Github or Google Code to make contributions easier) and ping me! I’ll maintain a list of available translations.

To test your translation file as you create it :

  1. Download a nightly build or update via SVN
  2. Drop your pt_BR.po and files in user/languages
  3. Add define( 'YOURLS_LANG', 'pt_BR' ) to your config.php
  4. That’s it! Play with YOURLS

Translators, it’s important you join the party early: you’ll help us make sure the translation API works as smooth as expected, and win the “First YOURLS Translation Ever” award :)

What’s the Roadmap, then ?

On top of localization, which not everyone gets excited about, YOURLS 1.6 will bring the usual load of bugfixes and little enhancements. Better URL sorting and searching in the admin interface, more filters and actions to allow for more flexible and powerful plugins, a smarter API, better security and sanitization functions, plus more awesome and more w00t.

As usual, no ETA, but we’re speaking probably a couple weeks here. It really depends on the translator feedback.

Then it will be time to work on YOURLS 2.0 with the much awaited and needed DB structure change, and more goodness you’ll be able to handle. From a semantic versionning point of view, it just made sense anyway to give such a change its own major release number rather than a simple dot release.

There are even more news to share, but that’ll be another post :)

Short URL to this post: