Hashids Laravel Package

Getting Started

1. Install via Composer: composer require vinkla/hashids.
2. Run php artisan vendor:publish to generate config/hashids.php.
3. Configure your default connection in config/hashids.php—set a unique salt (critical for security), desired length, and optional alphabet (e.g., remove 0O1l to avoid user confusion).
4. Start using the facade immediately:

   use Vinkla\Hashids\Facades\Hashids;
   $hash = Hashids::encode(42); // e.g., 'xW'
   $ids = Hashids::decode('xW'); // [42]
   

   First use case: obfuscating Eloquent IDs in public URLs (e.g., /posts/42 → /posts/xW).

Implementation Patterns

• Route Model Binding: Use decode() in custom route binding to resolve models from hashed IDs:

  Route::bind('post', function ($hash) {
      [$id] = Hashids::decode($hash) ?: [];
      return Post::findOrFail($id);
  });
  

• API Payloads: Replace raw database IDs in JSON responses to prevent enumeration attacks:

  return response()->json(['id' => Hashids::encode($user->id)]);
  

• Multiple Contexts: Define distinct connections (e.g., admin for internal logs, user-facing for customer URLs) with unique salts and alphabets:

  Hashids::connection('user-facing')->encode($productId); // Safe for public use
  

• DI over Facades: Inject HashidsManager in constructors for testability and avoids global state:

  public function __construct(HashidsManager $hashids) { $this->hashids = $hashids; }
  

• Testing: Mock the manager in feature/unit tests instead of relying on actual encoding logic.

Gotchas and Tips

• Salt Lock-in: Changing salt, alphabet, or min_hash_length breaks all existing hashes—migrate cautiously (e.g., store original IDs if re-encoding is needed).
• Decode Arrays: decode() always returns an array—even for single IDs—so use safe destructuring:

  [$id] = Hashids::decode($hash) ?: []; // Avoids "undefined offset" errors
  

• Silent Failures: encode() returns "0" for non-integers (e.g., strings, null) without throwing—validate inputs first.
• Ambiguous Characters: Avoid 0/O, 1/l/I in alphabet config when hashes are displayed to users (e.g., URL paths) to reduce human error.
• Configuration Priority: config/hashids.php settings override defaults, but the hashids service is lazy-loaded—changes to config require no cache clear (unless using config caching: php artisan config:clear).
• Consider Sqids: The README explicitly notes Hashids is deprecated in favor of Sqids. For new projects, Sqids is recommended—its Laravel bridge (sqids/sqids-php with manual DI) has near-identical API and better Unicode/ID requirements.