Laravel Mobile Pass Laravel Package

Technical Evaluation

Architecture Fit

• Enhanced Apple Wallet Features: The addition of iBeacon relevance support (PR #52) extends the package’s utility for location-aware passes (e.g., retail beacons, event check-ins). This aligns with Apple’s PassKit iBeacon capabilities, enabling dynamic pass updates based on proximity. The modular design ensures this feature is opt-in and doesn’t disrupt existing implementations.
• Modularity Preserved: The core architecture remains unchanged, with iBeacon support added as an optional configuration for Apple passes. This maintains backward compatibility and selective adoption.
• Event-Driven Extensibility: The package’s event system (GoogleMobilePassSaved, ApplePassGenerated) can now trigger actions tied to iBeacon updates (e.g., logging beacon-triggered pass activations).
• Laravel Synergy: iBeacon data can be stored as JSON in the mobile_passes table (or custom tables) and queried via Eloquent, leveraging Laravel’s JSON column support and query scopes.

Integration Feasibility

• iBeacon Configuration:
  • Requires adding ibeacon configuration to Apple pass definitions (e.g., major, minor, proximityUUID in the pass builder).
  • Example:

    $pass->ibeacon([
        'proximityUUID' => 'E2C56DB5-DFFB-48D2-B060-D0F5A71096E0',
        'major' => 1,
        'minor' => 1,
    ]);
    

  • No Breaking Changes: Existing passes continue to work; iBeacon is optional.
• Dependency Updates:
  • actions/checkout bump (v4 → v7) is a CI/CD change with no runtime impact.
  • No PHP/Laravel version requirements altered.
• HTTPS/SSL: iBeacon updates still require HTTPS for Apple’s web service callbacks, but the underlying infrastructure remains unchanged.
• Database Schema: No migrations required; iBeacon data is stored as JSON in the existing mobile_passes table or custom fields.

Technical Risk

• iBeacon Complexity:
  • UUID/Proximity Requirements: Incorrect proximityUUID, major, or minor values can cause pass validation failures on Apple devices. Test with Apple’s PassKit Validator.
  • Beacon Hardware: Physical beacons must be configured separately (e.g., via Estimote or Kontakt). The package only handles pass-side logic.
  • Battery/Range: iBeacon passes are sensitive to device battery and beacon range; user testing is critical.
• Performance:
  • iBeacon data adds ~50–100 bytes to pass payloads, negligible for most use cases but worth monitoring in high-volume scenarios.
  • No impact on Google Wallet; iBeacon is Apple-specific.
• Deprecation Risk:
  • iBeacon support is new but follows Apple’s official documentation, reducing risk of future incompatibility.
  • Google Wallet remains unaffected.

Key Questions for TPM

1. iBeacon Use Case:
   • Are passes intended for proximity-based triggers (e.g., retail, events, access control)? If so, iBeacon is a game-changer; if not, this feature may be superfluous.
   • What beacon hardware will be used? The package doesn’t manage beacons but requires their UUIDs/credentials.
2. Pass Type Prioritization:
   • Which pass types (e.g., BoardingPass, Coupon) will use iBeacon? Custom builders may need adjustments to support beacon data.
3. Fallback Strategy:
   • How will non-iBeacon-compatible devices handle passes? Apple’s PassKit supports graceful degradation.
4. Testing Scope:
   • Will iBeacon passes be tested with real hardware (e.g., Estimote beacons) or simulators (e.g., Apple’s PassKit simulator)?
5. Analytics:
   • How will beacon-triggered pass activations be tracked? The package emits events (ApplePassGenerated), but custom logging (e.g., via Laravel’s Log::channel) may be needed.
6. Scalability:
   • With iBeacon, will pass updates become more frequent (e.g., real-time beacon changes)? The existing queue system (PushPassUpdateJob) should handle this, but load testing is recommended.
7. Customization:
   • Are custom pass models needed to store iBeacon metadata? The package supports this but may require additional validation.
8. Monitoring:
   • How will iBeacon-related failures (e.g., invalid UUIDs, beacon unreachable) be monitored? Apple’s validation errors can be logged via the ApplePassValidationFailed event.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Eloquent JSON Fields: iBeacon data can be stored as JSON in the mobile_passes table, enabling queries like:

    $passes = MobilePass::whereJsonContains('ibeacon->proximityUUID', 'E2C56DB5-DFFB-48D2-B060-D0F5A71096E0')->get();
    

  • Queue System: iBeacon-triggered pass updates can use PushPassUpdateJob for async processing.
  • Middleware: Add iBeacon-specific validation middleware (e.g., check beacon credentials before pass generation).
• PHP Extensions:
  • No new extensions required. iBeacon logic is handled by the package’s XML/JSON generation.
• Dependencies:
  • actions/checkout: CI-only; no runtime impact.
  • Core: No changes to spatie/array-to-xml or firebase/php-jwt.

Migration Path

1. Phase 1: Core Setup (Unchanged)
   • Install package (v1.5.0), publish config, run migrations (no schema changes).
   • Configure Apple/Google credentials as before.
2. Phase 2: iBeacon Configuration (Optional)
   • Update pass builders to include iBeacon data:

     $pass = (new BoardingPass)
         ->ibeacon([
             'proximityUUID' => env('BEACON_UUID'),
             'major' => 1,
             'minor' => 1,
         ]);
     

   • Store beacon credentials in .env (e.g., BEACON_UUID, BEACON_MAJOR_MINOR).
3. Phase 3: Testing
   • Apple: Use PassKit Validator to test iBeacon passes.
   • Google: Unaffected; test existing Google Wallet passes.
   • Hardware: Test with real beacons or simulators (e.g., Apple’s PassKit simulator).
4. Phase 4: Analytics/Monitoring
   • Extend event listeners to log iBeacon-related actions:

     MobilePass::created(function ($pass) {
         if ($pass->ibeacon_data) {
             Log::info('iBeacon pass generated', $pass->ibeacon_data);
         }
     });
     

Compatibility

• Laravel Versions: No changes; still supports Laravel 8+.
• PHP Versions: PHP 8.0+ (unchanged).
• Database: iBeacon data is stored as JSON; compatible with MySQL 5.7+, PostgreSQL 12+, SQLite 3.35+.
• Apple/Google APIs:
  • Apple: iBeacon support adheres to PassKit specs.
  • Google: Unchanged; no iBeacon support in Google Wallet.
• Custom Models: Extend MobilePass to add iBeacon-specific fields if needed.

Sequencing

1. Step 1: Install v1.5.0

   composer require spatie/laravel-mobile-pass:^1.5.0
   

2. Step 2: Configure iBeacon (Optional)
   • Add beacon credentials to .env:

     BEACON_UUID=E2C56DB5-DFFB-48D2-B060-D0F5A71096E0
     BEACON_MAJOR=1
     BEACON_MINOR=1
     

   • Update pass builders to include iBeacon:

     $pass->ibeacon([
         'proximityUUID' => env('BEACON_UUID'),