hashids turns a number into a reversible id, and the salt is what makes it yours
A small PHP library to generate YouTube-like ids from numbers. Use it when you don't want to expose your database ids to the user.
At a glance
- What is it?
- hashids is one PHP class that converts database numbers into YouTube-like ids, with a salt, a minimum length, a custom alphabet, hex mode for Mongo ObjectIds and a built-in filter that keeps curse words out of URLs. It is small, MIT licensed, explicitly not an encryption tool, and its creator now points new projects at a successor called Sqids.
- Who is it for?
- hashids solves one narrow problem: turning a database number into an id you would rather not show a user, reversibly, with a salt you control and a curse word filter you did not ask for. Use it where you already depend on it, and settle the salt question first, because an id generated without one is the same in every project on earth.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- vinkla/hashids5,424 ★ · -3
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| vinkla/hashids | 5.4k | 5.4k |
-3 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Installation is one Composer line and one math extension
hashids is a single class you pull in with Composer and call directly. That is the whole installation surface:
composer require hashids/hashidsOne requirement is not implied by that line. The library needs either the bcmath extension or the gmp extension in order to work. With that sorted, the first call is three lines:
use Hashids\Hashids;
$hashids = new Hashids();
$hashids->encode(1);Notice what the no-argument constructor hands you: the same configuration every other project that never sets a salt is using. The constructor takes three optional arguments, salt first, then a minimum length, then an alphabet, and every example that follows changes the output by filling them in. That makes the default a poor choice for anything user facing, because your first record encodes to the same id it would encode to on somebody else's server.
The salt changes every id, and seven letters never touch
Passing a project name as the first argument makes the output yours:
use Hashids\Hashids;
$hashids = new Hashids('My Project');
$hashids->encode(1, 2, 3); // Z4UrtW
$hashids = new Hashids('My Other Project');
$hashids->encode(1, 2, 3); // gPUasbSame three numbers, same default alphabet, two different ids, and the salt is the only difference between them. That makes the salt part of your data rather than part of your configuration: an id generated under one project name is not what the library produces under another, so the string has to be kept somewhere stable next to your records, and changing it rewrites every id you ever handed out.
The alphabet does more than shuffle characters. Because these ids are meant to sit in visible places such as a URL, the algorithm tries to avoid generating most common English curse words, and it does that with a blunt rule: it never places these letters next to each other.
c, f, h, i, s, t, uEvery id it produces avoids the adjacent pair that would spell the word. The benefit is that a screenshot of one of your URLs does not turn into an insult aimed at your user.
Padding is a floor, and a custom alphabet rewrites every character
The second constructor argument is a minimum length:
use Hashids\Hashids;
$hashids = new Hashids(); // no padding
$hashids->encode(1); // jR
$hashids = new Hashids('', 10); // pad to length 10
$hashids->encode(1); // VolejRejNmThe empty salt is needed only to reach the second parameter, which is the ergonomic cost of a positional constructor. The number 1 becomes two characters with no salt and ten characters once the length is set. Read it as a floor: output ids are padded to at least that length and never to exactly it, so a number that already needs more room produces something longer than the number you asked for.
The third argument replaces the character set outright:
use Hashids\Hashids;
$hashids = new Hashids('', 0, 'abcdefghijklmnopqrstuvwxyz'); // all lowercase
$hashids->encode(1, 2, 3); // mdfphxThe same three numbers that produce o2fXhV with the default alphabet, entirely lowercase here. A custom alphabet is how you keep ids inside the character set your database collation, your router or your reserved word list is comfortable with, and it is also the fastest way to break every id you already published, since the output depends on it as much as the salt does.
Decoding returns an array and junk input returns an empty string
Three behaviours will catch you out, and all three are written down rather than left for you to find.
Decoding always gives you an array, even when a single number went in:
use Hashids\Hashids;
$hashids = new Hashids();
$id = $hashids->encode(1);
$hashids->decode($id); // [1]Input that is not a number produces an empty string instead of an exception:
use Hashids\Hashids;
$hashids = new Hashids();
$id = $hashids->encode('123a');
$id === ''; // trueThat pair is the dangerous one, because an empty string is a value a route will publish without complaint. Check that the id is non-empty before storing it, since bogus input returns an empty string rather than an id. Negative numbers are not supported at all, so a signed identifier from your database cannot go through this path.
And the security question has a one line answer: hashids is not an encryption library, it should not be used as a security measure, and sensitive data must not be encoded with it. It is reversible by design, which is the feature and the warning at the same time.
Hex mode takes a Mongo ObjectId or anything longer
Hex mode exists for identifiers that already arrive as hex strings, most obviously a MongoDB ObjectId:
use Hashids\Hashids;
$hashids = new Hashids();
$id = $hashids->encodeHex('507f1f77bcf86cd799439011'); // y42LW46J9luq3Xq9XMly
$hex = $hashids->decodeHex($id); // 507f1f77bcf86cd799439011encodeHex() and decodeHex() are a matched pair, and decodeHex() hands back the string you started with. The scope is wider than ObjectId: there is no limit on how large a hex number you can pass, and it does not have to be a Mongo ObjectId, so anything that already lives in hex can be put through the same transform.
Since Hashids is not an encryption library, the encoded form belongs on a public record id and nowhere near a token.
No visible pattern for repeats, and no compression either
The claim being made here is modest and worth repeating accurately: the primary purpose is to obfuscate numeric ids, it is not meant or tested to be used as a security or compression tool, and the algorithm does try to make the ids random and unpredictable.
Two examples back the unpredictability half. Repeated numbers produce nothing that looks repeated:
use Hashids\Hashids;
$hashids = new Hashids();
$hashids->encode(5, 5, 5); // A6t1tQAnd a run of numbers becomes one id rather than a series of them:
use Hashids\Hashids;
$hashids = new Hashids();
$hashids->encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10); // wpfLh9iwsqt0uyCEFjHM
$hashids->encode(1); // jR
$hashids->encode(2); // k5
$hashids->encode(3); // l5
$hashids->encode(4); // mO
$hashids->encode(5); // nRTen numbers in, one id out, and that id is longer than the digits it stands for. Compression is the job this library does not take, so anyone reaching for it to shorten identifiers has picked the wrong tool.
You reverse the id to get the numbers back and use your indexes as you always did.
Last release in 2023, and the successor has a different name
Two dates say more than the version number. The last push to master was on 2026-04-16, while the newest release in the feed is 5.0.2 from 2023-02-23, preceded by 5.0.1 on the same day and 5.0.0 on 2023-02-14. The source tree keeps moving and the tagged releases have not followed since 2023.
The layout is small and honest about what the project is: composer.json, src/, tests/, phpunit.xml.dist for the test runner, CHANGELOG.md, LICENSE and an .editorconfig, with no application code wrapped around the library. The licence is MIT. There is no configuration file to read and no service to run, which is also why there is nothing here about runtime behaviour beyond the class itself.
The larger question for anyone starting fresh sits in a note at the top of the page. The creator has released a new, upgraded version rebranded as Sqids, hashids itself is described as continuing to be maintained and available for future use, and the technical comparison lives on the Sqids site rather than in this repository. Nothing here explains what changed under the new name, so the decision for a new project is between a package whose last tag is from 2023 and its successor, and the Sqids website is where that comparison is actually made.
Editorial conclusion
hashids solves one narrow problem: turning a database number into an id you would rather not show a user, reversibly, with a salt you control and a curse word filter you did not ask for. Use it where you already depend on it, and settle the salt question first, because an id generated without one is the same in every project on earth. Do not use it to hide anything sensitive, since the library states outright that it is not encryption, and do not expect ids to get shorter. If you are choosing today rather than inheriting the dependency, read the Sqids comparison at sqids.org first, because the last tagged release of hashids itself is 5.0.2 from 2023-02-23.
Frequently asked questions
How does hashids compare with Sqids?
The creator of hashids released a new, upgraded version rebranded as Sqids, which ships as its own PHP package. hashids is described as continuing to be maintained and available for future use, and the technical comparison is on the Sqids site at sqids.org/faq#hashids rather than in this repository.
What is an alternative to hashids?
Sqids is the alternative named here, released by the same creator as an upgraded and rebranded version of hashids. hashids itself remains available and is described as continuing to be maintained, so replacing it is a choice rather than a migration forced by abandonment.
Is hashids safe to use for sensitive data?
No. hashids is not an encryption library, it should not be used as a security measure, and sensitive data must not be encoded with it. Its stated purpose is obfuscating numeric ids, and decode() reverses them.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/vinkla-hashids)Star history chart for your README
[](https://hysenlabs.com/projects/vinkla-hashids)Was this useful?