<commit_before>{<img src="https://secure.travis-ci.org/jpmcgrath/shortener.png?branch=master" alt="Build Status" />}[http://travis-ci.org/jpmcgrath/shortener]

= Shortener

Shortener is a Rails Engine Gem that makes it easy to create and interpret shortened URLs on your own domain from within your Rails application. Once installed Shortener will generate, store URLS and "unshorten" shortened URLs for your applications visitors, all whilst collecting basic usage metrics.

== Overview

The majority of the Shortener consists of three parts:

* a model for storing the details of the shortened link;
* a controller to accept incoming requests and redirecting them to the target URL;
* a helper for generating shortened URLs from controllers and views.

=== Dependencies

Shortener is designed to work from within a Rails 3 and Rails 4 applications. It has dependancies Rails core components like ActiveRecord, ActionController, the rails routing engine and more.

=== Ruby Version Support

As Ruby 1.9.3 entered end of maintainance in early 2015, the last version of the Shortener gem
to support Ruby 1.9.3 is 0.4.x. Shortener v0.5 onwards will require Ruby 2+.

=== Upgrading

==== v0.4.0 to v0.5.0
There have been some breaking changes:
1. The owner argument is passed into the generator and helper methods as a named parameter.
2. Original URLs arguments without a hypertext protocol (http|https) will be assumed to be relative paths.

=== v0.5.1 to v0.5.2
v0.5.2 introduced the ability to set an expiration date for a shortened URL. The expiration dates
are stored in a expires_at column in the database, which can be added to your schema with the following
migration:

  class AddExpiresAtToShortenedUrl < ActiveRecord::Migration
    def change
      add_column :shortened_urls, :expires_at, :datetime
    end
  end

=== Some niceities of Shortener:

* The controller does a 301 redirect, which is the recommended type of redirect for maintaining maximum google juice to the original URL;
* A unique alphanumeric code of generated for each shortened link, this means that we can get more unique combinations than if we just used numbers;
* The link records a count of how many times it has been “un-shortened”;
* The link can be associated with a user, this allows for stats of the link usage for a particular user and other interesting things;
* The controller spawns a new thread to record information to the database, allowing the redirect to happen as quickly as possible;

=== Future improvements:

* There has not been an attempt to remove ambiguous characters (i.e. 1 l and capital i, or 0 and O etc.) from the unique key generated for the link. This means people might copy the link incorrectly if copying the link by hand;
* The system could pre-generate unique keys in advance, avoiding the database penalty when checking that a newly generated key is unique;
* The system could store the shortened URL if the url is to be continually rendered;
* Some implementations might want duplicate links to be generated each time a user request a shortened link.

== Installation

Shortener is compatible with Rails v3 and v4. To install, add to your Gemfile:

  gem 'shortener'

After you install Shortener run the generator:

  rails generate shortener

This generator will create a migration to create the shortened_urls table where your shortened URLs will be stored.

Then add to your routes:

  get '/:id' => "shortener/shortened_urls#show"

== Configuration
The gem can be configured in a config/initializers/shortener.rb file.

By default, the shortener will generate keys that are 5 characters long. You can change that by specifying the length of the key like so;
<commit_msg>remove note about "possible" feature as it is now available as "fresh" feature<commit_after>{<img src="https://secure.travis-ci.org/jpmcgrath/shortener.png?branch=master" alt="Build Status" />}[http://travis-ci.org/jpmcgrath/shortener]

= Shortener

Shortener is a Rails Engine Gem that makes it easy to create and interpret shortened URLs on your own domain from within your Rails application. Once installed Shortener will generate, store URLS and "unshorten" shortened URLs for your applications visitors, all whilst collecting basic usage metrics.

== Overview

The majority of the Shortener consists of three parts:

* a model for storing the details of the shortened link;
* a controller to accept incoming requests and redirecting them to the target URL;
* a helper for generating shortened URLs from controllers and views.

=== Dependencies

Shortener is designed to work from within a Rails 3 and Rails 4 applications. It has dependancies Rails core components like ActiveRecord, ActionController, the rails routing engine and more.

=== Ruby Version Support

As Ruby 1.9.3 entered end of maintainance in early 2015, the last version of the Shortener gem
to support Ruby 1.9.3 is 0.4.x. Shortener v0.5 onwards will require Ruby 2+.

=== Upgrading

==== v0.4.0 to v0.5.0
There have been some breaking changes:
1. The owner argument is passed into the generator and helper methods as a named parameter.
2. Original URLs arguments without a hypertext protocol (http|https) will be assumed to be relative paths.

=== v0.5.1 to v0.5.2
v0.5.2 introduced the ability to set an expiration date for a shortened URL. The expiration dates
are stored in a expires_at column in the database, which can be added to your schema with the following
migration:

  class AddExpiresAtToShortenedUrl < ActiveRecord::Migration
    def change
      add_column :shortened_urls, :expires_at, :datetime
    end
  end

=== Some niceities of Shortener:

* The controller does a 301 redirect, which is the recommended type of redirect for maintaining maximum google juice to the original URL;
* A unique alphanumeric code of generated for each shortened link, this means that we can get more unique combinations than if we just used numbers;
* The link records a count of how many times it has been “un-shortened”;
* The link can be associated with a user, this allows for stats of the link usage for a particular user and other interesting things;
* The controller spawns a new thread to record information to the database, allowing the redirect to happen as quickly as possible;

=== Future improvements:

* There has not been an attempt to remove ambiguous characters (i.e. 1 l and capital i, or 0 and O etc.) from the unique key generated for the link. This means people might copy the link incorrectly if copying the link by hand;
* The system could pre-generate unique keys in advance, avoiding the database penalty when checking that a newly generated key is unique;
* The system could store the shortened URL if the url is to be continually rendered;

== Installation

Shortener is compatible with Rails v3 and v4. To install, add to your Gemfile:

  gem 'shortener'

After you install Shortener run the generator:

  rails generate shortener

This generator will create a migration to create the shortened_urls table where your shortened URLs will be stored.

Then add to your routes:

  get '/:id' => "shortener/shortened_urls#show"

== Configuration
The gem can be configured in a config/initializers/shortener.rb file.

By default, the shortener will generate keys that are 5 characters long. You can change that by specifying the length of the key like so;

{'fraction_non_alphanumeric': 0.049564270152505446, 'fraction_numerical': 0.011437908496732025, 'mean_word_length': 4.416666666666667, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6381106', 'n_tokens_mistral': 1914, 'n_tokens_neox': 1810, 'n_words': 1085}