1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
\r
2 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
\r
4 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
\r
5 <title>YOURLS: Your Own URL Shortener (and a WordPress plugin)</title>
\r
6 <style type="text/css" media="screen">
\r
9 font-family: Verdana, Arial;
\r
12 background: #ffffff;
\r
29 margin: 10px 20px 0px 20px;
\r
31 border: 1px solid #8d8d8d;
\r
32 background-color: #f5f5f5;
\r
40 a, a:active, a:link, a:visited {
\r
42 text-decoration: none;
\r
46 text-decoration: underline;
\r
52 border:1px solid #5b87b4;
\r
56 /* Place Holder Style */
\r
60 margin-right: auto;
\r
63 background-color: #fafafa;
\r
64 border: 1px solid #a2b6cb;
\r
70 font-family: Verdana, Arial;
\r
74 border-bottom: 1px solid #2a85b3;
\r
75 margin-bottom: 10px;
\r
76 background:transparent url(http://yourls.org/images/yourls-logo.png) top center no-repeat;
\r
83 font-family: Verdana, Arial;
\r
93 font-family: Verdana, Arial;
\r
105 font-family: Verdana, Arial;
\r
108 list-style-type: none;
\r
109 padding-bottom: 28px;
\r
110 border-bottom: 1px solid #a2b6cb;
\r
111 margin-bottom: 12px;
\r
117 background-color: #deedfb;
\r
118 margin: 2px 0px 0px 5px;
\r
119 border: 1px solid #a2b6cb;
\r
125 text-decoration: none;
\r
128 #Tabs li.Tab a:hover {
\r
129 background-color: #bfe0fe;
\r
130 border-bottom: 1px solid #bfe0fe;
\r
133 #Tabs li.SelectedTab {
\r
136 background-color: #fafafa;
\r
137 margin: 2px 0px 0px 5px;
\r
138 border-top: 1px solid #a2b6cb;
\r
139 border-right: 1px solid #a2b6cb;
\r
140 border-bottom: 1px solid #fafafa;
\r
141 border-left: 1px solid #a2b6cb;
\r
143 #Tabs li.SelectedTab a {
\r
147 text-decoration: none;
\r
153 text-align: center;
\r
158 <div id="Container">
\r
160 <h1>YOURLS: <span>Y</span>our <span>O</span>wn <span>URL</span> <span>S</span>hortener (and a WordPress plugin)</h1>
\r
164 <li id="ShowcaseTab" class="Tab"><a href="#Showcase" onclick="toggle(this);">Showcase</a></li>
\r
165 <li id="FAQTab" class="Tab"><a href="#FAQ" onclick="toggle(this);">FAQ</a></li>
\r
166 <li id="APITab" class="Tab"><a href="#API" onclick="toggle(this);">API</a></li>
\r
167 <li id="PluginTab" class="Tab"><a href="#Plugin" onclick="toggle(this);">WordPress plugin</a></li>
\r
168 <li id="ConfigTab" class="Tab"><a href="#Config" onclick="toggle(this);">Configuration</a></li>
\r
169 <li id="InstallTab" class="Tab"><a href="#Install" onclick="toggle(this);">Installation</a></li>
\r
170 <li id="AboutTab" class="SelectedTab"><a href="#About" onclick="toggle(this);">About</a></li>
\r
176 <div id="AboutDiv">
\r
177 <h2>About YOURLS</h2>
\r
179 <h3>What is YOURLS</h3>
\r
180 <p>YOURLS is a small set of PHP scripts that will allow you to run your own URL shortening service (<em>a la</em> TinyURL). You can make it private or public, you can pick custom keyword URLs, it comes with its own API. You will love it.</p>
\r
181 <p>There's a <a href="#Plugin" onclick="toggle(this);">WordPress plugin</a> available for YOURLS, making integration with your blog a snap: create short URLs and tweet them automagically as you publish blog posts.</p>
\r
182 <p>YOURLS is in early stages of its life. While functional, it regularly evolves and improves. Please keep current and up to date to get the most of it</p>
\r
184 <h3>YOURLS Features</h3>
\r
186 <li>Public (everybody can create short links) or private (your links only)</li>
\r
187 <li>Random (sequential) or custom URL keyword</li>
\r
188 <li>Handy bookmarklet to easily shorten and share links</li>
\r
189 <li>Track click count on your links</li>
\r
190 <li>Neat AJAXed interface</li>
\r
191 <li>Developer API</li>
\r
194 <h3>Screenshots</h3>
\r
196 <div class="sshot">
\r
197 <img src="http://yourls.org/images/head.gif" />
\r
198 <img src="http://yourls.org/images/stats.gif" />
\r
199 <img src="http://yourls.org/images/footer.gif" />
\r
204 <p><a href="http://code.google.com/p/yourls/downloads/list">Download YOURLS</a> from Google Code</p>
\r
208 <p>YOURLS is made by:</p>
\r
210 <li><a href="http://lesterchan.net/" title="Visit Lester Chan's site">Lester Chan</a> &ndash <a href="http://twitter.com/gamerz">@GamerZ</a> on Twitter</li>
\r
211 <li><a href="http://planetozh.com/" title"Visit Ozh's site">Ozh RICHARD</a> &ndash <a href="http://twitter.com/ozh">@Ozh</a> on Twitter</li>
\r
215 <!-- Installation Instructions -->
\r
216 <div id="InstallDiv" style="display: none;">
\r
217 <h2>Installation Instructions</h2>
\r
219 <li>Unzip the YOURLS archive</li>
\r
220 <li>Copy <code>includes/config-sample.php</code> to <code>includes/config.php</code></li>
\r
221 <li>Open <code>includes/config.php</code> with a raw text editor (like Notepad) and fill in the required settings</li>
\r
222 <li>Upload the unzipped files to your domain <code>public_html</code> or <code>www</code> folder</li>
\r
223 <li>Create a new database (see <a href="#Config" onclick="toggle(this);">Configuration</a> – you can also use an existing one)</li>
\r
224 <li>Point your browser to <code>http://yoursite.com/admin/install.php</code></li>
\r
228 <!-- Configuration Instructions -->
\r
229 <div id="ConfigDiv" style="display: none;">
\r
230 <h2>Configuration (in includes/config.php)</h2>
\r
231 <h3>MySQL settings</h3>
\r
233 <li><code>YOURLS_DB_USER</code><br/>
\r
234 your MySQL username<br/>
\r
235 <em>Example:</em> <tt>'joe'</tt></li>
\r
236 <li><code>YOURLS_DB_PASS</code><br/>
\r
237 your MySQL password<br/>
\r
238 <em>Example:</em> <tt>'MySeCreTPaSsW0rd'</tt></li>
\r
239 <li><code>YOURLS_DB_NAME</code>:
\r
240 The database name<br/>
\r
241 <em>Example:</em> <tt>'yourls'</tt></li>
\r
242 <li><code>YOURLS_DB_HOST</code><br/>
\r
243 The database host<br/>
\r
244 <em>Example:</em> <tt>'localhost'</tt></li>
\r
245 <li><code>YOURLS_DB_TABLE_URL</code><br/>
\r
246 The table name to store URLs<br/>
\r
247 <em>Example:</em> <tt>'url'</tt></li>
\r
248 <li><code>YOURLS_DB_TABLE_NEXTDEC</code><br/>
\r
249 The table name to store the next sequential link decimal id<br/>
\r
250 <em>Example:</em> <tt>'nextdec'</tt></li>
\r
253 <h3>Site options</h3>
\r
255 <li><code>YOURLS_SITE</code><br/>
\r
256 Your (short) domain URL, no trailing slash<br/>
\r
257 <em>Example:</em> <tt>'http://ozh.in'</tt></li>
\r
258 <li><code>YOURLS_HOURS_OFFSET</code><br/>
\r
259 Timezone GMT offset<br/>
\r
260 <em>Example:</em> <tt>'-5'</tt></li>
\r
261 <li><code>YOURLS_PRIVATE</code><br/>
\r
262 Private means protected with login/pass as defined below. Set to false for public usage<br/>
\r
263 <em>Example:</em> <tt>'true'</tt></li>
\r
264 <li><code>YOURLS_COOKIEKEY</code><br/>
\r
265 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 <a href="http://yourls.org/cookiekey.php">http://yourls.org/cookiekey.php</a><br/>
\r
266 <em>Example:</em> <tt>'qQ4KhL_pu|s@Zm7n#%:b^{A[vhm'</tt></li>
\r
267 <li><code>yourls_user_passwords</code><br/>
\r
268 A list of username(s) and password(s) allowed to access the site if private<br/>
\r
269 <em>Example:</em> <tt>'joe' => 'mypassword'</tt></li>
\r
272 <h3>URL Shortening settings</h3>
\r
274 <li><code>YOURLS_URL_CONVERT</code><br/>
\r
275 URL shortening method: base <tt>36</tt> or <tt>62</tt>. See <a onclick="toggle(this);" href="#FAQ">FAQ</a> for more explanations</li>
\r
276 <li><code>yourls_reserved_URL</code><br/>
\r
277 A list of reserved keywords that won't be used as short URLs. Define here negative, unwanted or potentially misleading keywords<br/>
\r
278 <em>Example:</em> <tt>'porn', 'faggot', 'sex', 'nigger', 'fuck', 'cunt', 'dick', 'gay'</tt></li>
\r
282 <!-- WordPress plugin -->
\r
283 <div id="PluginDiv" style="display:none">
\r
284 <h2>WordPress Plugin</h2>
\r
288 <li>Generate short URLs for each new post or page</li>
\r
289 <li>Send a tweet on your Twitter account with the post title and short URL as you publish them</li>
\r
290 <li>Works if YOURLS is hosted on the same server or on a remote server</li>
\r
291 <li>Also compatible with tr.im, is.gd, tinyurl.com and bit.ly for maximum fun</li>
\r
294 <h3>Screenshots</h3>
\r
295 <div class="sshot">
\r
296 <img src="http://yourls.org/images/wpplugin.gif"/>
\r
299 <h3>Download & more informations</h3>
\r
301 <li>Download <a href="http://wordpress.org/extend/plugins/yourls-wordpress-to-twitter/">YOURLS: WordPress to Twitter</a> from the official WordPress plugin repository</li>
\r
302 <li>More information, tips and feedback on <a href="http://planetozh.com/blog/yourls-wordpress-to-twitter-a-short-url-plugin/">the plugin page</a> from planetOzh</li>
\r
308 <div id="APIDiv" style="display:none">
\r
309 <h2>YOURLS' API</h2>
\r
313 <li>Generate or get existing short URLs, with sequential or custom keyword</li>
\r
314 <li>Get some statistics about your links: top clicked links, least clicked links, newest links</li>
\r
315 <li>Output format: JSON, XML, or simple raw text</li>
\r
319 <p>You need to send parameters to <code>http://yoursite.com/yourls-api.php</code> either via <code>GET</code> or <code>POST</code>. These parameters are:</p>
\r
321 <li>A valid <code>username</code></li>
\r
322 <li>A valid <code>password</code></li>
\r
323 <li>The requested <code>action</code>: <tt>"shorturl"</tt> (get short URL for a link), <tt>"expand"</tt> (get long URL of a shorturl) or <tt>"stats"</tt> (get stats about your links)</li>
\r
324 <li>With <tt>action = "shorturl"</tt> :
\r
326 <li>the <code>url</code> to shorten</li>
\r
327 <li>optional <code>keyword</code> for custom short URLs</li>
\r
328 <li>output <code>format</code>: either <tt>"json"</tt>, <tt>"xml"</tt> or <tt>"simple"</tt></li>
\r
331 <li>With <tt>action = "expand"</tt> :
\r
333 <li>the <code>shorturl</code> to expand (can be either 'abc' or 'http://site/abc')</li>
\r
334 <li>output <code>format</code>: either <tt>"json"</tt>, <tt>"xml"</tt> or <tt>"simple"</tt></li>
\r
337 <li>With <tt>action = "stats"</tt> :
\r
339 <li>the <code>filter</code>: either <tt>"top"</tt>, <tt>"bottom"</tt> , <tt>"rand"</tt> or <tt>"last"</tt></li>
\r
340 <li>the <code>limit</code> (maximum number of links to return)</li>
\r
341 <li>output <code>format</code>: either <tt>"json"</tt> or <tt>"xml"</tt></li>
\r
346 <h3>Sample return</h3>
\r
347 <pre><tt><result>
\r
349 <id>62019439011</id>
\r
350 <keyword>shorter</keyword>
\r
351 <url>http://somereallylongurlyouneedtoshrink.com/</url>
\r
352 <date>2009-06-23 18:08:07</date>
\r
353 <ip>127.0.0.1</ip>
\r
355 <status>success</status>
\r
356 <message>http://somereallylongurlyouneedtoshrink.com/ (ID: shorter) added to database</message>
\r
357 <shorturl>http://yoursite.com/shorter</shorturl>
\r
358 </result></tt></pre>
\r
360 <h3>Sample file</h3>
\r
361 <p>There's a sample file included that serves as an example on how to play with the API</p>
\r
366 <!-- FAQ Instructions -->
\r
367 <div id="FAQDiv" style="display: none;">
\r
370 <h3>Server requirements</h3>
\r
372 <li>A server with <strong>mod_rewrite</strong> enabled</li>
\r
373 <li>At least <strong>PHP 4.3</strong></li>
\r
374 <li>At least <strong>MYSQL 4.1</strong></li>
\r
375 <li><em>Note</em>: YOURLS can also run on Nginx (<a href="http://foolrulez.org/blog/2009/08/foolz-us-make-yourls-work-on-ngin/">Read more</a>)</li>
\r
378 <h3>Server recommendations</h3>
\r
380 <li>PHP <a href="http://www.php.net/curl">CURL extension</a> installed if you plan on playing with the API</li>
\r
381 <li>PHP <a href="http://www.php.net/manual/en/ref.bc.php">BCMath extension</a> for handling large integers (ie many (really many many) links or long custom keyword URLs)</li>
\r
384 <h3>Limitations</h3>
\r
386 <li>Maximum length of custom keyword is <strong>12 characters</strong></li>
\r
387 <li><strong>4,738,381,338,321,617,846</strong> available URLs</li>
\r
390 <h3>Difference Between Base 36 And Base 62 Encoding</h3>
\r
392 <li>Base 36 encoding uses <code>0123456789abcdefghijklmnopqrstuvwxyz</code></li>
\r
393 <li>Base 62 encoding uses <code>0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz</code></li>
\r
394 <li>Stick to one setting, don't change after you've created links as it will change all your short URLs!</li>
\r
395 <li>Base 36 should be picked. Use 62 only if you understand what it implies.</li>
\r
396 <li>Using base 62 means you *need* PHP extension BCMath</li>
\r
397 <li>Consider Base 62 encoding a <code>beta feature</code></li>
\r
400 <h3>Getting a short domain name for your YOURLS install</h3>
\r
402 <li>Unless you plan on making it public, any shared hosting should be fine</li>
\r
403 <li><a href="http://domai.nr/">Domainr</a> is a fun search tool that might inspire and help you</li>
\r
404 <li>Aim for exotic top level domains (.in, .im, .li ...), they're often cheap and a lot are still available. <a href="https://www.gandi.net/domain/buy/search/">Gandi</a> is a pretty comprehensive registrar, for instance.</li>
\r
407 <h3>YOURLS needs its own .htaccess</h3>
\r
409 <li>You cannot install YOURLS and, say, WordPress, in the same directory. Both of them need to handle URLs differently</li>
\r
410 <li>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")</li>
\r
413 <h3>If YOURLS generates 404 for your short URLs</h3>
\r
415 <li>Make sure <strong>mod_rewrite</strong> is enabled with your Apache server</li>
\r
416 <li>Some (crappy) hosts such as GoDaddy or 1and1 need <a href="http://code.google.com/p/yourls/issues/detail?id=25">a small fix</a> to .htaccess:</li>
\r
419 <h3>Feedback and bug reporting</h3>
\r
421 <li>Please don't get in touch directly by mail or Twitter</li>
\r
422 <li>Raise an <a href="http://code.google.com/p/yourls/issues/list">issue here</a> and give all the details. Thanks!</li>
\r
429 <div id="ShowcaseDiv" style="display: none;">
\r
432 <h3>Here are a few examples of sites running YOURLS with a unique design or concept</h3>
\r
435 <li><a href="http://hmm.ph/">http://hmm.ph/</a><br/>
\r
436 Funny domain name, nicely styled</li>
\r
437 <li><a href="http://qte.me/">http://qte.me/</a><br/>
\r
438 Another YOURLS setup with a cute quote look</li>
\r
439 <li><a href="http://unsl.im/">http://unsl.im/</a><br/>
\r
440 Gorgeous design listing latest links with a custom RSS feed (private use)</li>
\r
441 <li><a href="http://mrte.ch/">http://mrte.ch/</a><br/>
\r
442 Mr Tech's public YOURLS setup, listing top links and some stats</li>
\r
443 <li><a href="http://s4c.in/">http://s4c.in/</a><br/>
\r
444 Shorten 4 Charity, a public YOURLS setup with shortened links displayed within a frame containing ads for charities </li>
\r
445 <li><a href="http://girv.in/">http://girv.in/</a><br/>
\r
446 John Girvin's YOURLS setup with all links in a sortable display</li>
\r
447 <li><a href="http://www.iyeman.net/">http://www.iyeman.net/</a><br/>
\r
448 <a href="http://tinytags.co.cc/">http://tinytags.co.cc/</a><br/>
\r
449 Examples of portals for your online self with links to your places (blog, Twitter) and your URL shortener</li>
\r
450 <li><a href="http://li.nkto.me/">http://li.nkto.me/</a><br/>
\r
451 A nice domain name hack :)</li>
\r
452 <li><a href="http://vb.ly/">http://vb.ly/</a><br/>
\r
453 Public YOURLS setup run by famous sex writer Violet Blue as "the internet's first and only sex-positive url shortener"</li>
\r
457 <h3>More stuff about or with YOURLS</h3>
\r
460 <li><a href="http://screenr.com/nTs">http://screenr.com/nTs</a><br/>
\r
461 A screencast explaining how to setup YOURLS</li>
\r
462 <li><a href="http://foolrulez.org/blog/2009/09/yourls-widget-released">YOURLS Widget for WordPress</a><br/>
\r
463 This widget adds a convenient short URL service into your sidebar. Check the above link for a live example</li>
\r
464 <li><a href="http://github.com/pjain/WWW-Shorten-Yourls">WWW-Shorten-Yourls</a><br/>
\r
465 A Perl module to shorten URLs using YOURLS</li>
\r
466 <li>YOURLS featured on <a href="http://lifehacker.com/5335216/make-your-own-url-shortening-service">Lifehacker</a></li>
\r
470 </div> <!-- content -->
\r
471 </div> <!-- container -->
\r
473 <p id="Copyright">YOURLS: Your Own URL Shortener<br />All Free & GPL – 2009</p>
\r
475 <script type="text/javascript">
\r
477 // Dynamically get tabs
\r
478 function getTabs() {
\r
479 var d = document.getElementById('Tabs');
\r
480 var matches = d.innerHTML.match(/<li id="(.+?)Tab"/g);
\r
482 for (i in matches) {
\r
483 tabs[i]= matches[i].replace('<li id="','').replace('Tab"', '');
\r
485 tabs = tabs.reverse();
\r
488 // Toggle tab display
\r
489 function toggle(el) {
\r
490 //var tabs = ["About", "Install", "Config", "Plugin", "FAQ"];
\r
491 var target = el.toString().replace(/^.*#/, '');
\r
492 for (var tab in tabs) {
\r
494 document.getElementById(tabs[tab]+'Tab').className = 'Tab';
\r
496 document.getElementById(tabs[tab]+'Div').style.display= 'none';
\r
498 // highlight & display target
\r
499 document.getElementById(target+'Div').style.display = 'block';
\r
500 document.getElementById(target+'Tab').className = 'SelectedTab';
\r
504 var tabs = getTabs();
\r
505 // On page load/refresh display required tab
\r
506 if (location.hash) {
\r
507 toggle(location.hash);
\r
projects / Github / YOURLS.git / blob