Qrcode Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bushidoio/qrcode-bundle:dev-master
   

   Enable the bundle in app/AppKernel.php:

   new BushidoIO\QRCodeBundle\BushidoIOQRCodeBundle(),
   

   Add the route in app/config/routing.yml:

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

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

   {{ qrcode('https://example.com', { 'size': 10 }) }}
   

   Or via PHP:

   use BushidoIO\QRCodeBundle\Generator\QRCodeGenerator;
   $generator = $this->get('bushidoio_qrcode.generator');
   $qrCode = $generator->generate('https://example.com', ['size' => 10]);
   

Implementation Patterns

Common Workflows

1. Twig Integration: Use the Twig filter (qrcode) or function (qrcode()) for dynamic QR code generation in templates:

   {# Filter #}
   {{ 'https://example.com' | qrcode({ 'size': 12, 'mask': 'best' }) }}
   
   {# Function #}
   {{ qrcode('https://example.com', { 'size': 12, 'mask': 'best' }) }}
   

2. Controller-Based Generation: Inject the QRCodeGenerator service and generate QR codes programmatically:

   public function generateAction($content, $size = 10)
   {
       $generator = $this->get('bushidoio_qrcode.generator');
       $qrCode = $generator->generate($content, ['size' => $size]);
       return new Response($qrCode, 200, ['Content-Type' => 'image/png']);
   }
   

3. Caching for Performance: Leverage the built-in caching to reduce CPU usage:

   # app/config/config.yml
   bushidoio_qrcode:
       cache:
           enabled: true
           expiration: 3600  # Cache for 1 hour
           path: "%kernel.cache_dir%/qrcodes"
   

4. Dynamic URL Generation: Use absolute or relative URLs in QR codes:

   {# Absolute URL #}
   {{ qrcode('https://example.com/qr', { 'absolute_url': true }) }}
   
   {# Relative URL #}
   {{ qrcode('/qr', { 'absolute_url': false }) }}
   

5. Base64 Encoding: Generate QR codes as Base64 strings for inline use (e.g., in emails or APIs):

   $base64QrCode = $generator->generateBase64('https://example.com');
   

Gotchas and Tips

Pitfalls

1. Deprecated Bundle: The last release was in 2017, so ensure compatibility with your Symfony version (tested up to Symfony 2.x). For Symfony 3/4/5, consider alternatives like miloschuman/php-qrcode-bundle.

2. Cache Path Issues: If cache paths are misconfigured (e.g., outside Symfony’s writable directories), QR codes may fail silently. Verify permissions:

   bushidoio_qrcode:
       cache:
           path: "%kernel.cache_dir%/qrcodes"  # Default; ensure this dir is writable
   

3. Mask Configuration: The mask parameter (best, random, or a numeric value) affects QR code readability. Use best for critical data:

   {{ qrcode('data', { 'mask': 'best' }) }}
   

4. Size Limits: The default max size is 1024 pixels. Exceeding this may cause errors or distorted QR codes. Adjust in config:

   bushidoio_qrcode:
       max_size: 2048  # Increase if needed
   

5. Routing Conflicts: The bundle’s routes (/qrcode/...) may clash with existing routes. Prefix or customize routes in routing.yml:

   bushidoio_qrcode_custom:
       resource: "@BushidoIOQRCodeBundle/Controller/"
       type: annotation
       prefix: /api/qr
   

Debugging Tips

1. Check Logs: Enable debug mode (APP_DEBUG=true) to inspect cache or generation errors in app/logs/dev.log.

2. Validate Output: Use a QR code scanner (e.g., smartphone app) to verify generated codes. Incorrect masks or sizes may cause scanning failures.

3. Clear Cache: After config changes, clear Symfony’s cache:

   php app/console cache:clear
   

Extension Points

1. Custom Generators: Extend the QRCodeGenerator service to add logic (e.g., logging, analytics):

   // src/BushidoIO/QRCodeBundle/DependencyInjection/Compiler/OverrideGeneratorPass.php
   public function process(ContainerBuilder $container)
   {
       $definition = $container->findDefinition('bushidoio_qrcode.generator');
       $definition->addMethodCall('setCustomLogic', ['your_logic_here']);
   }
   

2. Twig Extensions: Override or extend Twig filters/functions in your bundle’s Resources/config/services.yml:

   services:
       your_bundle.qrcode_extension:
           class: Your\Bundle\Twig\QRCodeExtension
           tags:
               - { name: twig.extension }
   

3. Event Listeners: Hook into QR code generation events (if the bundle supports them) to modify behavior dynamically. Example:

   // src/YourBundle/EventListener/QRCodeListener.php
   public function onGenerate(QRCodeEvent $event)
   {
       $event->setSize($event->getSize() * 2); // Double size
   }