Php Qrcode Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require chillerlan/php-qrcode
   

   Ensure PHP 8.4+ with ext-mbstring and optionally ext-gd/ext-imagick for image output.

2. First Use Case: Generate a QR code from a string and output it directly:

   $qrCode = new \chillerlan\QRCode\QRCode();
   echo $qrCode->render('https://example.com');
   

   This outputs a Base64-encoded data URI (e.g., data:image/png;base64,...).

3. Where to Look First:

   • Official Documentation
   • Examples Folder (version-specific)
   • API Reference

Implementation Patterns

Core Workflow

1. Instantiation:

   // Default options
   $qrCode = new \chillerlan\QRCode\QRCode();
   
   // Custom options (v6+)
   $options = new \chillerlan\QRCode\QROptions([
       'version' => 10,
       'eccLevel' => \chillerlan\QRCode\EccLevel::H,
   ]);
   $qrCode = new \chillerlan\QRCode\QRCode($options);
   

2. Rendering:

   • Inline Output (e.g., for HTML):

     echo '<img src="' . $qrCode->render('data') . '" alt="QR Code" />';
     

   • File Output:

     $qrCode->render('data', 'path/to/qrcode.png');
     

   • Resource Output (for post-processing):

     $qrCode->getOptions()->outputInterface = \chillerlan\QRCode\QRGdImage::class;
     $qrCode->getOptions()->returnResource = true;
     $resource = $qrCode->render('data');
     

3. Reading QR Codes:

   $reader = new \chillerlan\QRCode\QRReader();
   $result = $reader->read('path/to/qrcode.png');
   echo $result->getData(); // Extracted data
   

Common Patterns

• Dynamic Options:

  $qrCode->getOptions()->version = 5; // Modify after instantiation
  

• Mixed Mode Encoding:

  $qrCode->clearSegments()
      ->addNumericSegment('12345')
      ->addAlphaNumSegment('ABCD')
      ->addByteSegment(\chillerlan\QRCode\QRDataMode::ECI_UTF8, '日本語');
  

• Output Format Control:

  $qrCode->getOptions()->outputType = \chillerlan\QRCode\QROutputInterface::GDIMAGE_SVG;
  

Integration Tips

• Laravel Blade:

  // In a Blade view
  {!! \chillerlan\QRCode\QRCode::format('png')->size(300)->render('data') !!}
  

• API Responses:

  return response()->json([
      'qr_code' => $qrCode->render('data'),
  ]);
  

• Queue Jobs:

  // Dispatch a job to generate QR codes asynchronously
  GenerateQRCode::dispatch($data, $path);
  

Gotchas and Tips

Pitfalls

1. Output Format Mismatch:

   • Ensure ext-gd or ext-imagick is installed for image outputs.
   • Defaults to Base64 URI; disable with $options->outputBase64 = false.

2. Character Encoding:

   • Set mb_internal_encoding('UTF-8') for non-ASCII data (e.g., Japanese/Chinese).
   • Validate strings before adding segments:

     if (!\chillerlan\QRCode\QRDataMode\Hanzi::validateString($data)) {
         throw new \InvalidArgumentException('Invalid Hanzi data');
     }
     

3. Version/Size Limits:

   • QR codes have a version limit (1–40). Long data may require higher versions or error correction (ECC).
   • Test with $qrCode->getOptions()->version = 40 if data exceeds limits.

4. Reader Limitations:

   • The reader requires either GD or ImageMagick (ext-gd/ext-imagick).
   • Low-quality images may fail to decode. Use high-resolution sources.

5. Caching:

   • cachefile in QROptions saves rendered QR codes to disk. Clear manually if needed:

     if (file_exists($options->cachefile)) {
         unlink($options->cachefile);
     }
     

Debugging Tips

• Check Output:

  $qrCode->getOptions()->debug = true; // Logs warnings/errors
  

• Inspect Matrix:

  $matrix = $qrCode->getQRMatrix();
  var_dump($matrix->getMatrix()); // Debug module layout
  

• Validate Data: Use QRDataModeInterface::validateString() for each segment type before encoding.

Extension Points

1. Custom Output Modules: Implement QROutputInterface for new formats (e.g., WebP):

   class QRWebP implements QROutputInterface {
       public function render(QRMatrix $matrix, QROptions $options): string {
           // Custom logic
       }
   }
   

   Register via:

   $qrCode->getOptions()->outputInterface = QRWebP::class;
   

2. Extend QROptions: Add custom settings via traits or inheritance:

   class CustomOptions extends \chillerlan\QRCode\QROptions {
       protected string $customParam = 'default';
   }
   

3. Override Defaults: Use setOptions() or pass options directly to the constructor:

   $qrCode = new \chillerlan\QRCode\QRCode([
       'outputType' => QROutputInterface::GDIMAGE_SVG,
       'size' => 500,
   ]);
   

Performance Notes

• Caching: Reuse QRCode instances with shared options for repeated generations.
• Memory: Large QR codes (high versions) consume more memory. Use QRMatrix for manual control:

  $matrix = $qrCode->getQRMatrix();
  $qrCode->renderMatrix($matrix, 'output.png');
  

Laravel-Specific Quirks

• Service Provider: Bind the package to the container for dependency injection:

  $this->app->singleton(\chillerlan\QRCode\QRCode::class, function ($app) {
      return new \chillerlan\QRCode\QRCode($app['config']['qrcode.options']);
  });
  

• Config: Publish config for global settings:

  php artisan vendor:publish --provider="chillerlan\QRCode\QRCodeServiceProvider"