Barcode Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require baks-dev/barcode
   

   Ensure your server has imagick, libpoppler-glib-dev, and librsvg2-dev installed (see README).

2. Grant Execute Permissions:

   chmod +x vendor/baks-dev/barcode/Writer/Generate
   chmod +x vendor/baks-dev/barcode/Reader/Decode
   chmod +x vendor/baks-dev/barcode/Pdf/PdfCropImg
   

3. First Use Case: Generate a QR code in Laravel:

   use BaksDev\Barcode\Facades\BarcodeGenerator;
   
   $path = BarcodeGenerator::generate('QRCode', 'https://example.com', [
       'save' => true,
       'format' => 'png',
       'outputPath' => storage_path('app/barcodes/qr_example.png'),
   ]);
   

4. Decode a Barcode:

   use BaksDev\Barcode\Facades\BarcodeReader;
   
   $result = BarcodeReader::decode(storage_path('app/barcodes/qr_example.png'));
   // Returns: ['text' => 'https://example.com', 'type' => 'QRCode']
   

5. PDF Integration: Embed a barcode in a PDF:

   use BaksDev\Barcode\Facades\PdfBarcode;
   
   $pdfPath = PdfBarcode::embedBarcode(
       storage_path('app/invoice.pdf'),
       'EAN-13',
       '1234567890128',
       100, // x position
       100  // y position
   );
   

Implementation Patterns

Core Workflows

1. Barcode Generation

• Dynamic Generation: Use facades or service container bindings to generate barcodes on demand:

  // In a controller or service
  public function generateLabel($sku) {
      $path = BarcodeGenerator::generate('EAN-13', $sku, [
          'format' => 'png',
          'outputPath' => storage_path("app/barcodes/{$sku}.png"),
          'scale' => 3,
      ]);
      return response()->file($path);
  }
  

• Batch Processing: Offload to a queue job for high-volume generation (e.g., inventory labels):

  // app/Jobs/GenerateBarcodeJob.php
  public function handle() {
      foreach ($this->products as $product) {
          BarcodeGenerator::generate('DataMatrix', $product->serial_number, [
              'outputPath' => storage_path("app/barcodes/{$product->id}.png"),
          ]);
      }
  }
  

• Storage Integration: Save to disk or cloud storage (e.g., S3) with Laravel’s filesystem:

  use Illuminate\Support\Facades\Storage;
  
  $path = BarcodeGenerator::generate('Code128', 'ABC123', [
      'save' => true,
      'format' => 'png',
      'outputPath' => Storage::disk('s3')->path('barcodes/ABC123.png'),
  ]);
  

2. Barcode Decoding

• API Endpoint for Scanning:

  // routes/api.php
  Route::post('/barcodes/decode', function (Request $request) {
      $file = $request->file('barcode_image');
      $result = BarcodeReader::decode($file->path());
      return response()->json($result);
  });
  

• Validation: Handle decoding failures gracefully:

  try {
      $result = BarcodeReader::decode($imagePath);
      return $result['text'];
  } catch (\Exception $e) {
      Log::error("Barcode decode failed: " . $e->getMessage());
      return null;
  }
  

3. PDF Workflows

• Dynamic Invoice Labels: Embed barcodes in PDFs generated with libraries like barryvdh/laravel-dompdf:

  use BaksDev\Barcode\Facades\PdfBarcode;
  
  $pdf = PDF::loadView('invoice', ['order' => $order]);
  PdfBarcode::embedBarcode(
      $pdf->output(),
      'PDF417',
      $order->tracking_number,
      50, 50
  );
  

• Multi-Page Documents: Use PdfCropImg for complex layouts:

  # CLI usage (e.g., in a Laravel command)
  vendor/baks-dev/barcode/Pdf/PdfCropImg input.pdf output.pdf barcode.png 100 100
  

4. Service Container Integration

• Bind to Interface:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->bind(\BaksDev\Barcode\Contracts\BarcodeGenerator::class, function () {
          return new \BaksDev\Barcode\Services\BarcodeGenerator();
      });
  }
  

• Dependency Injection:

  public function __construct(private BarcodeGenerator $generator) {}
  
  public function createBarcode() {
      $this->generator->generate('QRCode', 'data');
  }
  

Integration Tips

Laravel-Specific Patterns

1. Artisan Commands: Create custom commands for bulk operations:

   // app/Console/Commands/GenerateBulkBarcodes.php
   public function handle() {
       foreach ($this->products as $product) {
           BarcodeGenerator::generate('EAN-13', $product->sku, [
               'outputPath' => storage_path("app/barcodes/{$product->id}.png"),
           ]);
       }
   }
   

2. Events: Trigger events after barcode generation:

   // Listen for barcode generation
   event(new BarcodeGenerated($barcodeData));
   

3. Policies: Restrict barcode generation to authorized users:

   public function generate(User $user, $type, $data) {
       return $user->can('generate-barcodes');
   }
   

Performance Optimization

• Caching: Cache frequently generated barcodes (e.g., product SKUs):

  $path = Cache::remember("barcode_{$sku}", now()->addHours(1), function () use ($sku) {
      return BarcodeGenerator::generate('EAN-13', $sku, ['format' => 'png']);
  });
  

• Queue Jobs: Use Laravel queues for batch processing:

  GenerateBarcodeJob::dispatch($product)->onQueue('barcodes');
  

Testing

• Unit Tests: Mock the generator/reader to test logic:

  $mock = Mockery::mock(\BaksDev\Barcode\Contracts\BarcodeGenerator::class);
  $mock->shouldReceive('generate')->once()->andReturn('/path/to/barcode.png');
  
  $this->app->instance(\BaksDev\Barcode\Contracts\BarcodeGenerator::class, $mock);
  

• Feature Tests: Test barcode generation and decoding:

  public function test_barcode_generation() {
      $path = BarcodeGenerator::generate('QRCode', 'test', ['format' => 'png']);
      $this->assertFileExists($path);
      $this->assertStringContainsString('test', file_get_contents($path));
  }
  

Gotchas and Tips

Pitfalls

1. Imagick Dependencies:

   • Issue: Missing imagick or incorrect permissions cause failures.
   • Fix: Verify installation with php -m | grep imagick and ensure CLI tools have execute permissions.
   • Fallback: Use endroid/qr-code for QR-only cases if Imagick is unavailable.

2. PDF Handling:

   • Issue: PdfCropImg may fail with complex PDFs or unsupported fonts.
   • Fix: Test with sample PDFs first. Use pdftk or ghostscript as alternatives if needed.

3. Barcode Type Limitations:

   • Issue: Some types (e.g., Aztec) may require specific data formats.
   • Fix: Validate input data before generation (e.g., EAN-13 must be 13 digits).

4. Memory Limits:

   • Issue: Large batch processing may hit PHP memory limits.
   • Fix: Increase memory_limit or process in smaller batches.

5. Decoding Accuracy:

   • Issue: Low-quality images may fail to decode.
   • Fix: Preprocess images with imagick (e.g., resize, enhance contrast) before decoding.

6. Path Handling:

   • Issue: Absolute paths in outputPath may break in shared hosting.
   • Fix: Use Laravel’s storage_path() or relative paths.

7. CLI Tool Permissions:

   • Issue: Generate, Decode, or `