YOURLS 1.7.1

Hello world! Your favorite URL shortener just got some love and the latest is now YOURLS 1.7.1. Update and let your friends know!

What’s new? Lots of bug fixes, lots of improvements, nothing that will rock your socks in awe, but several things you won’t notice because they just work better :) See the changelog for more details.

How to update? If updating through the command line is too hardcore for you, just download the archive and overwrite your existing install. This update doesn’t contain anything scary, but of course that’s no reason not to have a proper backup of your data from time to time, right? :)

What’s next? We’ll continue our slow trip down the road map but the most noticeable change for a few of you will be that we are going to start breaking things!

  • we’re dropping PHP 5.2 support. As of today 3.8% of all YOURLS installs run this super deprecated PHP version: folks, please.
  • We’ll probably drop MySQL support as well. An overhaul of the DB stuff has been planned for long, MySQL is deprecated in newer PHP builds, so we’ll very most likely switch to PDO. Sorry for the 1.9% of you that don’t have PDO installed on their server, but that is not something that’s acceptable from a decent web host :)

Update and tell your friends and family to update too!

Short URL to this post:

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 Google Code or 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 me! Open a new issue on YOURLS.pot and tell us where your translation lives. It must be a directory, or a page listing available translations, not a specific single file.

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: