YOURLS 4 min read

Allowing weird characters in YOURLS short URLs

By Ozh

One of the most recurring support requests we get for YOURLS goes like this: "How do I get a - (or a /, or a :) into my keywords?" People want pretty customshort URLs like sho.rt/my-talk or sho.rt/v2:final, and by default YOURLS won't let them.

The short answer is "use the get_shorturl_charset filter." The long answer is that, depending on the character, that filter is either the whole solution or just the start of one. Here's why, with the colon as the interesting case.

The easy case: the hyphen

YOURLS ships with a bundled core plugin for the hyphen, and it's trivial code: basically add - to the allowed character set.

< View plain text >
php

  1. // Add hyphen to the allowed character set
  2. yourls_add_filter( 'get_shorturl_charset', 'ozh_hyphen_in_charset' );
  3.  
  4. // Unless we are crafting a random keyword
  5. yourls_add_action( 'add_new_link_create_keyword', function() {
  6.     yourls_remove_filter( 'get_shorturl_charset', 'ozh_hyphen_in_charset' );
  7. } );
  8.  
  9. function ozh_hyphen_in_charset( $in ) {
  10.     return $in . '-';
  11. }

So, a lot of people starting to build on this, to add any custom char. The thing is a bit more complicated.

Then someone asks for a colon

When YOURLS instantiates, amongst first things it evaluates the "request", ie the abc part in sho.rt/abc.

One of the handy bookmarklets YOURLS has is the "Prefix-n-Shorten" mechanism: just prepend your YOURLS URL to a long URL and shorten it on the fly. So the request can be a full URL, such as sho.rt/https://longurl.com/. When abc is a non ambiguous request, now having a colon becomes ambiguous because it looks like a URL:

< View plain text >
php

  1. $request = yourls_get_request();
  2.  
  3. // if request has a scheme : send to bookmarklet
  4. if ( yourls_get_protocol( $keyword ) ) {
  5.     // ... redirect to /admin/index.php?...
  6.     yourls_redirect( /* admin */, 302 );
  7.     exit;
  8. }

The plugin to allow colon

Because everything funnels through yourls_get_protocol(), and because that function is filterable (it ends with yourls_apply_filter( 'get_protocol', ... )), one filter fixes the whole chain. The trick is to teach get_protocol to recognize our own keywords and refuse to treat their colon as a scheme.

< View plain text >
php

  1. // Add the colon to the allowed short URL character set...
  2. yourls_add_filter( 'get_shorturl_charset', 'ozh_colon_in_charset' );
  3. function ozh_colon_in_charset( $charset ) {
  4.     return $charset . ':';
  5. }
  6.  
  7. // ...unless we are crafting a random keyword, to keep auto-generated keywords colon-free
  8. yourls_add_action( 'add_new_link_create_keyword', function() {
  9.     yourls_remove_filter( 'get_shorturl_charset', 'ozh_colon_in_charset' );
  10. } );
  11.  
  12. // Don't let a keyword that contains a colon be mistaken for a URI scheme
  13. yourls_add_filter( 'get_protocol', 'ozh_colon_get_protocol', 10, 2 );
  14. function ozh_colon_get_protocol( $protocol, $url ) {
  15.     // Nothing was detected as a protocol: leave as is
  16.     if ( $protocol === '' ) {
  17.         return $protocol;
  18.     }
  19.  
  20.     // A genuine "scheme://..." URL (eg a bookmarklet target): leave as is
  21.     if ( str_contains( $protocol, '/' ) ) {
  22.         return $protocol;
  23.     }
  24.  
  25.     // Here $protocol is a bare "scheme:" with no slashes. If the whole candidate
  26.     // string consists only of valid short URL charset characters, it's one of our
  27.     // keywords (eg "foo:bar"), not a URL: don't treat the colon as a scheme.
  28.     $pattern = yourls_make_regexp_pattern( yourls_get_shorturl_charset() );
  29.     if ( ! preg_match( '@[^' . $pattern . ']@', $url ) ) {
  30.         return '';
  31.     }
  32.  
  33.     return $protocol;
  34. }

The logic of the get_protocol filter, in plain English:

  • No scheme detected? Leave it alone.
  • The detected scheme contains a slash (http://)? That's a real URL, leave it alone.
  • A bare scheme: with no slashes, and the entire candidate string is made only of charset characters? That's one of our keywords – return '' so the colon stops being read as a scheme.

Real URLs survive because they contain a /, a ., an @, or some other character outside the keyword charset, so they fail that last test and keep their protocol. The bookmarklet still works.

The colon plugin is available here if you want to drop it into user/plugins/ and go: Allow Colon in YOURLS short URL.

The one limitation

If you try to shorten a URL whose entire string fits inside the keyword charset plus the colon – think tel:123 or urn:isbn – the plugin will neutralize its scheme and treat it as a keyword. In practice this should not happen, as any realistic URL you'd shorten contains a /, or a . somewhere, which puts it safely outside the charset. But it's worth knowing it's there.

Bonus: which other characters will make tricky keywords?

A few chars will be reinterpreted somewhere down the pipeline starting at yourls-loader.php in the root: ?, + and / will be special cases to handle differently.

Some are modified, or destroyed by the browser, or at the HTTP layer before they reach YOURLS: #, spaces, \, %, so they should never be used at all in keywords.

Leave a Reply

Your email address will not be published. Required fields are marked *