Hash Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dynamophp/hash-bundle
   

   Ensure DynamoPHP\HashBundle\DynamoPHPHashBundle::class is registered in config/bundles.php.

2. Basic Configuration: Add to config/packages/dynamo_php_hash.yaml:

   dynamo_php_hash:
       start_selection: 3
       end_selection: 0
   

   (Default values: start_selection: 3, end_selection: 0 if omitted.)

3. First Use Case: Inject DynamoHasherInterface into a controller/service and call hash():

   use DynamoPHP\HashBundle\Service\DynamoHasherInterface;
   
   public function demo(DynamoHasherInterface $hasher) {
       $result = $hasher->hash('input_string'); // Returns truncated SHA-256 hash
       return new Response($result);
   }
   

Where to Look First

• Bundle Docs: Dynamo-PHP-Hash Lib for algorithm details.
• Service Interface: DynamoHasherInterface (only method: hash(string $input): string).
• Default Config: config/packages/dynamo_php_hash.yaml (overridable via environment variables).

Implementation Patterns

Core Workflows

1. Hashing User Inputs:

   // Truncate SHA-256 to first 3 + last 0 hexits (default)
   $hashed = $hasher->hash($userInput);
   

   Use for lightweight hashing (e.g., session tokens, non-sensitive IDs).

2. Custom Hash Selection: Override config to adjust truncation:

   dynamo_php_hash:
       start_selection: 2  # First 2 hexits
       end_selection: 1   # Last 1 hexit
   

   Re-inject the service to reflect changes.

3. Dependency Injection:

   // Service container alias (if needed)
   $this->container->get('dynamo_php_hash.hasher');
   

4. Event-Driven Hashing: Dispatch events before/after hashing via Symfony’s event system:

   $event = new PreHashEvent($input);
   $this->eventDispatcher->dispatch($event, PreHashEvent::NAME);
   $hashed = $hasher->hash($event->getInput());
   

Integration Tips

• Validation: Combine with Symfony’s Validator to ensure hash consistency:

  $constraint = new Length(['min' => 1, 'max' => 64]); // Adjust based on config
  $this->validator->validate($hashed, $constraint);
  

• Caching: Cache hashed results for static inputs (e.g., config keys):

  $cache = $this->cache->get('hash_' . $input, function() use ($hasher, $input) {
      return $hasher->hash($input);
  });
  

• Testing: Mock DynamoHasherInterface in PHPUnit:

  $this->mockBuilder->getMockBuilder(DynamoHasherInterface::class)
      ->disableOriginalConstructor()
      ->getMock()
      ->method('hash')
      ->willReturn('mocked_hash');
  

Gotchas and Tips

Pitfalls

1. Non-Deterministic Output:

   • The bundle’s truncation logic (start_selection/end_selection) may produce collisions for similar inputs. Avoid using for security-sensitive data (e.g., passwords).
   • Workaround: Use for non-cryptographic purposes only (e.g., lightweight IDs).

2. Config Overrides:

   • Environment variables (e.g., %env(DYNAMO_HASH_START)%) do not override YAML config by default. Use parameter_bag in services.yaml:

     parameters:
         dynamo_hash.start_selection: '%env(int:DYNAMO_HASH_START)%'
     

3. SHA-256 Dependency:

   • The bundle only supports SHA-256 as the primary hash function. Extending to other algorithms requires modifying the underlying library.

4. Service Immutability:

   • The DynamoHasherInterface instance is singleton-scoped. Changes to config require a service restart or re-injection.

Debugging

• Unexpected Hash Length: Verify start_selection + end_selection does not exceed SHA-256’s hex length (64). Example:

  # Fails (70 > 64)
  dynamo_php_hash:
      start_selection: 40
      end_selection: 30
  

  Fix: Adjust values or use end_selection: 0 to disable suffix truncation.

• Case Sensitivity: Input strings are case-sensitive. Normalize inputs (e.g., mb_strtolower()) for consistency.

Extension Points

1. Custom Hasher: Implement DynamoHasherInterface and register as a service:

   services:
       App\Service\CustomHasher:
           tags: ['dynamo_php_hash.hasher']
   

   Note: Requires modifying the bundle’s DynamoHasher class to support multiple hashers.

2. Event Listeners: Extend hashing logic via Symfony events:

   // src/EventListener/HashListener.php
   class HashListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [PreHashEvent::NAME => 'onPreHash'];
       }
       public function onPreHash(PreHashEvent $event) {
           $event->setInput(strtoupper($event->getInput()));
       }
   }
   

3. Configuration Validation: Add custom validation to config/packages/dynamo_php_hash.yaml:

   dynamo_php_hash:
       start_selection: 3
       end_selection: 0
       # Custom constraint (via Symfony Validator)
       constraints:
           - Symfony\Component\Validator\Constraints\Expression:
               expression: "value.start_selection + value.end_selection <= 64"
               message: "Total selection must not exceed 64 hexits."