Filament Qrcode Field Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require jeffersongoncalves/filament-qrcode-field
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="JeffersonGoncalves\FilamentQrCodeField\FilamentQrCodeFieldServiceProvider" --tag="config"
   

2. First Use Case Add the QR Code field to a Filament form/resource:

   use JeffersonGoncalves\FilamentQrCodeField\Fields\QrCode;
   
   QrCode::make('qr_content')
       ->label('QR Code Content')
       ->required()
       ->default('https://example.com'),
   

3. Where to Look First

   • Documentation: Check the GitHub README for version-specific examples.
   • Config: Review config/filament-qrcode-field.php for customization options (e.g., QR size, error correction level).
   • Field Methods: Explore the QrCode field class in the source code for available methods.

Implementation Patterns

Common Workflows

1. Basic Form Integration Use the field in a Filament form to generate/scan QR codes for dynamic content (e.g., user profiles, inventory items):

   public static function form(Form $form): Form
   {
       return $form
           ->schema([
               TextInput::make('name')->required(),
               QrCode::make('qr_data')
                   ->label('QR Payload')
                   ->helperText('Scan this to access the resource.'),
           ]);
   }
   

2. Resource-Specific Usage Attach to a model’s getTableRecords() or getFormSchema() for CRUD operations:

   public static function table(Table $table): Table
   {
       return $table
           ->columns([
               // ...
               Columns\QrCodeColumn::make('qr_data')
                   ->label('QR Code')
                   ->size(100), // Adjust size in pixels
           ]);
   }
   

3. Dynamic Payloads Generate QR codes from computed data (e.g., encrypted tokens, API endpoints):

   QrCode::make('auth_token')
       ->getStateUsing(function ($record) {
           return encrypt($record->token);
       })
       ->columnSpanFull(),
   

4. Validation & Sanitization Combine with Filament’s validation rules:

   QrCode::make('url')
       ->rules(['url', 'max:2048'])
       ->dehydrateStateUsing(fn ($state) => str($state)->trim()),
   

Integration Tips

• Custom Styling: Override the QR renderer via the renderUsing method:

  QrCode::make('custom_qr')
      ->renderUsing(function ($state, $record) {
          return view('custom.qr-renderer', ['content' => $state]);
      });
  

• Localization: Use Filament’s translation system for labels/helpers:

  QrCode::make('qr_code')
      ->label(__('filament-qrcode::fields.qr_code.label'))
      ->helperText(__('filament-qrcode::fields.qr_code.helper')),
  

• Asset Optimization: Cache generated QR codes in storage:

  QrCode::make('cached_qr')
      ->disk('public')
      ->path('qr-codes/{record_id}.png'),
  

Gotchas and Tips

Pitfalls

1. Payload Length Limits

   • QR codes have a max capacity of ~2,953 bytes (numeric mode). Long URLs or JSON may fail silently.
   • Fix: Use URL shorteners or compress payloads (e.g., base64_encode(json_encode($data))).

2. Filament Version Mismatch

   • The package targets Filament v4. Using with v3 may break due to API changes.
   • Fix: Check the compatibility table and pin versions in composer.json.

3. State Hydration Issues

   • If getStateUsing returns null, the field may render blank.
   • Fix: Provide a default or ensure the model’s attribute exists:

     QrCode::make('qr_data')->default('fallback_url'),
     

4. CORS for Scanning

   • Mobile scanners may block cross-origin QR generation.
   • Fix: Serve QR images with Access-Control-Allow-Origin headers or use a proxy.

Debugging

• Log Payloads: Add debug output to verify encoded/decoded data:

  QrCode::make('debug_qr')
      ->dehydrateStateUsing(fn ($state) => logger()->debug('QR Payload:', ['data' => $state]) ?: $state),
  

• Check Console Errors: Inspect browser dev tools for failed QR renders (e.g., invalid SVG output).

Extension Points

1. Custom QR Libraries Replace the default endroid/qr-code with another library (e.g., bacon/bacon-qr-code) by binding a service:

   $this->app->bind(\JeffersonGoncalves\FilamentQrCodeField\Contracts\QrCodeGenerator::class, function () {
       return new CustomQrGenerator();
   });
   

2. Event Hooks Extend the field lifecycle via Filament’s events:

   FilamentQrCodeField::registerCallback(
       QrCode::class,
       'beforeGenerate',
       fn ($state, $record) => str($state)->replace('old', 'new')
   );
   

3. Testing Mock the QR generator in PHPUnit:

   $this->mock(\JeffersonGoncalves\FilamentQrCodeField\Contracts\QrCodeGenerator::class, function ($mock) {
       $mock->shouldReceive('generate')->andReturn('<svg>mock-qr</svg>');
   });
   

Config Quirks

• Default Size: The field uses 200px by default. Adjust via config:

  'default_size' => 300, // in config/filament-qrcode-field.php
  

• Error Correction: Modify the QR’s error tolerance (L/M/Q/H) in the config:

  'error_correction' => 'H', // High error correction