Quar Laravel Package

Getting Started

Minimal Steps

1. Installation: Add the package via Composer:

   composer require tuncaybahadir/quar
   

2. First Usage: Generate a basic QR code in a controller or service:

   use tbQuar\Facades\Quar;
   
   $qrCode = Quar::generate('https://example.com');
   

3. Display in Blade: Pass the generated QR code to a view:

   <div>{{ $qrCode }}</div>
   

Where to Look First

• Facade API: The tbQuar\Facades\Quar facade provides a fluent interface for all QR code customizations.
• README.md: The package's README includes visual examples for all features (e.g., gradients, logos, text overlays).
• Changelog: Check for recent updates (e.g., Laravel 13 support, PHP 8.5 compatibility).

First Use Case

Generate a QR code for a user profile link and save it to storage:

$qr = Quar::format('png')
    ->size(200)
    ->color('#32a852')
    ->generate("https://app.example.com/profile/{$user->id}", storage_path("app/qr_{$user->id}.png"));

Implementation Patterns

Core Workflows

1. Dynamic QR Code Generation

Use the facade in controllers or services to generate QR codes on-the-fly:

// In a controller
public function generateInvoiceQr($invoiceId) {
    $qr = Quar::size(150)
        ->color('#2c3e50')
        ->eye('rounded')
        ->generate("invoice/{$invoiceId}");
    return view('invoice', ['qr' => $qr]);
}

2. Batch Processing

Generate multiple QR codes in a loop (e.g., for bulk exports):

$products = Product::all();
foreach ($products as $product) {
    $qr = Quar::size(100)
        ->generate("product/{$product->slug}")
        ->saveAs(storage_path("app/qr_products/{$product->id}.png"));
}

3. Conditional Logic with when()

Leverage Laravel’s Conditionable trait for dynamic QR code customization:

$qr = Quar::size(200)
    ->when($user->isPremium, function ($qr) {
        $qr->gradient(255, 0, 0, 0, 0, 255, 'horizontal');
    })
    ->generate($user->profileUrl);

4. Text Overlays for Context

Add descriptive text to QR codes (e.g., for tickets or labels):

$qr = Quar::size(300)
    ->withText("Event Ticket: {$event->name}")
    ->configureText(function ($text) {
        $text->setPosition('bottom')
             ->setFontSize(10)
             ->setTextColor('#ffffff')
             ->setBackgroundColor('#000000')
             ->setBackgroundOpacity(0.7);
    })
    ->generate("event/{$event->ticket_code}");

5. Logo Integration

Embed logos for branding (ensure margin(1) is set to avoid rendering bugs):

$qr = Quar::format('png')
    ->margin(1)
    ->merge(public_path('assets/logo.png'), 0.25)
    ->size(400)
    ->generate("https://example.com");

Integration Tips

Laravel Views

• Base64 Encoding: For inline QR codes in Blade:

  <img src="data:image/png;base64,{{ base64_encode($qr) }}" />
  

• Storage Paths: Use storage_path() for file-based QR codes:

  $path = storage_path("app/qr_codes/{$user->id}.png");
  Quar::generate($url, $path);
  

API Responses

Return QR codes as binary responses:

return response($qr, 200, [
    'Content-Type' => 'image/png',
    'Content-Disposition' => "inline; filename=\"qr_{$id}.png\"",
]);

Testing

Mock the facade in tests:

$mockQr = Mockery::mock('alias:tbQuar\Facades\Quar');
$mockQr->shouldReceive('generate')
       ->with('test-url')
       ->andReturn('<img src="data:image/png;base64,...">');

Performance

• Caching: Cache generated QR codes for static content:

  $qr = Cache::remember("qr_{$url}", now()->addHours(1), function () use ($url) {
      return Quar::generate($url);
  });
  

• Compression: Reduce file size for storage:

  Quar::setPngCompression(75)->generate($url, $path);
  

Gotchas and Tips

Pitfalls

1. Logo Rendering Bug

   • Issue: Logos may appear misaligned or cropped if margin() is not set to 1 or higher.
   • Fix: Always include ->margin(1) before ->merge():

     Quar::margin(1)->merge($logoPath, $scale)->size(400)->generate($url);
     

2. Hex Color Parsing

   • Issue: Hex colors (e.g., '#32a852') must be passed as strings, not arrays.
   • Fix: Use ->color('#32a852') instead of ->color([50, 168, 82]) for hex values.

3. Text Overlay Conflicts

   • Issue: Custom text configurations may override default styles unexpectedly.
   • Fix: Chain ->withText() before other modifiers:

     Quar::withText('Label')->configureText(...)->size(300)->generate($url);
     

4. File Permissions

   • Issue: QR codes saved to storage/ may fail if directories lack write permissions.
   • Fix: Run php artisan storage:link and ensure storage/app is writable:

     chmod -R 755 storage/app
     

5. Gradient Limits

   • Issue: Gradients require 6 RGB values (start and end colors).
   • Fix: Use ->gradient(R, G, B, R, G, B, 'type'):

     Quar::gradient(255, 0, 0, 0, 0, 255, 'horizontal')->generate($url);
     

Debugging

• Inspect Generated Code: Use dd($qr) to verify the output before rendering.
• Check File Paths: Ensure paths in ->generate($url, $path) are absolute and writable.
• Validate Dependencies: Confirm bacon/bacon-qrcode and simplesoftwareio/simple-qrcode are up-to-date.

Extension Points

1. Custom Text Styling Extend the TextOverlay class to add features like custom fonts:

   // app/Services/CustomTextOverlay.php
   use tbQuar\TextOverlay;
   
   class CustomTextOverlay extends TextOverlay {
       public function setCustomFont($path) {
           $this->font = $path;
           return $this;
       }
   }
   

   Then use it via the facade:

   Quar::withText('Custom')->configureText(function ($text) {
       $text->setCustomFont(public_path('fonts/roboto.ttf'));
   });
   

2. Dynamic Size Calculation Create a helper to auto-scale QR codes based on content length:

   function dynamicQrSize($content) {
       return strlen($content) * 5 + 100; // Adjust multiplier as needed
   }
   

   Usage:

   $size = dynamicQrSize($user->profileUrl);
   Quar::size($size)->generate($user->profileUrl);
   

3. Event Listeners Trigger actions when QR codes are generated (e.g., log usage):

   // app/Listeners/LogQrGeneration.php
   public function handle($event) {
       Log::info("QR generated for URL: {$event->url}");
   }
   

   Register the listener in EventServiceProvider:

   protected $listen = [
       'tbQuar\Events\QrGenerated' => [
           'App\Listeners\LogQrGeneration',
       ],
   ];
   

Configuration Quirks

• Default Values: The package uses sensible defaults (e.g., square markers, bottom text position), but always verify critical settings like margin() for logos.
• PHP Version: Test on PHP 8.2+; some features (e.g., named arguments)