katmore/shrturl

a URL shortener webservice

shrturl

a URL shortener webservice, _(*1)

Shrturl is a RESTful web service that behaves similar to enterprise level URL shortening services (such as bit.ly)., _(*2)

• Latest Version:, _(*3)

  • http://github.com/katmore/shrturl

• Documentation, _(*4)

  • http://github.com/katmore/shrturl/wiki

Terminology

• code or short code: the unique portion (token) contained in a short URL that serves as reference to full URL. The typically jibberish looking sequence of alpha numeric characters used in most URL shorteners.
• short url: the full URL that includes the short code (ie: http://example.com/shrt.php?code=abc)
• target url: the full URL that needs to be changed into a short URL

Installation

1. extract/copy the shrturl project somewhere, _(*5)

   git clone https://github.com/katmore/shrturl.git
   cd shrturl
   

2. create autoloader and resolve dependencies using Composer..., _(*6)

   composer update
   

3. run the db-install.php script..., _(*7)

   php bin/db-install.php
   

4. copy app/config/shrturl/mysql-sample.ini to mysql.ini and edit..., _(*8)

   cp app/config/shrturl/mysql-sample.ini app/config/shrturl/mysql.ini
   vi app/config/shrturl/mysql.ini
   

5. populate the database with initial set of randomly generated short codes..., _(*9)

   php bin/make-codes.php 1000
   

Webservice Usage

• Redirect to target URL:, _(*10)

  https://example.com/shrt.php?code=abc, _(*11)

  (where 'abc' is the code returned by "Shorten URL" request), _(*12)

• Display short URL, Create if it does not exist, _(*13)

  • POST REQUEST METHOD https://example.com/shrt.php?target=http://my_really_long_uri
    • adding a query var named 'POST' to the query string to will also invoke 'POST' (if using GET REQUEST METHOD) > https://example.com/shrt.php?POST&target=http://my_really_long_uri

  • add a query var and value for 'url_base' if you want to display a short url with a base, _(*14)

    URL other than what is configured in the 'default' section of shrt-config. A value for 'url_base' should correspond with a config var in shrt-config.php, _(*15)

  • POST REQUEST METHOD, _(*16)

    https://example.com/shrt.php?target=http://my_really_long_uri&url_base=reallyshort, _(*17)

    • would display/create: http://rlysh.rt/abc
    • see example in shrt-config-example.php > [https://github.com/katmore/shrturl/blob/master/shrt-config-example.php]

• Change Target URL, _(*18)

  • POST REQUEST METHOD > https://example.com/shrt.php?changeTarget=http://a_different_really_long_uri&code=abc
  • adding a query var named 'POST' to the query string to will also invoke 'POST' (if using GET REQUEST METHOD)

• Shorten Multiple URLs, _(*19)

  • POST REQUEST METHOD > https://example.com/shrt.php?request={JSON_document}
  • where 'target' is a valid JSON document with the following structure:

  json {"shrt":{"target":["http://target_url_1","http://target_url_2","http://etc"]}}, _(*20)

  • adding a query var named 'POST' to the query string to will also invoke 'POST' (if using GET REQUEST METHOD)

Webservice Deployment Suggestions

• use 2 different FQDNs (fully qualified domain names) for this service, _(*21)

  • FQDN #1 for 'end use' the short code, such as:, _(*22)

    http://rlysh.rt, _(*23)

  • FQDN #2 for API calls to short code service, such as:, _(*24)

    https://shrturl.example.com, _(*25)

• for example:, _(*26)

  1. on the 'end use FQDN' (#1)
     1. install/configure project as described in installation section of this document
     2. configure a url_base in addition to the 'default' > see url_base section in shrt-config-example.php
  • contains example of .htaccess or equivelent configuration for web server
  • http://rlysh.rt/abc will work now
  • where 'abc' is the short code provided by previous call to short API
  1. on the 'API FQDN' (#2) use as described in usage section > in API requests to obtain a short code ensure that: > provide a url_base parameter in query that corresponds to the 'end use' > that is set in your shrt-config-example.php

Legal

Copyright

Flat webapp - https://github.com/katmore/flat-webapp, _(*27)

Copyright (c) 2012-2017 Doug Bird. All Rights Reserved., _(*28)

License

"shrturl" is copyrighted free software., _(*29)

You can redistribute it and/or modify it under either the terms and conditions of the "The MIT License (MIT)"; or the terms and conditions of the "GPL v3 License"., _(*30)