Laravel Mobile Pass Laravel Package

Technical Evaluation

Architecture Fit

• Modular & Extensible: The package follows Laravel’s conventions (e.g., service providers, model events, queue jobs) and integrates seamlessly with Eloquent models. It supports Apple Wallet (PKPass) and Google Wallet with platform-specific builders, making it ideal for apps requiring cross-platform mobile pass functionality.
• Domain-Driven Design (DDD) Alignment: The MobilePass model and associated builders (BoardingPass, EventTicket, Loyalty, etc.) align well with DDD principles, allowing for clear separation of concerns between pass types and business logic.
• Event-Driven Updates: Leverages Laravel events (GoogleMobilePassSaved, GoogleMobilePassRemoved) and queue jobs (PushPassUpdateJob) for asynchronous pass updates, reducing latency and improving scalability.

Integration Feasibility

• Laravel-Centric: Designed for Laravel (v8+), with minimal external dependencies (e.g., spatie/array-to-xml, spatie/google-wallet). Integration requires:
  • HTTPS for Apple Wallet web service URLs (enforced by the package).
  • Google Wallet API credentials (service account JSON key) for callback verification.
  • Database migrations for the mobile_passes table (or custom table via config).
• Customization Points:
  • Override the default MobilePass model via mobile-pass.models.mobile_pass config.
  • Extend builders (e.g., EventTicketPassBuilder) for custom fields or logic.
  • Hook into events (e.g., CreatingMobilePass, UpdatingMobilePass) for pre/post-processing.

Technical Risk

• Apple Wallet Requirements:
  • Certificate Management: Requires a PKCS12 certificate (.p12) for signing .pkpass files. Misconfiguration (e.g., expired certs) can break pass generation.
  • HTTPS Enforcement: Non-HTTPS web service URLs are rejected by Apple Wallet (package throws InvalidConfig::webserviceHostMustBeHttps).
  • Pass Serial Uniqueness: Apple routes updates via pass_serial (added in v1.0.5), requiring careful handling of duplicate/conflicting serials.
• Google Wallet Risks:
  • Callback Verification: Relies on Google’s ECv2SigningOnly verification (updated in v1.2.0). Incorrect JWKS configuration can fail pass updates.
  • Rate Limits: Google Wallet APIs may throttle frequent updates; queue jobs (MOBILE_PASS_QUEUE_CONNECTION) help mitigate this.
• Data Migration:
  • v1.0.5 introduces a required migration for pass_serial (see UPGRADING.md). Existing deployments must backfill this field.
  • Remote images (v1.1.0+) require CDN/HTTPS support; local paths are not supported for Google Wallet objects.

Key Questions

1. Platform Prioritization:
   • Is Apple Wallet or Google Wallet the primary target? This influences certificate management, web service routing, and pass type selection.
2. Update Frequency:
   • How often will passes be updated? High-frequency updates may require queue optimization (e.g., batching jobs) or Google API quota planning.
3. Customization Needs:
   • Are there non-standard pass types (e.g., NFC-enabled passes)? The package lacks Smart Tap NFC support (deferred to v1.1+).
4. Compliance:
   • Does the use case require GDPR/CCPA compliance for pass data? The package stores pass metadata in the database; ensure alignment with data retention policies.
5. Monitoring:
   • How will pass delivery success/failure be tracked? The package lacks built-in analytics; integration with Laravel Horizon or third-party tools (e.g., Sentry) may be needed.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Models: Extend MobilePass or use the default model for pass metadata (e.g., user_id, pass_type, serial).
  • Queues: Leverage PushPassUpdateJob for async updates (requires MOBILE_PASS_QUEUE_CONNECTION config).
  • Events: Subscribe to GoogleMobilePassSaved/GoogleMobilePassRemoved for custom logic (e.g., notifications).
  • APIs: Use addToWalletUrl() to generate platform-specific download links (e.g., /mobile-pass/{pass}/download for Apple, deep links for Google).
• External Dependencies:
  • Apple: Requires a PKCS12 certificate (.p12) and pass type IDs (e.g., com.example.boardingpass) from Apple Developer Portal.
  • Google: Requires a Google Wallet API service account and JWKS public key for callback verification.
• Frontend:
  • Apple: Use Safari’s addToWallet() WebKit API or a download link.
  • Google: Use the Google Wallet Android SDK or deep links.

Migration Path

1. Prerequisites:
   • Laravel 8+ with PHP 8.0+.
   • HTTPS-enabled domain (Apple requirement).
   • Apple Developer account (for PKCS12 cert and pass type IDs).
   • Google Wallet API credentials (for callback verification).
2. Installation:

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

3. Configuration:
   • Publish config (config/mobile-pass.php) and update:
     • apple.certificate_path (path to .p12 file).
     • apple.pass_type_identifiers (e.g., ['boardingpass' => 'com.example.boardingpass']).
     • google.service_account_key_path (path to Google service account JSON).
     • mobile_pass model (if customizing).
4. Database Migration:
   • Run php artisan migrate to create the mobile_passes table.
   • For v1.0.5+, add pass_serial to existing records (see UPGRADING.md).
5. Testing:
   • Use the demo app to validate pass generation and updates.
   • Test on real devices (Apple Wallet requires iOS 6.0+; Google Wallet requires Android 5.0+).

Compatibility

• Laravel Versions: Officially supports v8+; may work with v7.x with minor adjustments.
• PHP Versions: Requires PHP 8.0+ (due to named arguments and other features).
• Pass Types:
  • Apple: BoardingPass, EventTicket, StoreCard, Coupon, Generic.
  • Google: BoardingPass, EventTicket, Loyalty, Offer, Generic.
• Image Support:
  • Apple: Local or remote (HTTPS) images.
  • Google: Remote images only (v1.1.0+).

Sequencing

1. Phase 1: Core Integration
   • Implement MobilePass model and basic pass generation (e.g., BoardingPass).
   • Set up Apple/Google credentials and config.
   • Test pass generation and installation on devices.
2. Phase 2: Update Workflow
   • Configure queue jobs (PushPassUpdateJob) for async updates.
   • Implement webhook handlers for Apple/Google callbacks.
   • Test update scenarios (e.g., expiry, field changes).
3. Phase 3: Customization
   • Extend builders for custom pass types/fields.
   • Add analytics or monitoring for pass delivery.
   • Optimize queue performance for high-volume updates.
4. Phase 4: Rollout
   • Gradual rollout to users with A/B testing for pass adoption.
   • Monitor failure rates (e.g., Apple/Google API rejections).

Operational Impact

Maintenance

• Certificate Renewal:
  • Apple PKCS12 certificates expire annually. Automate renewal alerts and update config/mobile-pass.php accordingly.
  • Monitor certificate validity via openssl pkcs12 -info -in path/to/cert.p12.
• Google API Keys:
  • Rotate service account keys periodically and update google.service_account_key_path.
  • Verify JWKS public keys are up-to-date for callback verification.
• Database:
  • Regularly back up the mobile_passes table (contains user-sensitive data like pass serials).
  • Archive expired passes to comply with data retention policies.
• Logs:
  • Monitor spatie/mobile-pass logs for:
    • Failed pass generation (e.g., invalid certs).
    • Update job failures (e.g., Google API rate limits).
    • Callback verification errors.

Support

• Common Issues:
  • Apple: Passes not updating? Verify webServiceURL is HTTPS and pass_serial is unique.
  • Google: Callback failures? Check JWKS key alignment and ECv2SigningOnly config.
  • Images: Remote images must be HTTPS; Apple may reject non-HTTPS sources.
• Debugging Tools:
  • Use `artisan mobile