A small Ruby gem to generate YouTube-like ids from one or many numbers. Use hashids when you do not want to expose your database ids to the user.
(2.4.0 2.3.1, 2.2.5, 2.1.9, 2.0.0, jruby-9.0.5.0, jruby-1.7.20)
hashids (Hash ID's) creates short, unique, decodable hashes from unsigned integers.
(NOTE: This is NOT a true cryptographic hash, since it is reversible)
It was designed for websites to use in URL shortening, tracking stuff, or making pages private (or at least unguessable).
This algorithm tries to satisfy the following requirements:
- Hashes must be unique and decodable.
- They should be able to contain more than one integer (so you can use them in complex or clustered systems).
- You should be able to specify minimum hash length.
- Hashes should not contain basic English curse words (since they are meant to appear in public places - like the URL).
Instead of showing items as 1
, 2
, or 3
, you could show them as jR
, k5
, and l5
.
You don't have to store these hashes in the database, but can encode + decode on the fly.
All integers need to be greater than or equal to zero.
Add this line to your application's Gemfile:
gem 'hashids'
And then execute:
$ bundle
Or install it yourself as:
$ gem install hashids
You can pass a unique salt value so your hashes differ from everyone else's. I use this is my salt as an example.
hashids = Hashids.new("this is my salt")
hash = hashids.encode(12345)
hash
is now going to be:
NkK9
Notice during decoding, same salt value is used:
hashids = Hashids.new("this is my salt")
numbers = hashids.decode("NkK9")
numbers
is now going to be:
[ 12345 ]
Decoding will not work if salt is changed:
hashids = Hashids.new("this is my pepper")
numbers = hashids.decode("NkK9")
numbers
is now going to be:
[]
hashids = Hashids.new("this is my salt")
hash = hashids.encode(683, 94108, 123, 5)
hash
is now going to be:
aBMswoO2UB3Sj
hashids = Hashids.new("this is my salt")
numbers = hashids.decode("aBMswoO2UB3Sj")
numbers
is now going to be:
[ 683, 94108, 123, 5 ]
Here we encode integer 1, and set the minimum hash length to 8 (by default it's 0 -- meaning hashes will be the shortest possible length).
hashids = Hashids.new("this is my salt", 8)
hash = hashids.encode(1)
hash
is now going to be:
gB0NV05e
hashids = Hashids.new("this is my salt", 8)
numbers = hashids.decode("gB0NV05e")
numbers
is now going to be:
[ 1 ]
Here we set the alphabet to consist of: "abcdefghijkABCDEFGHIJK12345"
hashids = Hashids.new("this is my salt", 0, "abcdefghijkABCDEFGHIJK12345")
hash = hashids.encode(1, 2, 3, 4, 5)
hash
is now going to be:
dEc4iEHeF3
The primary purpose of hashids is to obfuscate ids. It's not meant or tested to be used for security purposes or compression. Having said that, this algorithm does try to make these hashes unguessable and unpredictable:
hashids = Hashids.new("this is my salt")
hash = hashids.encode(5, 5, 5, 5)
You don't see any repeating patterns that might show there's 4 identical numbers in the hash:
1Wc8cwcE
Same with incremented numbers:
hashids = Hashids.new("this is my salt")
hash = hashids.encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
hash
is now going to be:
kRHnurhptKcjIDTWC3sx
hashids = Hashids.new("this is my salt")
hashids.encode 1 #=> NV
hashids.encode 2 #=> 6m
hashids.encode 3 #=> yD
hashids.encode 4 #=> 2l
hashids.encode 5 #=> rD
hashids = Hashids.new("this is my salt")
hash = hashids.encode_hex('DEADBEEF')
hash
is now going to be:
kRNrpKlJ
hashids = Hashids.new("this is my salt")
hex_str = hashids.decode_hex("kRNrpKlJ")
hex_str
is now going to be:
DEADBEEF
1.0.3
- Support for Ruby 2.4.0
1.0.2
- Handle invalid input by raising InputError
1.0.1
- Final alphabet length can now be shorter than the minimum alphabet length
validate_alphabet
now run before setting up seps & guards
1.0.0
- Public functions renamed to be more appropriate:
encrypt
changed toencode
encrypt_hex
changed toencode_hex
decrypt
changed todecode
decrypt_hex
changed todecode_hex
0.3.0
- Bumped the version number since hashids.rb now support the new algorithm
- Support for
encrypt_hex
anddecrypt_hex
0.0.3
- Default salt (Allows for
Hashids.new.encrypt(91) #=> "kBy"
) - Further tweaking of the private methods (
tr/delete
overgsub
,scan
oversplit
)
0.0.2
- Minitest required if RUBY_VERSION < 1.9.3
- Using scan over split where appropriate
0.0.1
- First commit (Heavily based on the CoffeeScript version)
Follow me @peterhellberg
MIT License. See the LICENSE.txt
file.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request