Laravel Mobile Pass Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-mobile-pass
   php artisan vendor:publish --provider="Spatie\MobilePass\MobilePassServiceProvider"
   php artisan migrate
   

   • Publishes config (config/mobile-pass.php) and creates a passes table.

2. First Use Case: Generate a simple boarding pass:

   use Spatie\MobilePass\Pass;
   use Spatie\MobilePass\PassType;
   
   $pass = Pass::create([
       'passType' => PassType::boardingPass(),
       'serialNumber' => 'ABC123',
       'teamIdentifier' => 'com.yourcompany.app',
       'organizationName' => 'Your Company',
       'description' => 'Boarding Pass',
       'relevantDate' => now()->addDay(),
       'foregroundColor' => '#000000',
       'backgroundColor' => '#FFFFFF',
       'logoText' => 'Your Company',
       'storeCard' => false,
       'webServiceURL' => 'https://your-app.com/pass/verify',
       'authenticationToken' => 'your-secret-token',
       'headerFields' => [
           ['key' => 'name', 'label' => 'Name', 'value' => 'John Doe'],
       ],
       'barcode' => [
           'message' => 'ABC123',
           'format' => 'PKBarcodeFormatQR',
           'messageEncoding' => 'iso-8859-1',
       ],
   ]);
   
   return $pass->toWebPass();
   

   • Visit /passes/{id}/webpass in a browser to download the .pkpass file.

Key Files to Review

• Config: config/mobile-pass.php (adjust team_identifier, certificate_path, etc.).
• Migrations: database/migrations/xxxx_create_passes_table.php (customize fields as needed).
• Service Provider: app/Providers/MobilePassServiceProvider.php (extend if needed).

Implementation Patterns

Core Workflows

1. Pass Generation:

   • Use Pass::create() with a PassType (e.g., PassType::boardingPass(), PassType::eventTicket()).
   • Define required fields like serialNumber, webServiceURL, and authenticationToken.
   • Customize appearance with foregroundColor, backgroundColor, logoText, etc.
   • Add dynamic fields via headerFields, primaryFields, or secondaryFields.

2. Barcode Integration:

   $pass->barcode([
       'message' => 'UNIQUE_ID_123',
       'format' => 'PKBarcodeFormatPDF417', // or QR, AZTEC, etc.
       'messageEncoding' => 'iso-8859-1',
   ]);
   

   • Use PDF417 for high-density data (e.g., boarding passes) or QR for simplicity.

3. Pass Updates:

   • Fetch a pass by ID: $pass = Pass::find($id).
   • Update fields (e.g., relevantDate, headerFields) and save:

     $pass->update(['relevantDate' => now()->addHour()]);
     $pass->updateBarcode(['message' => 'NEW_UNIQUE_ID']);
     

   • Users’ devices auto-update if the webServiceURL is reachable.

4. Web Pass Delivery:

   • Serve the .pkpass file via:

     route('passes.webpass', function (Pass $pass) {
         return $pass->toWebPass();
     });
     

   • Or manually:

     $pass->toWebPass()->saveTo($path);
     

5. Validation:

   • Use Pass::validate() to check if a pass is valid (e.g., for redemption):

     if (Pass::validate($serialNumber, $authToken)) {
         // Pass is valid
     }
     

Integration Tips

• Authentication: Secure webServiceURL with API tokens or signed requests.
• Dynamic Data: Fetch user-specific data (e.g., event details) when generating passes.
• Testing: Use Pass::fake() in tests to mock pass generation:

  Pass::fake([
      PassType::boardingPass()->withSerialNumber('TEST123'),
  ]);
  

• Frontend: Use the Apple Wallet documentation to guide users on adding passes to their devices.

Gotchas and Tips

Pitfalls

1. Certificate Requirements:

   • Issue: Apple requires a .p12 certificate for signing .pkpass files. Without it, passes won’t install.
   • Fix: Generate a certificate via Apple Developer Account and configure certificate_path in config/mobile-pass.php:

     'certificate_path' => storage_path('app/certificates/wallet_cert.p12'),
     'certificate_password' => env('WALLET_CERT_PASSWORD'),
     

   • Debug: If passes fail to install, check the console for signing errors.

2. Team Identifier:

   • Issue: The teamIdentifier (e.g., com.yourcompany.app) must match your Apple Developer account’s bundle ID.
   • Fix: Verify in config/mobile-pass.php and regenerate certificates if mismatched.

3. Barcode Validation:

   • Issue: Invalid barcode formats (e.g., unsupported PKBarcodeFormat) may cause pass generation to fail silently.
   • Fix: Use supported formats: PKBarcodeFormatPDF417, PKBarcodeFormatQR, PKBarcodeFormatAztec, or PKBarcodeFormatCode128.

4. Web Service URL:

   • Issue: If webServiceURL is unreachable, users won’t receive updates.
   • Fix: Use a reliable endpoint (e.g., /api/passes/validate/{serialNumber}) and test with:

     curl -X GET "https://your-app.com/pass/verify?serialNumber=ABC123&authToken=your-token"
     

     Return a 200 status for valid passes.

5. Pass Expiration:

   • Issue: Passes expire if relevantDate is in the past or expirationDate is set.
   • Fix: Always set future dates and handle updates proactively.

Debugging Tips

• Logs: Enable debug mode in config/mobile-pass.php:

  'debug' => env('APP_DEBUG', false),
  

• Pass Inspection: Open .pkpass files with Pass Inspector (macOS) to validate structure.
• Common Errors:
  • Invalid signature: Certificate or password issue.
  • Pass not found: webServiceURL misconfiguration.
  • Barcode error: Invalid message or format.

Extension Points

1. Custom Pass Types: Extend Spatie\MobilePass\PassType to create reusable pass templates:

   namespace App\PassTypes;
   
   use Spatie\MobilePass\PassType;
   
   class LoyaltyCard extends PassType
   {
       public static function create(): PassType
       {
           return (new static())
               ->withPassTypeIdentifier('pass.com.yourcompany.loyalty')
               ->withOrganizationName('Your Company')
               ->withLogoText('LOYALTY')
               ->withForegroundColor('#000000')
               ->withBackgroundColor('#FFFFFF');
       }
   }
   

2. Dynamic Field Generation: Use closures to generate fields dynamically:

   $pass->headerFields([
       ['key' => 'event', 'label' => 'Event', 'value' => fn () => 'Conference 2025'],
   ]);
   

3. Event Listeners: Listen for pass events (e.g., creation/updates) to trigger notifications:

   Pass::created(function (Pass $pass) {
       // Send email/SMS to user
   });
   

4. Batch Processing: Generate passes in bulk for events or promotions:

   $users = User::where('attending_event', true)->get();
   foreach ($users as $user) {
       Pass::create([
           'serialNumber' => 'EVENT_' . $user->id,
           // ... other fields
       ]);
   }
   

5. Localization: Support multiple languages by localizing label and value fields:

   $pass->headerFields([
       ['key' => 'name', 'label' => __('Name'), 'value' => $user->name],
   ]);