Last updated 11 September 2011. Created on 21 May 2010.
Edited by IceCreamYou. Log in to edit this page.

The Shorten URLs package contains four modules:

  • Shorten URLs: provides an API and UI for shortening URLs via many common services
  • Record Shortened URLs: keeps track of which URLs have been shortened
  • Shorten URLs Custom Services: allows administrators to add custom URL shortening services through the user interface (instead of using the API)
  • Shorten URLs Input Filter: provides an input filter to shorten URLs inline

The main Shorten URLs module provides:

  • An API to shorten URLs via almost any service (over 25 services are available by default)
  • A block and a page (located at example.com/shorten) that provide an interface for easily shortening URLs
  • A block that displays a shortened URL for the current page for easy copying

The Record Shortened URLs submodule provides an overview of which URLs have been shortened at admin/settings/shorten/records. The list is generated using Views if it is installed.

The Shorten URLs Custom Services module is recommended for advanced users only; most sites won't need to use it. It can be used to add custom URL shortening services; for example, if your main website is at example.com but you build a custom URL shortener at xmpl.cm, then you could use the Custom Services module to register xmpl.cm as a URL shortening service available to the main Shorten URLs module. (The alternative is to register the service in code using the API below.)

API

shorten_url($original = '', $service = '')
Returns a shortened URL. $original is the URL to be shortened, and $service is the service to use to shorten the URL. For service, you can use any string that appears in the default service options on the settings page. If $original is not specified it defaults to the current page; if $service is not specified it defaults to the primary service set in the settings for this module. Shortened URLs are cached for performance.
 
hook_shorten_service()
This hook should return an array keyed by the name of the service, with values as one of the options below:
  return array(
    // Automatically gets the shortened URL based on the URL to TinyURL's API provided below.
    'TinyURL' => 'http://tinyurl.com/api-create.php?url=',
    // This is equivalent to the above.
    'TinyURL' => array(
      'custom' => FALSE,
      'url' => 'http://tinyurl.com/api-create.php?url=',
    ),

    // Does custom processing within the hook and passes an already-shortened URL.
    // Use this for services requiring a POST request.
    // The original URL is automatically passed as the first argument.
    // If you don't have any other arguments, don't specify 'args'.
    'myservice' => array(
      'custom' => 'mymodule_get_short_url_from_myservice',
      'args' => array($arg1, $arg2),
    ),

    // Automatically gets the shortened URL from the value of the 'tag' element when the relevant service provides the response as XML.
    'short.ie' => array(
      'custom' => 'xml', // This line is optional, but recommended.
      'url' => 'http://short.ie/api?url=',
      'tag' => 'shortened',
    ),

    // Automatically gets the shortened URL from the value of the 'json' element when the relevant service provides the response as JSON.
    'tr.im' => array(
      'custom' => 'json', // This line is optional, but recommended.
      'url' => 'http://api.tr.im/api/trim_url.json?url=',
      'json' => 'url',
    ),

  );

If you implement a service with a custom callback, you will probably want to call shorten_fetch(). Look at that function's in-code documentation or (in D7) take a look at _shorten_googl() for an example. Custom callbacks are currently the only way to implement POST requests, and shorten_fetch() only supports POST requests in D7.

hook_shorten_create($original, $short, $service)
Allows modules to react to the retrieval of a new shortened URL. $original is the URL that was shortened, $short is the shortened URL, and $service is the service used to shorten the URL.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.