Receipt Scanner Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require helgesverre/receipt-scanner
   php artisan vendor:publish --tag="receipt-scanner-config"
   php artisan vendor:publish --provider="OpenAI\Laravel\OpenAIServiceProvider"
   

   Add OPENAI_API_KEY to .env.

2. First Use Case Scan a receipt image from a file:

   use HelgeSverre\ReceiptScanner\Facades\ReceiptScanner;
   
   $result = ReceiptScanner::scan(file_get_contents('path/to/receipt.png'));
   dd($result); // Structured receipt data (e.g., total, items, vendor)
   

3. Key Config Check config/receipt-scanner.php for:

   • model (default: gpt-3.5-turbo).
   • temperature (default: 0.2 for consistency).
   • max_tokens (default: 1000).

Implementation Patterns

Core Workflows

1. OCR + AI Pipeline

   // For PDFs/images (auto-detects OCR via Textract if configured)
   $data = ReceiptScanner::scanFromFile('receipt.pdf');
   

2. Email Attachment Handling

   $email = Mail::getMessage(); // From Laravel Notifications
   $attachments = $email->getAttachments();
   foreach ($attachments as $attachment) {
       $receipt = ReceiptScanner::scan($attachment->getContent());
       // Store in DB
   }
   

3. Batch Processing

   $files = Storage::disk('s3')->files('receipts/');
   foreach ($files as $file) {
       $content = Storage::disk('s3')->get($file);
       $result = ReceiptScanner::scan($content);
       // Process $result
   }
   

Integration Tips

• Laravel Filesystem: Use Storage::disk() to fetch files before scanning.
• Queues: Offload scanning to queues for large volumes:

  ScanReceiptJob::dispatch($filePath)->onQueue('receipts');
  

• Validation: Sanitize inputs (e.g., file types) before passing to scan().
• Fallbacks: Handle OpenAI rate limits with retries:

  try {
      $result = ReceiptScanner::scan($content);
  } catch (\OpenAI\Exceptions\RateLimitException $e) {
      // Implement exponential backoff
  }
  

Gotchas and Tips

Pitfalls

1. OCR Limitations

   • Textract (AWS) requires explicit configuration in .env:

     RECEIPT_SCANNER_OCR=textract
     AWS_ACCESS_KEY_ID=...
     AWS_SECRET_ACCESS_KEY=...
     

   • Fallback to OpenAI’s native OCR if Textract fails (slower but more reliable for some formats).

2. Prompt Sensitivity

   • The default prompt works for 80% of receipts, but custom prompts may be needed for:
     • Multi-language receipts (set locale in config).
     • Non-standard layouts (override via setPrompt()):

       ReceiptScanner::setPrompt(file_get_contents('custom-prompt.txt'));
       

3. Cost Management

   • Monitor token usage (receipts often exceed 1000 tokens). Use max_tokens wisely.
   • Cache results for identical inputs (e.g., duplicate receipts):

     $cacheKey = md5($content);
     $result = cache()->remember($cacheKey, now()->addHours(1), function() use ($content) {
         return ReceiptScanner::scan($content);
     });
     

4. File Size Limits

   • OpenAI has a 4MB limit for image inputs. For larger PDFs:

     // Pre-process PDFs to extract first N pages
     $pdf = \Spatie\PdfToText\Pdf::getText('large-receipt.pdf');
     $firstPage = explode("\n\n", $pdf)[0]; // Simplistic example
     $result = ReceiptScanner::scan($firstPage);
     

Debugging Tips

• Log Raw Outputs: Enable debug mode in config to log OpenAI responses:

  'debug' => env('RECEIPT_SCANNER_DEBUG', false),
  

• Validate Structured Data: Use Laravel’s validate() to ensure expected fields:

  $validated = $result->validate([
      'total' => 'required|numeric',
      'items' => 'array',
      'items.*.description' => 'string',
  ]);
  

• Test with Edge Cases: Validate against:
  • Receipts with tables (may need custom prompts).
  • Handwritten text (OCR accuracy varies).
  • Multi-page PDFs (split pages manually if needed).

Extension Points

1. Custom Models Override the default OpenAI model in config or dynamically:

   ReceiptScanner::setModel('gpt-4'); // For complex receipts
   

2. Post-Processing Extend the scan() result with additional logic:

   $result = ReceiptScanner::scan($content);
   $result->tax_rate = $result->total / (1 + $result->tax_percentage);
   

3. Event Listeners Dispatch events after scanning:

   event(new ReceiptScanned($result));
   

   Listen for validation/processing:

   ReceiptScanned::listen(function ($event) {
       $event->receipt->save();
   });