Qrcode Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bushidoio/qrcode-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       BushidoIO\QRCodeBundle\BushidoIOQRCodeBundle::class => ['all' => true],
   ];
   

2. Enable Routes: Ensure config/routes.yaml includes:

   bushidoio_qrcode:
       resource: "@BushidoIOQRCodeBundle/Controller/"
       type: annotation
   

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

   {{ 'https://example.com'|qrcode }}
   

   Outputs a <img> tag with the QR code.

Where to Look First

• Twig Filters/Functions: Check src/Resources/views/ for Twig templates and DependencyInjection/ for service definitions.
• Configuration: Defaults are in Resources/config/services.yaml; override in config/packages/bushidoio_qrcode.yaml.
• Controller: Controller/QRCodeController.php for direct API usage.

Implementation Patterns

Common Workflows

1. Twig Integration:

   • Use |qrcode filter for URLs or |qrcode_base64 for inline images:

     <img src="{{ 'data:text/plain;base64,' ~ 'SGVsbG8='|qrcode_base64 }}" />
     

   • Customize size/mask via Twig arguments:

     {{ 'text'|qrcode({ size: 200, mask: 'best' }) }}
     

2. API Endpoints:

   • Generate QR codes via HTTP:

     curl "http://app.dev/qrcode?text=Hello&size=300&format=png"
     

   • Cache responses with Cache-Control headers (configurable via cache_expiration).

3. Symfony Services:

   • Inject BushidoIO\QRCodeBundle\Service\QRCodeService for programmatic use:

     $service->generate('https://example.com', ['size' => 500]);
     

4. Cache Optimization:

   • Store generated images outside Symfony’s cache directory (configure via cache_dir).
   • Set cache_expiration (e.g., 3600 for 1 hour) to reduce CPU load.

Integration Tips

• Dynamic Content: Use Twig in controllers to generate QR codes for user-specific data:

  return $this->render('page.html.twig', [
      'user_qr' => $user->email . '|' . $user->id,
  ]);
  

  {{ user_qr|qrcode }}
  

• Asset Pipeline: For static QR codes, pre-generate and reference via assets:install:

  php bin/console bushidoio:qrcode:generate --text="StaticText" --output=public/qr/
  

• Testing: Mock QRCodeService in PHPUnit:

  $this->createMock(QRCodeService::class)
       ->method('generate')
       ->willReturn('<img src="mock.png" />');
  

Gotchas and Tips

Pitfalls

1. Cache Directory Permissions:

   • Ensure cache_dir (default: var/cache/qrcode/) is writable by the web server.
   • Debug: touch var/cache/qrcode/ and check permissions (chmod -R 775 var/cache/).

2. Image Size Limits:

   • Default max_size (1024px) may cause distortion for large text. Override in config:

     bushidoio_qrcode:
         max_size: 2048
     

3. Twig Filter Scope:

   • The |qrcode filter requires the bundle’s Twig extension. If missing, clear cache:

     php bin/console cache:clear
     

4. HTTPS Mixed Content:

   • If serving QR codes via HTTP on an HTTPS site, configure cache_expiration_ssl separately:

     bushidoio_qrcode:
         cache_expiration: 3600
         cache_expiration_ssl: 86400
     

Debugging

• Logs: Enable debug mode (APP_DEBUG=true) and check var/log/dev.log for QRCodeBundle errors.
• Output Validation: Verify generated QR codes using QR Code Reader.
• Common Issues:
  • Blank Images: Check cache_dir permissions or max_size constraints.
  • 404 Routes: Ensure routing.yml is loaded and the bushidoio_qrcode route is enabled.

Extension Points

1. Custom Masks:

   • Extend the QR code mask logic by overriding the QRCodeService:

     // src/Service/CustomQRCodeService.php
     class CustomQRCodeService extends \BushidoIO\QRCodeBundle\Service\QRCodeService {
         protected function getMask() { return 'custom_mask'; }
     }
     

   • Bind it in config/services.yaml:

     services:
         App\Service\CustomQRCodeService: ~
     

2. New Formats:

   • Add support for SVG/PDF by extending QRCodeController and updating the generate method.

3. Event Listeners:

   • Hook into QR code generation via Symfony events (e.g., kernel.request):

     public function onKernelRequest(GetResponseEvent $event) {
         if ($event->getRequest()->query->has('qrcode')) {
             // Modify generation logic
         }
     }
     

Pro Tips

• Batch Generation: Use Symfony’s Messenger component to queue QR code generation for background processing:

  $this->messageBus->dispatch(new GenerateQRCodeMessage($text, $outputPath));
  

• Analytics: Track QR code usage by appending UTM parameters:

  {{ ('https://example.com?utm_source=qrcode')|qrcode }}
  

• Theming: Override Twig templates in templates/bundles/bushidoioqrcode/ to customize the <img> tag (e.g., add class or data-* attributes).