Hashids Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require danilovl/hashids-bundle
   

   Ensure Danilovl\HashidsBundle\HashidsBundle::class is registered in config/bundles.php.

2. Configuration: Add basic settings in config/services.yaml:

   danilovl_hashids:
     salt: 'your-secret-salt-here'
     min_hash_length: 12  # Adjust based on security needs
   

3. First Use Case: Encode an ID in a controller:

   use Danilovl\HashidsBundle\Service\HashidsService;
   
   class MyController {
       public function __construct(private HashidsService $hashids) {}
   
       public function show(int $id) {
           $hash = $this->hashids->encode($id);
           return response()->json(['hash' => $hash]);
       }
   }
   

Implementation Patterns

Core Workflows

1. Encoding/Decoding IDs:

   // Encode
   $hash = $this->hashids->encode([1, 2, 3]); // Returns "abc123xyz"
   
   // Decode
   $ids = $this->hashids->decode("abc123xyz"); // Returns [1, 2, 3]
   

2. ParamConverter Integration: Enable in config/services.yaml:

   danilovl_hashids:
     enable_param_converter: true
   

   Now route params like /user/{id:hashids} will auto-decode to integers.

3. Batch Processing:

   $hashes = $this->hashids->encode([100, 200, 300]); // Array of hashes
   $decoded = $this->hashids->decode($hashes); // Array of arrays
   

Integration Tips

• API Responses: Use hashes for opaque IDs in JSON APIs to hide internal DB IDs.
• URLs: Store hashes in URLs (e.g., /product/{hash}) for obfuscation.
• Validation: Combine with Symfony’s validator to ensure hashes meet min_hash_length.

Gotchas and Tips

Pitfalls

1. Salt Management:

   • Never hardcode salts in version control. Use environment variables or Symfony’s parameter_bag.
   • Example: salt: '%env(APP_HASHIDS_SALT)%'.

2. ParamConverter Quirks:

   • Only works for integer IDs. Non-integers (e.g., UUIDs) will fail silently.
   • Test with enable_param_converter: false during development to avoid confusion.

3. Collision Risks:

   • Short min_hash_length (e.g., <12) increases collision probability. Monitor logs for decode failures.

Debugging

• Decode Failures: Check if the hash matches the configured alphabet and salt.
• Logs: Enable debug mode to see raw decode attempts:

  danilovl_hashids:
    debug: true
  

Extension Points

1. Custom Alphabets: Override the default alphabet in config:

   danilovl_hashids:
     alphabet: 'custom123ABC!@#'
   

2. Event Listeners: Extend the bundle by subscribing to hashids.encode/hashids.decode events (if supported in future versions).

3. Testing: Mock HashidsService in tests:

   $this->hashids->shouldReceive('encode')->andReturn('test123');