readme.html

   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
   3 <head>  \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
   7                 /* Default Style */\r
   8                 body {\r
   9                         font-family: Verdana, Arial;\r
  10                         font-size: 12px;\r
  11                         color: #000000;\r
  12                         background: #ffffff;\r
  13                 }\r
  14                 p {\r
  15                         padding-left: 10px;\r
  16                 }\r
  17                 code {\r
  18                         background:#eaeaef;\r
  19                         padding:0 2px;\r
  20                 }\r
  21                 tt {\r
  22                         background:#ffc;\r
  23                         padding:0 2px;          \r
  24                 }\r
  25                 pre tt {\r
  26                         display:block;\r
  27                 }\r
  28                 blockquote {\r
  29                         margin: 10px 20px 0px 20px;\r
  30                         padding: 10px;\r
  31                         border: 1px solid #8d8d8d;\r
  32                         background-color: #f5f5f5;\r
  33                 }\r
  34                 li {\r
  35                         margin-top: 20px;\r
  36                 }\r
  37                 ul li ul li {\r
  38                         margin-top: 10px;\r
  39                 }\r
  40                 a, a:active, a:link, a:visited {\r
  41                         color: #5b87b4;\r
  42                         text-decoration: none;\r
  43                 }\r
  44                 a:hover {\r
  45                         color: #5577a5;\r
  46                         text-decoration: underline;\r
  47                 }\r
  48                 div.sshot {\r
  49                         text-align:center;\r
  50                 }\r
  51                 div.sshot img {\r
  52                         border:1px solid #5b87b4;\r
  53                         zdisplay:block;\r
  54                         margin-bottom:1em;\r
  55                 }\r
  56                 /* Place Holder Style */\r
  57                 #Container {\r
  58                         width: 780px;\r
  59                         margin-left: auto;\r
  60                         margin-right: auto; \r
  61                 }\r
  62                 #Content {\r
  63                         background-color: #fafafa;\r
  64                         border: 1px solid #a2b6cb;\r
  65                         padding: 10px;\r
  66                         margin-top: -13px;\r
  67                 }\r
  68                 /* Title Style */\r
  69                 h1 {\r
  70                         font-family: Verdana, Arial;\r
  71                         font-size: 22px;\r
  72                         font-weight: bold;\r
  73                         color: #2a85b3;\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
  77                         padding-top:90px;\r
  78                 }\r
  79                 h1:hover span {\r
  80                         color: #73A4D6;\r
  81                 }\r
  82                 h2 {\r
  83                         font-family: Verdana, Arial;\r
  84                         font-size: 18px;\r
  85                         font-weight: bold;\r
  86                         color: #5b87b4;\r
  87                 }\r
  88                 h2:before {\r
  89                         content: '\00BB';\r
  90                         color:#BFE0FE;\r
  91                 }\r
  92                 h3 {\r
  93                         font-family: Verdana, Arial;\r
  94                         font-size: 14px;\r
  95                         font-weight: bold;\r
  96                         color: #73a4d6;\r
  97                         margin-top:2em;\r
  98                 }\r
  99                 h3:before {\r
 100                         content: '\00BB';\r
 101                         color:#BFE0FE;\r
 102                 }\r
 103                 /* Tabs */\r
 104                 ul#Tabs {\r
 105                         font-family: Verdana, Arial;\r
 106                         font-size: 12px;\r
 107                         font-weight: bold;\r
 108                         list-style-type: none;\r
 109                         padding-bottom: 28px;\r
 110                         border-bottom: 1px solid #a2b6cb;\r
 111                         margin-bottom: 12px;\r
 112                         z-index: 1;\r
 113                 }\r
 114                 #Tabs li.Tab {\r
 115                         float: right;\r
 116                         height: 25px;\r
 117                         background-color: #deedfb;\r
 118                         margin: 2px 0px 0px 5px;\r
 119                         border: 1px solid #a2b6cb;\r
 120                 }\r
 121                 #Tabs li.Tab a {\r
 122                         float: left;\r
 123                         display: block;\r
 124                         color: #666666;\r
 125                         text-decoration: none;\r
 126                         padding: 5px;\r
 127                 }\r
 128                 #Tabs li.Tab a:hover {\r
 129                         background-color: #bfe0fe;\r
 130                         border-bottom: 1px solid #bfe0fe;\r
 131                 }\r
 132                 /* Selected Tab */\r
 133                 #Tabs li.SelectedTab {\r
 134                         float: right;\r
 135                         height: 25px;\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
 142                 }\r
 143                 #Tabs li.SelectedTab a {\r
 144                         float: left;\r
 145                         display: block;\r
 146                         color: #666666;\r
 147                         text-decoration: none;\r
 148                         padding: 5px;\r
 149                         cursor: default;\r
 150                 }\r
 151                 /* Copyright */\r
 152                 #Copyright {\r
 153                         text-align: center;\r
 154                 }\r
 155         </style>\r
 156 </head>\r
 157 <body>\r
 158 <div id="Container">\r
 159         <!-- Title -->\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
 161 \r
 162         <!-- Tabs -->\r
 163         <ul id="Tabs">\r
 164                 <li id="FAQTab" class="Tab"><a href="#FAQ" onclick="toggle(this);">FAQ</a></li>\r
 165                 <li id="APITab" class="Tab"><a href="#API" onclick="toggle(this);">API</a></li>\r
 166                 <li id="PluginTab" class="Tab"><a href="#Plugin" onclick="toggle(this);">WordPress plugin</a></li>\r
 167                 <li id="ConfigTab" class="Tab"><a href="#Config" onclick="toggle(this);">Configuration</a></li>\r
 168                 <li id="InstallTab" class="Tab"><a href="#Install" onclick="toggle(this);">Installation</a></li>\r
 169                 <li id="AboutTab" class="SelectedTab"><a href="#About" onclick="toggle(this);">About</a></li>\r
 170         </ul>\r
 171 \r
 172         <!-- Content -->\r
 173         <div id="Content">\r
 174                 <!-- Index -->\r
 175                 <div id="AboutDiv">\r
 176                         <h2>About YOURLS</h2>\r
 177                         \r
 178                         <h3>What is YOURLS</h3>\r
 179                         <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
 180                         <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
 181                         \r
 182                         <h3>YOURLS Features</h3>\r
 183                         <ul>\r
 184                                 <li>Public (everybody can create short links) or private (your links only)</li>\r
 185                                 <li>Random (sequential) or custom URL keyword</li>\r
 186                                 <li>Track click count on your links</li>\r
 187                                 <li>Neat AJAXed interface</li>\r
 188                                 <li>Developer API</li>\r
 189                         </ul>\r
 190                         \r
 191                         <h3>Screenshots</h3>\r
 192                         \r
 193                         <div class="sshot">\r
 194                                 <img src="http://yourls.org/images/head.gif" />\r
 195                                 <img src="http://yourls.org/images/stats.gif" />\r
 196                                 <img src="http://yourls.org/images/footer.gif" />\r
 197                         </div>\r
 198                         \r
 199                         <h3>Download</h3>\r
 200                         \r
 201                         <p><a href="http://code.google.com/p/yourls/downloads/list">Download YOURLS</a> from Google Code</p>\r
 202                         \r
 203                         <h3>Credits</h3>\r
 204                         \r
 205                         <p>YOURLS is made by:</p>\r
 206                         <ul>\r
 207                                 <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
 208                                 <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
 209                         </ul>\r
 210                 </div>\r
 211 \r
 212                 <!-- Installation Instructions -->\r
 213                 <div id="InstallDiv" style="display: none;">\r
 214                         <h2>Installation Instructions</h2>\r
 215                         <ol>\r
 216                                 <li>Unzip the YOURLS archive</li>\r
 217                                 <li>Copy <code>includes/config-sample.php</code> to <code>includes/config.php</code></li>\r
 218                                 <li>Open <code>includes/config.php</code> with a raw text editor (like Notepad) and fill in the required settings</li>\r
 219                                 <li>Upload the unzipped files to your domain <code>public_html</code> or <code>www</code> folder</li>\r
 220                                 <li>Create a new database (see <a href="#Config" onclick="toggle(this);">Configuration</a> &ndash; you can also use an existing one)</li>\r
 221                                 <li>Point your browser to <code>http://yoursite.com/admin/install.php</code></li>\r
 222                         </ol>\r
 223                 </div>\r
 224 \r
 225                 <!-- Configuration Instructions -->     \r
 226                 <div id="ConfigDiv" style="display: none;">\r
 227                         <h2>Configuration (in includes/config.php)</h2>\r
 228                         <h3>MySQL settings</h3>\r
 229                         <ul>\r
 230                                 <li><code>YOURLS_DB_USER</code><br/>\r
 231                                 your MySQL username<br/>\r
 232                                 <em>Example:</em> <tt>'joe'</tt></li>\r
 233                                 <li><code>YOURLS_DB_PASS</code><br/>\r
 234                                 your MySQL password<br/>\r
 235                                 <em>Example:</em> <tt>'MySeCreTPaSsW0rd'</tt></li>\r
 236                                 <li><code>YOURLS_DB_NAME</code>:\r
 237                                 The database name<br/>\r
 238                                 <em>Example:</em> <tt>'yourls'</tt></li>\r
 239                                 <li><code>YOURLS_DB_HOST</code><br/>\r
 240                                 The database host<br/>\r
 241                                 <em>Example:</em> <tt>'localhost'</tt></li>\r
 242                                 <li><code>YOURLS_DB_TABLE_URL</code><br/>\r
 243                                 The table name to store URLs<br/>\r
 244                                 <em>Example:</em> <tt>'url'</tt></li>\r
 245                                 <li><code>YOURLS_DB_TABLE_NEXTDEC</code><br/>\r
 246                                 The table name to store the next sequential link decimal id<br/>\r
 247                                 <em>Example:</em> <tt>'nextdec'</tt></li>\r
 248                         </ul>\r
 249                         \r
 250                         <h3>Site options</h3>\r
 251                         <ul>\r
 252                                 <li><code>YOURLS_SITE</code><br/>\r
 253                                 Your (short) domain URL, no trailing slash<br/>\r
 254                                 <em>Example:</em> <tt>'http://ozh.in'</tt></li>\r
 255                                 <li><code>YOURLS_HOURS_OFFSET</code><br/>\r
 256                                 Timezone GMT offset<br/>\r
 257                                 <em>Example:</em> <tt>'-5'</tt></li>\r
 258                                 <li><code>YOURLS_PRIVATE</code><br/>\r
 259                                 Private means protected with login/pass as defined below. Set to false for public usage<br/>\r
 260                                 <em>Example:</em> <tt>'true'</tt></li>\r
 261                                 <li><code>YOURLS_COOKIEKEY</code><br/>\r
 262                                 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
 263                                 <em>Example:</em> <tt>'qQ4KhL_pu|s@Zm7n#%:b^{A[vhm'</tt></li>\r
 264                                 <li><code>yourls_user_passwords</code><br/>\r
 265                                 A list of username(s) and password(s) allowed to access the site if private<br/>\r
 266                                 <em>Example:</em> <tt>'joe' => 'mypassword'</tt></li>\r
 267                         </ul>\r
 268                         \r
 269                         <h3>URL Shortening settings</h3>\r
 270                         <ul>\r
 271                                 <li><code>YOURLS_URL_CONVERT</code><br/>\r
 272                                 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
 273                                 <li><code>yourls_reserved_URL</code><br/>\r
 274                                 A list of reserved keywords that won't be used as short URLs. Define here negative, unwanted or potentially misleading keywords<br/>\r
 275                                 <em>Example:</em> <tt>'porn', 'faggot', 'sex', 'nigger', 'fuck', 'cunt', 'dick', 'gay'</tt></li>\r
 276                         </ul>\r
 277                 </div>\r
 278                 \r
 279                 <!-- WordPress plugin -->\r
 280                 <div id="PluginDiv" style="display:none">\r
 281                         <h2>WordPress Plugin</h2>\r
 282                         \r
 283                         <h3>Features</h3>\r
 284                         <ul>\r
 285                                 <li>Generate short URLs for each new post or page</li>\r
 286                                 <li>Send a tweet on your Twitter account with the post title and short URL as you publish them</li>\r
 287                                 <li>Works if YOURLS is hosted on the same server or on a remote server</li>\r
 288                                 <li>Also compatible with tr.im, is.gd, tinyurl.com and bit.ly for maximum fun</li>\r
 289                         </ul>\r
 290                         \r
 291                         <h3>Screenshots</h3>\r
 292                         <div class="sshot">\r
 293                         <img src="http://yourls.org/images/wpplugin.gif"/>\r
 294                         </div>\r
 295                         \r
 296                         <h3>Download &amp; more informations</h3>\r
 297                         <ul>\r
 298                                 <li>Download <a href="http://wordpress.org/extend/plugins/##">YOURLS: WordPress to Twitter</a> from the official WordPress plugin repository</li>\r
 299                                 <li>More information, tips and feedback on <a href="http://planetozh.com/####">the plugin page</a> from planetOzh</li>\r
 300                         </ul>\r
 301                 \r
 302                 </div>\r
 303                 \r
 304                 <!-- API -->\r
 305                 <div id="APIDiv" style="display:none">\r
 306                         <h2>YOURLS' API</h2>\r
 307                         \r
 308                         <h3>Features</h3>\r
 309                         <ul>\r
 310                                 <li>Generate or get existing short URLs, with sequential or custom keyword</li>\r
 311                                 <li>Get some statistics about your links: top clicked links, least clicked links, newest links</li>\r
 312                                 <li>Output format: JSON, XML, or simple raw text</li>\r
 313                         </ul>\r
 314                         \r
 315                         <h3>Usage</h3>\r
 316                         <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
 317                         <ul>\r
 318                                 <li>A valid <code>username</code></li>\r
 319                                 <li>A valid <code>password</code></li>\r
 320                                 <li>The requested <code>action</code>: either <tt>"shorturl"</tt> (get short URL for a link) or <tt>"stats"</tt> (get stats about your links)</li>\r
 321                                 <li>With <tt>action = "shorturl"</tt> :\r
 322                                         <ul>\r
 323                                                 <li>the <code>url</code> to shorten</li>\r
 324                                                 <li>optional <code>keyword</code> for custom short URLs</li>\r
 325                                                 <li>output <code>format</code>: either <tt>"json"</tt>, <tt>"xml"</tt> or <tt>"simple"</tt></li>\r
 326                                         </ul>\r
 327                                 </li>\r
 328                                 <li>With <tt>action = "stats"</tt> :\r
 329                                         <ul>\r
 330                                                 <li>the <code>filter</code>: either <tt>"top"</tt>, <tt>"bottom"</tt> or <tt>"last"</tt></li>\r
 331                                                 <li>the <code>limit</code> (maximum number of links to return)</li>\r
 332                                                 <li>output <code>format</code>: either <tt>"json"</tt> or <tt>"xml"</tt></li>\r
 333                                         </ul>\r
 334                                 </li>\r
 335                         </ul>\r
 336                         \r
 337                         <h3>Sample return</h3>\r
 338                         <pre><tt>&lt;result&gt;\r
 339         &lt;url&gt;\r
 340                 &lt;id&gt;62019439011&lt;/id&gt;\r
 341                 &lt;keyword&gt;shorter&lt;/keyword&gt;\r
 342                 &lt;url&gt;http://somereallylongurlyouneedtoshrink.com/&lt;/url&gt;\r
 343                 &lt;date&gt;2009-06-23 18:08:07&lt;/date&gt;\r
 344                 &lt;ip&gt;127.0.0.1&lt;/ip&gt;\r
 345         &lt;/url&gt;\r
 346         &lt;status&gt;success&lt;/status&gt;\r
 347         &lt;message&gt;http://somereallylongurlyouneedtoshrink.com/ (ID: shorter) added to database&lt;/message&gt;\r
 348         &lt;shorturl&gt;http://yoursite.com/shorter&lt;/shorturl&gt;\r
 349 &lt;/result&gt;</tt></pre>\r
 350 \r
 351                         <h3>Sample file</h3>\r
 352                         <p>There's a sample file included that serves as an example on how to play with the API</p>\r
 353 \r
 354                 </div>\r
 355                 \r
 356 \r
 357                 <!-- FAQ Instructions -->       \r
 358                 <div id="FAQDiv" style="display: none;">\r
 359                         <h2>FAQ</h2>\r
 360 \r
 361                         <h3>Server requirements</h3>\r
 362                         <ol>\r
 363                                 <li>At least <strong>PHP 4.3</strong></li>\r
 364                                 <li>At least <strong>MYSQL 4.1</strong></li>\r
 365                         </ol>\r
 366 \r
 367                         <h3>Server recommendations</h3>\r
 368                         <ul>\r
 369                                 <li>PHP <a href="http://www.php.net/curl">CURL extension</a> installed if you plan on playing with the API</li>\r
 370                                 <li>PHP <a href="http://www.php.net/bccomp">BCCOMP extension</a> for handling large integers (ie many (really many many) links or long custom keyword URLs)</li>        \r
 371                         </ul>\r
 372                         \r
 373                         <h3>Limitations</h3>\r
 374                         <ul>\r
 375                                 <li>Maximum length of custom keyword is <strong>12 characters</strong></li>\r
 376                                 <li><strong>4,738,381,338,321,617,846</strong> available URLs</li>\r
 377                         </ul>\r
 378                         \r
 379                         <h3>Difference Between Base 36 And Base 62 Encoding</h3>\r
 380                         <ul>\r
 381                                 <li>Base 36 encoding uses <code>0123456789abcdefghijklmnopqrstuvwxyz</code></li>\r
 382                                 <li>Base 62 encoding uses <code>0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz</code></li>\r
 383                                 <li>Stick to one setting, don't change after you've created links as it will change all your short URLs!</li>\r
 384                                 <li>Base 36 should be picked. Use 62 only if you understand what it implies.</li>\r
 385                                 <li>Using base 62 means you *need* PHP extension BCCOMP</li>\r
 386                         </ul>\r
 387                         \r
 388                         <h3>Getting a short domain name for your YOURLS install</h3>\r
 389                         <ul>\r
 390                                 <li>Unless you plan on making it public, any shared hosting should be fine</li>\r
 391                                 <li><a href="http://domai.nr/">Domainr</a> is a fun search tool that might inspire and help you</li>\r
 392                                 <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
 393                 </div>\r
 394         </div>\r
 395 </div>\r
 396 \r
 397 <p id="Copyright">YOURLS: Your Own URL Shortener<br />All Free & GPL &ndash; 2009</p>\r
 398 \r
 399         <script type="text/javascript">\r
 400         /* <![CDATA[*/\r
 401         // Dynamically get tabs\r
 402         function getTabs() {\r
 403                 var d = document.getElementById('Tabs');\r
 404                 var matches = d.innerHTML.match(/<li id="(.+?)Tab"/g);\r
 405                 var tabs = []\r
 406                 for (i in matches) {\r
 407                   tabs[i]= matches[i].replace('<li id="','').replace('Tab"', '');\r
 408                 }\r
 409                 tabs = tabs.reverse();\r
 410                 return (tabs)\r
 411         }\r
 412         // Toggle tab display\r
 413         function toggle(el) {\r
 414                 //var tabs = ["About", "Install", "Config", "Plugin", "FAQ"];\r
 415                 var target = el.toString().replace(/^.*#/, '');\r
 416                 for (var tab in tabs) {\r
 417                         // reinit tabs\r
 418                         document.getElementById(tabs[tab]+'Tab').className = 'Tab';\r
 419                         // reinit divs\r
 420                         document.getElementById(tabs[tab]+'Div').style.display= 'none';\r
 421                 }\r
 422                 // highlight & display target\r
 423                 document.getElementById(target+'Div').style.display = 'block';\r
 424                 document.getElementById(target+'Tab').className = 'SelectedTab';\r
 425                 blur(this);\r
 426         }\r
 427         // Get tab list\r
 428         var tabs = getTabs();\r
 429         // On page load/refresh display required tab\r
 430         if (location.hash) {\r
 431                 toggle(location.hash);\r
 432         }\r
 433         /* ]]> */\r
 434         </script>\r
 435 \r
 436 \r
 437 </body>\r
 438 </html>