Fingerprintbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require atm/fingerprintbundle
   

   Add to config/bundles.php:

   return [
       // ...
       Atm\FingerprintBundle\AtmFingerprintBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan config:publish atm/fingerprint
   

   Update config/packages/atm_fingerprint.yaml with your fingerprint device settings (e.g., device_path, timeout, log_level).

3. First Use Case Capture a fingerprint in a controller:

   use Atm\FingerprintBundle\Service\FingerprintService;
   
   public function captureFingerprint(FingerprintService $fingerprint)
   {
       $fingerprintData = $fingerprint->capture();
       return response()->json($fingerprintData);
   }
   

Implementation Patterns

Common Workflows

1. Enrollment Workflow

   // Enroll a new fingerprint
   $fingerprint->enroll('user_id', 'template_id');
   // Returns: ['status' => 'success', 'template_id' => '12345']
   

2. Verification Workflow

   // Verify against an existing template
   $result = $fingerprint->verify('template_id');
   // Returns: ['status' => 'matched'/'no_match', 'confidence' => 85]
   

3. Template Management

   // Delete a template
   $fingerprint->deleteTemplate('template_id');
   
   // List all templates
   $templates = $fingerprint->listTemplates();
   

Integration Tips

• Event Listeners Bind to fingerprint.captured or fingerprint.verified events in EventServiceProvider:

  protected $listen = [
      'Atm\FingerprintBundle\Events\FingerprintCaptured' => [
          'App\Listeners\LogFingerprintCapture',
      ],
  ];
  

• Middleware for Auth Use middleware to enforce fingerprint verification for sensitive routes:

  public function handle($request, Closure $next)
  {
      if (!$request->user()->hasVerifiedFingerprint()) {
          return redirect()->route('verify.fingerprint');
      }
      return $next($request);
  }
  

• Queue Jobs Offload fingerprint processing to queues (e.g., FingerprintEnrollJob):

  dispatch(new FingerprintEnrollJob($userId, $templateId));
  

Gotchas and Tips

Pitfalls

1. Device Communication

   • Issue: Fingerprint devices may disconnect or return errors.
   • Fix: Implement retry logic with exponential backoff in your service layer:

     $attempts = 3;
     while ($attempts--) {
         try {
             return $fingerprint->capture();
         } catch (\Atm\FingerprintBundle\Exception\DeviceException $e) {
             if ($attempts === 0) throw $e;
             sleep(2 ** $attempts);
         }
     }
     

2. Template ID Collisions

   • Issue: Reusing template IDs across users can cause verification conflicts.
   • Fix: Prefix template IDs with a user-specific salt:

     $templateId = 'user_' . $userId . '_' . $fingerprint->generateTemplateId();
     

3. Permission Handling

   • Issue: Unauthorized users may trigger fingerprint operations.
   • Fix: Gate critical methods in the service:

     public function enroll($userId, $templateId)
     {
         if (!auth()->user()->can('enroll_fingerprint')) {
             throw new \RuntimeException('Unauthorized');
         }
         // ...
     }
     

Debugging

• Enable Verbose Logging Set log_level: debug in config and check storage/logs/fingerprint.log.

• Simulate Device Errors Use the Atm\FingerprintBundle\Tests\MockDevice in tests to simulate failures:

  $fingerprint = new FingerprintService(new MockDevice(['error' => 'device_offline']));
  

Extension Points

1. Custom Device Drivers Extend Atm\FingerprintBundle\Device\AbstractDevice to support new hardware:

   class CustomDevice extends AbstractDevice
   {
       public function capture(): array
       {
           // Custom implementation
       }
   }
   

2. Template Storage Override the default template storage (e.g., switch from DB to Redis):

   $fingerprint->setTemplateStorage(new RedisTemplateStorage());
   

3. Fallback Mechanisms Implement a fallback for when the fingerprint device is unavailable:

   try {
       return $fingerprint->verify($templateId);
   } catch (DeviceException $e) {
       return $this->fallbackVerification($templateId);
   }