Prefixed IDs
🆔 Friendly Prefixed IDs for your Ruby on Rails models
Generate prefixed IDs for your models with a friendly prefix. For example:
user_12345abcd
acct_23lksjdg3
This gem works by hashing the record's original :id
attribute using Hashids
, which transforms numbers like 347 into a string like yr8. It uses the table's name and an optional additional salt to hash values, returning a string like tablename_hashedvalue
.
Inspired by Stripe's prefixed IDs in their API.
🚀 Installation
Add this line to your application's Gemfile:
gem 'prefixed_ids'
📝 Usage
Add has_prefix_id :my_prefix
to your models to autogenerate prefixed IDs.
class User < ApplicationRecord
has_prefix_id :user
end
This will generate a value like user_1234abcd
.
Note: You should add has_prefix_id
before associations because it overrides has_many
to add prefix ID lookups.
Prefix ID Param
To retrieve the prefix ID, simply call:
@user.to_param
If to_param
override is disabled:
@user.prefix_id
Query by Prefixed ID
To query using the prefixed ID, you can use either find
, find_by_prefix_id
, or find_by_prefix_id!
:
User.find("user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe")
User.find_by_prefix_id("user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe")
find
still finds records by the primary key. Eg. localhost/users/1
still works.
If you're targeting security issues by masking the ID, make sure to use find_by_prefix_id
and add a salt.
We also override to_param
by default so it'll be used in URLs automatically.
To disable find and to_param overrides, simply pass in the options:
class User < ApplicationRecord
has_prefix_id :user, override_find: false, override_param: false
end
Salt
A salt is a secret value that makes it impossible to reverse engineer IDs. We recommend adding a salt to make your Prefix IDs unguessable.
Global Salt
# config/initializers/prefixed_ids.rb
PrefixedIds.salt = "salt"
Per Model Salt
class User
has_prefix_id :user, salt: "usersalt"
end
Generic Lookup By Prefix ID
Imagine you have a prefixed ID but you don't know which model it belongs to.
PrefixedIds.find("user_5vJjbzXq9KrLEMm3")
#=> #<User>
PrefixedIds.find("acct_2iAnOP0xGDYk6dpe")
#=> #<Account>
Customizing Prefix IDs
You can customize the prefix, length, and attribute name for PrefixedIds.
class Account < ApplicationRecord
has_prefix_id :acct, minimum_length: 32, override_find: false, override_param: false, salt: "", fallback: false
end
By default, find
will accept both Prefix IDs and regular IDs. Setting fallback: false
will disable finding by regular IDs and will only allow Prefix IDs.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run rake test
to run the tests. You can also 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
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
🙏 Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/excid3/prefixed_ids. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
📝 License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the PrefixedIds project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.