spatie/laravel-mobile-pass

Pass relevance is an Apple-exclusive feature that surfaces a pass on the lock screen at the optimal moment (e.g., a boarding pass before a flight or a loyalty card when entering a shop).

Relevance is driven by two primary factors:

1. Time: Using relevantDates to trigger the pass around a specific moment.
2. Location: Using GPS coordinates (addLocation) or iBeacons (addBeacon) to trigger the pass when a user is physically near a venue.

Best Practice: Combining both a date and a location provides the strongest relevance. For example, a concert ticket with both the showtime and the stadium coordinates will surface as the user travels to the venue and drop out once the event is over.

Google Wallet uses a two-part model: a Class and an Object.

• Class: A shared template representing the common data for a group of passes (e.g., a specific concert event, a loyalty program, or a flight). You declare this once.
• Object: An individual pass for a specific user that points to a Class.

Unlike Apple Wallet, where every pass is self-contained, Google Wallet requires you to define the Class first. The package handles the full Class ID by prefixing your provided suffix with your {issuer-id} (e.g., {issuer-id}.beatles-shea-1965).

Deciding whether to override an action or listen to an event depends on your goal:

Use Events (MobilePassAdded, MobilePassRemoved, PassPersonalized) when:

• You want to perform side effects like logging, analytics, or sending notifications.
• You want a lightweight implementation that won't break if the package's internal action logic changes.

Override Actions when:

• The event hook is insufficient.
• You need to change the persistence shape (e.g., using different columns or models).
• You need to swap a transport layer (e.g., using a custom APNs client).
• You need to reject an operation outright (e.g., anti-abuse checks during registration).

To use NFC functionality in Apple Wallet passes, you must obtain the PassKit NFC Credentials Entitlement from Apple. Apple restricts NFC access to specific use cases like loyalty, transit, and access control.

Important Notes:

• NFC is Apple-only: Google Wallet manages its own NFC flow and does not expose equivalent configuration fields.
• Development behavior: You can still set an NFC payload and generate valid pass bundles without the entitlement. However, an iPhone without the entitlement will simply not transmit any data when the pass is tapped against a reader.

When adding Wi-Fi credentials to a pass, keep the following security implications in mind:

1. Plain Text Storage: Passwords are stored in plain text within the pass. Any method of exporting the pass (email attachments, screenshots, iCloud backups) will expose the credentials.
2. Use Case: Only use this feature for networks where sharing the password is intended. Avoid using it for corporate or high-security networks.
3. Updating Credentials: If a network password changes, you must update the pass to push the new credentials to the user's device. Devices that have already joined will retain the old password in their cache until the network is manually forgotten.

It is important to note that neither Apple nor Google allows for the remote deletion of a pass from a user's device.

When you call expire(), you are not deleting the pass, but rather transitioning it to an expired state. This results in the following platform behaviors:

• The pass is greyed out in the wallet app.
• The pass is demoted from the lock screen.
• The pass stops being surfaced in relevant moments (like location-based notifications).

The user retains control over whether they actually delete the pass from their device.

To create a shared template, use the make() method on a specific Class builder with a unique suffix, configure the template fields, and call save(). Google stores these Classes on its own servers, not in your local database.

Example using EventTicketPassClass:

use Spatie\
LaravelMobilePass\\Builders\\Google\\EventTicketPassClass;

EventTicketPassClass::make('beatles-shea-1965')
    ->setIssuerName('Fab Four Promotions')
    ->setEventName('The Beatles | Live at Shea')
    ->setVenueName('Shea Stadium')
    ->setVenueAddress('126th Street & Roosevelt Avenue, Flushing, NY')
    ->setStartDate(Carbon::parse('1965-08-15 20:00'))
    ->setLogoUrl('https://example.com/beatles-logo.png')
    ->setHeroImageUrl('https://example.com/beatles-hero.png')
    ->setBackgroundColor('#1a1a1a')
    ->save();

The package requires several tables to track generated passes, Apple device registrations, and Google events. To set these up, publish the migrations and run them:

```bash
php artisan vendor:publish --tag="mobile-pass-migrations"
php artisan migrate

This creates the following tables:

• mobile_passes
• apple_mobile_pass_devices
• apple_mobile_pass_registrations
• mobile_pass_google_events

By default, pass updates are pushed to Apple (via APNs) or Google (via REST API) synchronously. For high-traffic applications or bulk updates, you should move these operations to a background queue to prevent HTTP latency from affecting your web requests.

To enable queuing, set the MOBILE_PASS_QUEUE_CONNECTION and MOBILE_PASS_QUEUE_NAME environment variables. The package uses a standard Laravel ShouldQueue job called PushPassUpdateJob.

# Example configuration for Redis
MOBILE_PASS_QUEUE_CONNECTION=redis
MOBILE_PASS_QUEUE_NAME=wallet