URL shortening

The URL Shortening Service (USS) is an additional PhPeace module, disabled by default and controlled by the central PhPeace server your installation is connected to (by default it's phpeace.com).

USS provides URL shortening for all URLs, both internal and external, although it has initially been implemented for posting tweets about internal articles' updates.

The URLs are shortened as a string made of lowercase characters and numbers.

There are no administration pages for this module. The client service is used by Twitter module and it will be used by other modules in the future. However there's no way at present for an administrative user to shorten URLs via a web interface.

Server vs Client

USS runs as a web service (USS server) which can be used by other PhPeace installations (USS clients) or by the server itself.

Authorization is based on a simple password which is transmitted in the SOAP request by the client to the server. It's a simple protection to limit abuse of the service.

All PhPeace installations have a USS client. The client supports PhPeace own URL shortening service and others such as bit.ly. In order to run a USS server, it must be enabled by the central installation as mentioned above.

Configuration settings

USS settings are defined in the system configuration file.
Depending on how you want to configure your PhPeace installation (as a USS server or as a client) different settings apply.

uss_url
This setting is used by USS clients only and specifies the hostname of the USS server, that is the URL of the portal in the PhPeace installation.
You may use an external URL Shortening provider, such as http://bit.ly. For more details see below.

uss_key
The is the password to authorize requests. It's set on both USS servers and clients and must match for clients to be able to use the service on the server

uss_log_hits
This setting applies to USS servers only.
You can choose whether to track hits of short URLs. A timestamp is updated and a counter is increased for each hit. It can be used to remove expired URLs, although this functionality is currently not available.
By default it's set to false.

uss_mask
This setting applies to USS servers only.
By default, the short URL is in the form www.domain.org/uss/?1234ab, where www.domain.org is the hostname of the portal of the PhPeace installation running the USS service, and 1234ab is a sample short identifier.
However www.domain.org/uss/?1234ab is redirected to www.domain.org/uss/go.php?id=1234ab, which will then redirect to the real URL associated to 1234ab

Using bit.ly

If you want to use http://bit.ly, you need to register and get your API key at http://bit.ly/a/your_api_key
Then put both login and API key in system configuration settings and set $uss_url = "bit.ly";
As you wil lbe using an external URL shortening service, all other USS-related settings will be ignored.

USS masking and mod_rewrite

The presence of the portal domain name and the USS directory, plus the querystring question mark, are making the URL unnecessary long, which is not suitable for a URL shortening service.
So it's much better to configure URL rewrite so that a specific short hostname is used to mask short URLs and redirect to the real ones.

For example, if your portal hostname is www.domain.org and you want to use short.org for USS, you need to setup your virtual host configuration in this way (assuming mod_rewrite is enabled in your Apache modules).

ServerName short.org
RewriteEngine On
RewriteRule ^/([a-z0-9]*)$ http://www.domain.org/uss/go.php?id=$1 [L]

So if you set

in the system configuration settings, your short URL for the example above will be
http://short.org/1234ab
which will be rewritten to
http://www.domain.org/uss/go.php?id=1234ab
and redirected to the associated URL

You are strongly advised to use a custom short hostname for masking your short URLs.