YOURLS: Your Own URL Shortener (and a WordPress plugin)

About YOURLS

What is YOURLS

YOURLS is a small set of PHP scripts that will allow you to run your own URL shortening service (a la TinyURL). You can make it private or public, you can pick custom keyword URLs, it comes with its own API. You will love it.

There's a WordPress plugin available for YOURLS, making integration with your blog a snap: create short URLs and tweet them automagically as you publish blog posts.

YOURLS Features

• Public (everybody can create short links) or private (your links only)
• Random (sequential) or custom URL keyword
• Track click count on your links
• Neat AJAXed interface
• Developer API

Screenshots

Download

Download YOURLS from Google Code

Credits

YOURLS is made by:

• Lester Chan &ndash @GamerZ on Twitter
• Ozh RICHARD &ndash @Ozh on Twitter

Installation Instructions

1. Unzip the YOURLS archive
2. Copy includes/config-sample.php to includes/config.php
3. Open includes/config.php with a raw text editor (like Notepad) and fill in the required settings
4. Upload the unzipped files to your domain public_html or www folder
5. Create a new database (see Configuration – you can also use an existing one)
6. Point your browser to http://yoursite.com/admin/install.php

Configuration (in includes/config.php)

MySQL settings

• YOURLS_DB_USER
  your MySQL username
  Example: 'joe'
• YOURLS_DB_PASS
  your MySQL password
  Example: 'MySeCreTPaSsW0rd'
• YOURLS_DB_NAME: The database name
  Example: 'yourls'
• YOURLS_DB_HOST
  The database host
  Example: 'localhost'
• YOURLS_DB_TABLE_URL
  The table name to store URLs
  Example: 'url'
• YOURLS_DB_TABLE_NEXTDEC
  The table name to store the next sequential link decimal id
  Example: 'nextdec'

Site options

• YOURLS_SITE
  Your (short) domain URL, no trailing slash
  Example: 'http://ozh.in'
• YOURLS_HOURS_OFFSET
  Timezone GMT offset
  Example: '-5'
• YOURLS_PRIVATE
  Private means protected with login/pass as defined below. Set to false for public usage
  Example: 'true'
• YOURLS_COOKIEKEY
  A random secret hash used to encrypt cookies. You don't have to remember it, make it long and complicated. Hint: generate a unique one at http://yourls.org/cookiekey.php
  Example: 'qQ4KhL_pu|s@Zm7n#%:b^{A[vhm'
• yourls_user_passwords
  A list of username(s) and password(s) allowed to access the site if private
  Example: 'joe' => 'mypassword'

URL Shortening settings

• YOURLS_URL_CONVERT
  URL shortening method: base 36 or 62. See FAQ for more explanations
• yourls_reserved_URL
  A list of reserved keywords that won't be used as short URLs. Define here negative, unwanted or potentially misleading keywords
  Example: 'porn', 'faggot', 'sex', 'nigger', 'fuck', 'cunt', 'dick', 'gay'

WordPress Plugin

Features

• Generate short URLs for each new post or page
• Send a tweet on your Twitter account with the post title and short URL as you publish them
• Works if YOURLS is hosted on the same server or on a remote server
• Also compatible with tr.im, is.gd, tinyurl.com and bit.ly for maximum fun

Screenshots

Download & more informations

• Download YOURLS: WordPress to Twitter from the official WordPress plugin repository
• More information, tips and feedback on the plugin page from planetOzh

YOURLS' API

Features

• Generate or get existing short URLs, with sequential or custom keyword
• Get some statistics about your links: top clicked links, least clicked links, newest links
• Output format: JSON, XML, or simple raw text

Usage

You need to send parameters to http://yoursite.com/yourls-api.php either via GET or POST. These parameters are:

• A valid username
• A valid password
• The requested action: either "shorturl" (get short URL for a link) or "stats" (get stats about your links)
• With action = "shorturl" :
  • the url to shorten
  • optional keyword for custom short URLs
  • output format: either "json", "xml" or "simple"
• With action = "stats" :
  • the filter: either "top", "bottom" or "last"
  • the limit (maximum number of links to return)
  • output format: either "json" or "xml"

Sample return

<result>
	<url>
		<id>62019439011</id>
		<keyword>shorter</keyword>
		<url>http://somereallylongurlyouneedtoshrink.com/</url>
		<date>2009-06-23 18:08:07</date>
		<ip>127.0.0.1</ip>
	</url>
	<status>success</status>
	<message>http://somereallylongurlyouneedtoshrink.com/ (ID: shorter) added to database</message>
	<shorturl>http://yoursite.com/shorter</shorturl>
</result>

Sample file

There's a sample file included that serves as an example on how to play with the API

FAQ

Server requirements

1. A server with mod_rewrite enabled
2. At least PHP 4.3
3. At least MYSQL 4.1

Server recommendations

• PHP CURL extension installed if you plan on playing with the API
• PHP BCMath extension for handling large integers (ie many (really many many) links or long custom keyword URLs)

Limitations

• Maximum length of custom keyword is 12 characters
• 4,738,381,338,321,617,846 available URLs

Difference Between Base 36 And Base 62 Encoding

• Base 36 encoding uses 0123456789abcdefghijklmnopqrstuvwxyz
• Base 62 encoding uses 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
• Stick to one setting, don't change after you've created links as it will change all your short URLs!
• Base 36 should be picked. Use 62 only if you understand what it implies.
• Using base 62 means you *need* PHP extension BCMath
• Consider Base 62 encoding a beta feature

Getting a short domain name for your YOURLS install

• Unless you plan on making it public, any shared hosting should be fine
• Domainr is a fun search tool that might inspire and help you
• Aim for exotic top level domains (.in, .im, .li ...), they're often cheap and a lot are still available. Gandi is a pretty comprehensive registrar, for instance.

YOURLS needs its own .htaccess

• You cannot install YOURLS and, say, WordPress, in the same directory. Both of them need to handle URLs differently
• If you want to install YOURLS on the same domain than your blog, give it its own (short) subdirectory, such as yourblog.com/s/ (for "short") or yourblog.com/x/ (for "exit")

If YOURLS generates 404 for your short URLs

• Make sure mod_rewrite is enabled with your Apache server
• Some crappy hosts such as GoDaddy need a small fix to .htaccess: