{"id":3945,"date":"2026-06-23T11:10:00","date_gmt":"2026-06-23T09:10:00","guid":{"rendered":"https:\/\/planetozh.com\/blog\/?p=3945"},"modified":"2026-06-23T11:10:00","modified_gmt":"2026-06-23T09:10:00","slug":"allowing-weird-characters-in-yourls-short-urls","status":"publish","type":"post","link":"https:\/\/planetozh.com\/blog\/2026\/06\/allowing-weird-characters-in-yourls-short-urls\/","title":{"rendered":"Allowing weird characters in YOURLS short URLs"},"content":{"rendered":"

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

The short answer is "use the get_shorturl_charset<\/tt> 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.<\/p>\n

The easy case: the hyphen<\/h2>\n

YOURLS ships with a bundled core plugin for the hyphen, and it's trivial code: basically add -<\/tt> to the allowed character set.<\/p>\n

\n\n\t\t
\n\n\t\t
\n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
php<\/div>\n\n\t\t\n\t\t
\n\n\t<\/div>\n\t\n\t
\n\t\t
  1. \/\/ Add hyphen to the allowed character set<\/div><\/li>\n
  2. yourls_add_filter( 'get_shorturl_charset', 'ozh_hyphen_in_charset' );<\/div><\/li>\n
  3.  <\/div><\/li>\n
  4. \/\/ Unless we are crafting a random keyword<\/div><\/li>\n
  5. yourls_add_action( 'add_new_link_create_keyword', function() {<\/div><\/li>\n
  6.     yourls_remove_filter( 'get_shorturl_charset', 'ozh_hyphen_in_charset' );<\/div><\/li>\n
  7. } );<\/div><\/li>\n
  8.  <\/div><\/li>\n
  9. function ozh_hyphen_in_charset( $in ) {<\/div><\/li>\n
  10.     return $in . '-';<\/div><\/li>\n
  11. }<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

    So, a lot of people starting to build on this, to add any custom char. The thing is a bit more complicated.<\/p>\n

    Then someone asks for a colon<\/h2>\n

    When YOURLS instantiates, amongst first things it evaluates the "request", ie the abc<\/tt> part in sho.rt\/abc<\/tt>.<\/p>\n

    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\/<\/tt>. When abc is a non ambiguous request, now having a colon becomes ambiguous because it looks like a URL:<\/p>\n

    \n\n\t\t
    \n\n\t\t
    \n\t\t\t\t\t\t< View plain text<\/span> ><\/a>\n\t\t\t\t\t<\/div>\n\n\t\t
    php<\/div>\n\n\t\t\n\t\t
    \n\n\t<\/div>\n\t\n\t
    \n\t\t
    1. $request = yourls_get_request();<\/div><\/li>\n
    2.  <\/div><\/li>\n
    3. \/\/ if request has a scheme : send to bookmarklet<\/div><\/li>\n
    4. if ( yourls_get_protocol( $keyword ) ) {<\/div><\/li>\n
    5.     \/\/ ... redirect to \/admin\/index.php?...<\/div><\/li>\n
    6.     yourls_redirect( \/* admin *\/, 302 );<\/div><\/li>\n
    7.     exit;<\/div><\/li>\n
    8. }<\/div><\/li>\n<\/ol>\t<\/div>\n\n<\/div>\n\n

      The plugin to allow colon<\/h2>\n

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

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

        The logic of the get_protocol filter, in plain English:<\/p>\n