YOURLS: Your Own URL Shortener

	
	

		
More
		
FAQ
		
API
		
WordPress plugin
		
YOURLS plugins
		
Configuration
		
Install/Upgrade
		
About
	

	
	

		
		

			
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
			

				
Private (your links only) or Public (everybody can create short links, fine for an intranet)
				
Sequential or custom URL keyword
				
Handy bookmarklets to easily shorten and share links
				
Awesome stats: historical click reports, referrers tracking, visitors geo-location
				
Neat Ajaxed interface
				
Terrific Plugin architecture to easily implement new features
				
Cool developer API
				
Friendly installer
				
Sample files to create your own public interface and more
			
			
			
Screenshots
			
			

				
Main admin dashboard
				
				
				
Stats for each short URL
				
				
				
See a live example of YOURLS stats on http://yourls.org/download+
			
			
			
Download
			
			
Download YOURLS from Google Code
			
You can follow YOURLS' development on the revision list and get current snapshot using SVN
			
			
Credits
			
			
YOURLS is made by:
			

				
Lester Chan &ndash @GamerZ on Twitter (initial idea)
				
Ozh Richard &ndash @Ozh on Twitter (development)
			
		

		
		

			
Fresh Install
			

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

				
Backup the database!
				
Unzip the YOURLS archive
				
Upload files to your server, overwriting your existing install
				
Point your browser to http://yoursite.com/admin/
				
Tip: you can now move your config.php file to the /user directory
			
			
			
Upgrade from YOURLS 1.3 or earlier
			

				
Backup the database!
				
Make a copy of your config.php
				
Delete all files including .htaccess in YOURLS root directory
				
Unzip the YOURLS archive, upload the files
				
Copy config-sample.php to config.php and fill in details. Don't start with your old config file, use the new sample config file.
				
In your new config.php, add the defines for YOURLS_DB_TABLE_URL and YOURLS_DB_TABLE_NEXTDEC you had in your previous config file
				
Point your browser to http://yoursite.com/admin/ and follow instructions
				
After upgrade is well and over, remove the define YOURLS_DB_TABLE_NEXTDEC from your config file
			
			
		

			
		

			
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_PREFIX

				The name prefix for all the tables YOURLS will need

				Example: 'yourls_'
			
			
			
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 (on an intranet for instance)

				Example: 'true'
				
YOURLS_UNIQUE_URLS

				Allow multiple short URLs for a same long URL

				Set to true to allow only one pair of shortURL/longURL (default YOURLS behavior), or to false to allow creation of multiple short URLs pointing to the same long URL (as bit.ly does)

				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/cookie

				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'
			
			
			
Optional settings
			

				
YOURLS_PRIVATE_INFOS

				If YOURLS_PRIVATE is set to true, you can still easily make your individual stat pages public. To do so, override the global private setting with:

				define('YOURLS_PRIVATE_INFOS', false);
				
				
YOURLS_PRIVATE_API

				If YOURLS_PRIVATE is set to true, you can still easily make your API public. To do so, override the global private setting with:

				define('YOURLS_PRIVATE_API', false);
				
YOURLS_NOSTATS

				If YOURLS_NOSTATS is set to true, redirects won't be logged and there will be not stats available.

				
			
			
			
Advanced settings
			
File includes/yourls-load.php contains a few more undocumented but self explanatory and commented settings. Add them to your own config.php if you know what you're doing
		
		
		
		

			
WordPress Plugin
			
			
Features
			

				
Generate short URLs for each new post or page
				
Generate short URLs for all your old posts and pages if wished
				
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
			
			
			
Screenshot
			

			
			
			
			
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
			
		
		
		
		
		

			
Plugins for YOURLS
			
			
Plugins?
			
Plugins are additional PHP scripts that extend the functionalities or features of YOURLS. The core of YOURLS is designed to be as light as possible and avoid bloat (implementing functions not everybody needs) and to allow for easy customization.
			
Using the plugin architecture, you can add new features to YOURLS without having to modify core files. This way, your changes won't be lost when you upgrade your YOURLS installation.

			
Documentation
			
Several sample plugins are included in the archive. Read the source and learn the concept. It's easy and fun!
			
Check the plugin API documentation to learn more
		
		
		
		
		

			
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
				
Authentify either with login/password or using a secure passwordless mechanism
			
			
			
Usage
			
You need to send parameters to http://yoursite.com/yourls-api.php either via GET or POST. These parameters are:
			

				
A valid username / password pair, or your signature (see Passwordless API requests)
				
The requested action: "shorturl" (get short URL for a link), "expand" (get long URL of a shorturl), "url-stats" (get stats about one short URL) 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 = "expand" :
					

						
the shorturl to expand (can be either 'abc' or 'http://site/abc')
						
output format: either "json", "xml" or "simple"
					
				
				
With action = "url-stats" :
					

						
the shorturl for which to get stats (can be either 'abc' or 'http://site/abc')
						
output format: either "json" or "xml"
					
				
				
With action = "stats" :
					

						
the filter: either "top", "bottom" , "rand" 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
			

				
A server with mod_rewrite enabled
				
At least PHP 4.3
				
At least MYSQL 4.1
				
Note: YOURLS can also run on Nginx and Cherokee
			

			
Server recommendations
			

				
PHP CURL extension installed if you plan on playing with the API
			
			
			
Limitations
			

				
Maximum length of long URLs to be shortened is 2000 characters
				
Maximum length of custom keyword is 200 characters
				
That makes about 8 sexdecillions of centillions of available URLs (seriously. That's a 355 digits number). 
			
			
			
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 is the default and should be picked.
			
			
			
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
				
Make sure your .htaccess file looks like this one
			
			
			
Feedback, feature requests and bug reporting
			

				
Please don't get in touch directly by mail or Twitter. Please.
				
Check the Road Map for future features
				
Raise an issue here and give all the details. Thanks!
			

		
		
		
					
		

			
Showcase

			
Here are a few examples of sites running YOURLS with a unique design or concept
			
			

				
http://mrte.ch/

				Mr Tech's public YOURLS setup, listing top links and some stats
				
http://xib.me/

				A nicely styled YOURLS public interface
				
http://s4c.in/

				Shorten 4 Charity, a public YOURLS setup with shortened links displayed within a frame containing ads for charities	
				
http://girv.in/

				John Girvin's YOURLS setup with all links in a sortable display
				
http://www.iyeman.net/

				Example of portal for your online self with links to your places (blog, Twitter) and your URL shortener
				
http://vb.ly/ (early adopter, now defunct)

				Public YOURLS setup run by famous sex writer Violet Blue as "the internet's first and only sex-positive url shortener"
			
			
			
More stuff about or with YOURLS
			
			

				
http://screenr.com/nTs

				A screencast explaining how to setup YOURLS
				
				
YOURLS: Short URL Widget

				Creates a fully configurable widget that outputs the short URL to the current post or page
				
				
YOURLS Widget for WordPress

				This widget adds a convenient short URL service into your sidebar. Check the above link for a live example
				
				
Twitter Tools & YOURLS

				Companion plugin for Alex King's Twitter Tool for WordPress, that enables YOURLS support
				
				
WWW-Shorten-Yourls

				A Perl module to shorten URLs using YOURLS
				
				
YOURLS Ruby

				A Ruby wrapper for the YOURLS API
				
				
Textexpander and YOURLS

				Making YOURLS and Textexpander on the Mac play together
				
				
YOURLS and Tweetie 2

				How to set up Tweetie2 so it uses your own service
				
				
YOURLS and TweetDeck

				How to set up TweetDeck so it uses your own service
				
				
YOURLS with Movable Type

				Twitter Tools for Movable Type supports custom YOURLS setup
				
				
YOURLS hacks

				Hacks to enhance YOURLS for spam control/throttling, unshortening and weekly stats
				
				
Export URLS as text list

				A simple script to list all URLs, one per line, in plain text (for using as an indexer config file, for example)
				
				
YOURLS featured on Lifehacker
			

		
	
 
 

YOURLS: Your Own URL Shortener
All Free & GPL – 2009