Skip to content

Latest commit

 

History

History
172 lines (127 loc) · 5.8 KB

README.md

File metadata and controls

172 lines (127 loc) · 5.8 KB
Raw

Hashid Rails

Gem Version Build Status Code Climate Test Coverage

This gem allows you to easily use Hashids in your Rails app. Instead of your models using sequential numbers like 1, 2, 3, they will instead have unique short hashes like "yLA6m0oM", "5bAyD0LO", and "wz3MZ49l". The database will still use integers under the hood, so this gem can be added or removed at any time.

IMPORTANT: If you need to maintain the same hashids from a pre-1.0 release, read the upgrade notes.

Installation

Add this line to your application's Gemfile:

gem "hashid-rails", "~> 1.0"

And then execute:

$ bundle

Basic Usage

  1. Include Hashid Rails in the ActiveRecord model you'd like to enable hashids.
class Model < ActiveRecord::Base
  include Hashid::Rails
end
  1. Continue using Model#find passing in either a hashid or regular 'ol id.
@person = Person.find(params[:hashid])

Get hashid of model

You can access the hashid of any model using the hashid method.

model = Model.find(params[:hashid])
#=> <Model>
model.hashid
#=> "yLA6m0oM"

Additionally, the to_param method is overridden to use hashid instead of id. This means methods that take advantage of implicit ID will automatically work with hashids.

Passing a hashid model to `link_to`…
<%= link_to "Model", model %>

will use `hashid` instead of `id`.
<a href="/models/yLA6m0oM">Model</a>

Alternative Usage

You can use the Model#find_by_hashid method to find a record without falling back on the standard find method.

# When a record is found, it returns the record.
@person = Person.find_by_hashid(params[:hashid])
#=> <Person>

# When no record, it returns nil
@person = Person.find_by_hashid(params[:hashid])
#=> nil

# A bang (!) version is also available and raises an exception when not found.
@person = Person.find_by_hashid!(params[:hashid])
#=> ActiveRecord::RecordNotFound

Configuration (optional)

You can add an initializer for Hashid::Rails to customize the options passed to the Hashids gem. This is completely optional. The configuration below shows the default options.

Hashid::Rails.configure do |config|
  # The salt to use for generating hashid. Prepended with pepper (table name).
  config.salt = ""
  config.pepper = table_name

  # The minimum length of generated hashids
  config.min_hash_length = 6

  # The alphabet to use for generating hashids
  config.alphabet = "abcdefghijklmnopqrstuvwxyz" \
                    "ABCDEFGHIJKLMNOPQRSTUVWXYZ" \
                    "1234567890"

  # Whether to override the `find` method
  config.override_find = true

  # Whether to override the `to_param` method
  config.override_to_param = true

  # Whether to sign hashids to prevent conflicts with regular IDs (see https://github.com/jcypret/hashid-rails/issues/30)
  config.sign_hashids = true
end

Model-Level Config

You can also customize the hashid configuration at the model level. hashid_config supports all the same options as the Hashid::Rails.configure block and allows for each model to have a different config. This can be useful for setting a custom salt/pepper. For instance, the pepper defaults to the table name, so if you rename the table, you can keep the same hashids by setting the pepper to the old table name.

class Model < ActiveRecord::Base
  include Hashid::Rails
  hashid_config pepper: "old_table_name"
end

Upgrading from Pre-1.0

The 1.0 release of this gem introduced hashid signing to prevent conflicts with database IDs that could be mis-interpreted as hashids. IDs are now signed when encoding and the signature verified when decoding. The trade off is that hashids are different than in previous versions due to the added signature. If you need to maintain the same hashids from a pre-1.0 version, set sign_hashids to false in the config.

Additionally, some of the config names have been modified to better match the parent Hashid project. The config secret has been renamed to salt and the length renamed to min_hash_length. Update the initializer config accordingly.

Lastly, Hashid::Rails is no longer imported into ActiveRecord::Base by default. You can instead include Hashid::Rails selectively in the desired models, or include it in ApplicationRecord for Rails 5 to apply to all subclassed models, or add an initializer with ActiveRecord::Base.send :include, Hashid::Rails to match previous behavior.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

  1. Fork it ( https://github.com/[my-github-username]/hashid-rails/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

NOTE: If it's a significant feature or change, consider creating an Issue for discussion before opening a PR.