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.