Laravel Mobile Pass

https://spatie.be/docs/laravel-mobile-pass/v1/
Admin
Laravel Mobile Pass is a package for generating and managing mobile passes for Apple Wallet and...
Tokens:20,699
Snippets:279
Trust Score:9.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Laravel Mobile Pass via Composer

Source: https://spatie.be/docs/laravel-mobile-pass/v1/installation-setup

Use this command to pull the package into your Laravel project.

```bash
composer require spatie/laravel-mobile-pass
```

--------------------------------

### Check if pass is in wallet

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/events

Use the unified helper to check if a pass is currently installed on any device.

```php
if ($mobilePass->isCurrentlyInWallet()) {
    // Apple: at least one device has it registered
    // Google: latest save/remove callback was a save
}
```

--------------------------------

### Publish and run database migrations

Source: https://spatie.be/docs/laravel-mobile-pass/v1/installation-setup

Commands to publish the package's migration files and execute them to create the necessary database tables.

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

--------------------------------

### Publish the configuration file

Source: https://spatie.be/docs/laravel-mobile-pass/v1/installation-setup

Use this command to copy the package configuration file to your application's config directory for customization.

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

--------------------------------

### Configure Google Wallet environment variables

Source: https://spatie.be/docs/laravel-mobile-pass/v1/getting-credentials-from-google

Set the issuer ID and the path to the service account JSON file in your .env file.

```text
MOBILE_PASS_GOOGLE_ISSUER_ID=3388000000022000000
MOBILE_PASS_GOOGLE_KEY_PATH=/absolute/path/to/service-account.json
```

--------------------------------

### Create a Google Loyalty Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/loyalty

Define the program class once, then create individual member objects using LoyaltyPassBuilder.

```php
use Spatie\LaravelMobilePass\Builders\Google\LoyaltyPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\LoyaltyPassClass;

// Once, per program
LoyaltyPassClass::make('spatie-rewards')
    ->setIssuerName('Spatie')
    ->setProgramName('Spatie Rewards')
    ->setProgramLogoUrl('https://cdn.example.com/spatie-logo.png')
    ->setAccountNameLabel('Member')
    ->setAccountIdLabel('Member ID')
    ->setBackgroundColor('#1d72b8')
    ->save();

// Per member
LoyaltyPassBuilder::make()
    ->setClass('spatie-rewards')
    ->setAccountId('USER-7842')
    ->setAccountName('Ringo Starr')
    ->setBalanceString('1,250 points')
    ->save();
```

--------------------------------

### Instantiating PkPassReader

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/reading-stored-passes

Use the PkPassReader class to load pass data from a file path or a string variable.

```php
use Spatie\LaravelMobilePass\Support\Apple\PkPassReader;

// from file
$reader = PkPassReader::fromFile('path/to/pass.pkpass');

// from string
$reader = PkPassReader::fromString($passData);
```

--------------------------------

### Reference a local image file

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/hosting-images

Use Image::fromLocalPath to point to a file on your server, noting that this is currently limited to object-level builders.

```php
use Spatie\LaravelMobilePass\Builders\Google\Entities\Image;

$image = Image::fromLocalPath(public_path('images/ticket-hero.png'));
```

--------------------------------

### Create a Google Offer Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/coupon

Define the offer class once, then create individual objects for each redeemer using OfferPassBuilder.

```php
use Spatie\LaravelMobilePass\Builders\Google\OfferPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\OfferPassClass;

// Once, per offer
OfferPassClass::make('summer-2026-20off')
    ->setIssuerName('Spatie Store')
    ->setTitle('Save 20% this summer')
    ->setProvider('Spatie')
    ->setRedemptionChannel('ONLINE')
    ->setFinePrint('One use per customer. Expires 2026-08-31.')
    ->setLogoUrl('https://cdn.example.com/spatie-logo.png')
    ->save();

// Per redeemer
OfferPassBuilder::make()
    ->setClass('summer-2026-20off')
    ->setTitle('20% off for Dan')
    ->setRedemptionCode('DAN20SUMMER')
    ->save();
```

--------------------------------

### Configure base64 encoded key

Source: https://spatie.be/docs/laravel-mobile-pass/v1/getting-credentials-from-google

Set the base64 encoded string as the value for the service account key.

```text
MOBILE_PASS_GOOGLE_KEY=ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCi...
```

--------------------------------

### Create an Apple Store Card

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/loyalty

Use StoreCardPassBuilder to define loyalty card details for Apple Wallet.

```php
use Spatie\LaravelMobilePass\Builders\Apple\StoreCardPassBuilder;

StoreCardPassBuilder::make()
    ->setOrganizationName('Spatie Rewards')
    ->setSerialNumber('CARD-USER-7842')
    ->setDescription('Spatie Rewards member card')
    ->addField('balance', '1,250', label: 'Points')
    ->addSecondaryField('member', 'Ringo Starr')
    ->addSecondaryField('tier', 'Gold')
    ->save();
```

--------------------------------

### Base64 encode service account key

Source: https://spatie.be/docs/laravel-mobile-pass/v1/getting-credentials-from-google

Use this command to encode the service account JSON file for use in the environment variable.

```bash
base64 -i path/to/service-account.json | pbcopy
```

--------------------------------

### Create a Google Event Ticket

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/event-ticket

Define the event class once, then create individual ticket objects for Google Wallet.

```php
use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassClass;
use Spatie\LaravelMobilePass\Enums\BarcodeType;

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

// Per ticket
EventTicketPassBuilder::make()
    ->setClass('beatles-shea-1965')
    ->setAttendeeName('John Lennon')
    ->setSection('B12')
    ->setRow('8')
    ->setSeat('22')
    ->setBarcode(BarcodeType::Qr, 'BTL-SHEA-0042')
    ->save();
```

--------------------------------

### Create a Google Boarding Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/boarding-pass

Define a flight class once, then generate individual boarding passes for each passenger.

```php
use Spatie\LaravelMobilePass\Builders\Google\BoardingPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\BoardingPassClass;

// Once, per flight
BoardingPassClass::make('lh123-2026-04-20')
    ->setIssuerName('Lufthansa')
    ->setAirlineCode('LH')
    ->setFlightNumber('LH123')
    ->setOriginAirportCode('FRA')
    ->setDestinationAirportCode('JFK')
    ->setLocalScheduledDepartureDateTime(Carbon::parse('2026-04-20 14:30'))
    ->setLogoUrl('https://cdn.example.com/lh-logo.png')
    ->save();

// Per passenger
BoardingPassBuilder::make()
    ->setClass('lh123-2026-04-20')
    ->setPassengerName('Paul McCartney')
    ->setSeatNumber('12A')
    ->setConfirmationCode('ABC123')
    ->save();
```

--------------------------------

### Base64 encode certificate for environment variables

Source: https://spatie.be/docs/laravel-mobile-pass/v1/getting-credentials-from-apple

Use this command to convert a .p12 certificate file into a base64 string for use in environments where file storage is restricted.

```bash
base64 -i path/to/certificate.p12 | pbcopy
```

--------------------------------

### Create a Google Generic Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/generic

Define a pass class once for the brand and visuals, then create individual objects for each attendee.

```php
use Spatie\LaravelMobilePass\Builders\Google\GenericPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\GenericPassClass;

// Once, per use case
GenericPassClass::make('spatie-conference-badge')
    ->setIssuerName('Spatie Conference')
    ->setCardTitle('Spatie Conference 2026')
    ->setSubheader('Attendee badge')
    ->setLogoUrl('https://cdn.example.com/conf-logo.png')
    ->save();

// Per attendee
GenericPassBuilder::make()
    ->setClass('spatie-conference-badge')
    ->setHeader('Ringo Starr')
    ->setCardTitle('All-access badge')
    ->setSubheader('Speaker')
    ->save();
```

--------------------------------

### Configure Pass Relevance for Wi-Fi Button

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/attaching-wifi-credentials

Combine Wi-Fi credentials with location and date relevance to ensure the Join Wi-Fi button appears at the appropriate time and place.

```php
use Illuminate\Support\Carbon;

$builder
    ->addLocation(
        latitude: 40.7559,
        longitude: -73.8456,
        relevantText: 'Welcome to Shea Stadium',
    )
    ->setRelevantDate(Carbon::parse('1965-08-15 19:00'))
    ->addWifiNetwork('SheaStadium-Guest', 'welcome1965');
```

--------------------------------

### Add Multiple Wi-Fi Networks

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/attaching-wifi-credentials

Chain multiple addWifiNetwork calls to attach more than one network to the pass.

```php
$builder
    ->addWifiNetwork('SheaStadium-Guest', 'welcome1965')
    ->addWifiNetwork('SheaStadium-VIP', 'backstage1965');
```

--------------------------------

### Logging the Add to Wallet URL

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/testing-your-passes

Log the pass URL to retrieve it for manual testing on a physical device.

```php
logger()->info($mobilePass->addToWalletUrl());
```

--------------------------------

### Handling Missing Image File Exceptions

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/handling-errors

Catch errors that occur immediately when an invalid image path is provided to a builder.

```php
use Spatie\LaravelMobilePass\Exceptions\ImageNotFound;

try {
    $builder->setLogoImage('/no/such/file.png');
} catch (ImageNotFound $exception) {
    // $exception->getMessage() includes the missing path
}
```

--------------------------------

### Add Wi-Fi Network to Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/attaching-wifi-credentials

Use the addWifiNetwork method on the pass builder to include network credentials.

```php
use Spatie\LaravelMobilePass\Builders\Apple\EventTicketPassBuilder;

EventTicketPassBuilder::make()
    ->setOrganizationName('Fab Four Promotions')
    ->setSerialNumber('BTL-SHEA-0042')
    ->setDescription('The Beatles at Shea Stadium')
    ->addWifiNetwork('SheaStadium-Guest', 'welcome1965')
    ->save();
```

--------------------------------

### Configure Wi-Fi Barcode on a Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/attaching-wifi-credentials

Use the setWifiBarcode method to encode network credentials into a QR code on the pass.

```php
use Spatie\LaravelMobilePass\Builders\Apple\GenericPassBuilder;

GenericPassBuilder::make()
    ->setOrganizationName('Spatie')
    ->setDescription('Guest Wi-Fi')
    ->addField('ssid', 'Spatie Guest', label: 'Network')
    ->addSecondaryField('password', 'welcome', label: 'Password')
    ->setWifiBarcode('Spatie Guest', 'welcome')
    ->save();
```

```php
$builder->setWifiBarcode('Spatie Guest');
```

```php
$builder->setWifiBarcode(
    ssid: 'Spatie Guest',
    password: 'welcome',
    hidden: true,
    altText: 'Scan to join',
);
```

--------------------------------

### Configure Asynchronous Updates

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/updating-a-pass

Set environment variables to offload pass update notifications to a queue worker.

```env
MOBILE_PASS_QUEUE_CONNECTION=redis
MOBILE_PASS_QUEUE_NAME=wallet
```

--------------------------------

### Create an Apple Coupon Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/coupon

Use CouponPassBuilder to define and save a coupon pass for Apple Wallet.

```php
use Spatie\LaravelMobilePass\Builders\Apple\CouponPassBuilder;

CouponPassBuilder::make()
    ->setOrganizationName('Spatie Store')
    ->setSerialNumber('COUPON-SUMMER25')
    ->setDescription('20% off everything this summer')
    ->addField('offer', '20%', label: 'Save')
    ->addSecondaryField('expires', '2026-08-31')
    ->save();
```

--------------------------------

### Declare a Google Wallet Pass Class

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Create a new pass class by calling make() with a unique suffix, configuring fields, and saving to Google's servers.

```php
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();
```

--------------------------------

### Add iBeacons for indoor precision

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/pass-relevance

Use iBeacons for indoor location tracking. You can specify a UUID and optional major/minor identifiers to target specific beacons.

```php
$builder->addBeacon(
    proximityUUID: 'f7826da6-4fa2-4e98-8024-bc5b71e0893e',
    relevantText: 'Show this pass at the counter',
);
```

```php
$builder->addBeacon(
    proximityUUID: 'f7826da6-4fa2-4e98-8024-bc5b71e0893e',
    major: 12, // e.g. a store
    minor: 3,  // e.g. a department
    relevantText: 'Welcome to the flagship store',
);
```

--------------------------------

### Set a relevant date for a pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/pass-relevance

Use a Carbon instance to define when a pass becomes relevant. Apple typically surfaces the pass four hours before the specified time.

```php
use Illuminate\Support\Carbon;

$builder->setRelevantDate(Carbon::parse('2026-08-15 20:00', 'America/New_York'));
```

--------------------------------

### Set foreground and label colors

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/apple-specific-methods

Customize the pass appearance by setting foreground and label colors using hex strings.

```php
$builder
    ->setForegroundColor('#ffffff')
    ->setLabelColor('#a7c7e7');
```

--------------------------------

### Set Apple Pass Images

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-images

Pass local file paths to the builder to set the logo and icon for an Apple pass.

```php
$builder
    ->setLogoImage(public_path('images/logo.png'))
    ->setIconImage(public_path('images/icon.png'));
```

--------------------------------

### Fetch Apple and Google passes by platform

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/retrieving-mobile-passes

Use dedicated helpers to retrieve passes specific to Apple or Google platforms.

```php
$user = User::first();

$user->applePasses;   // only Apple passes
$user->googlePasses;  // only Google passes

$user->firstApplePass();
$user->firstGooglePass();
```

--------------------------------

### Create an Apple Generic Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/generic

Use the GenericPassBuilder to define and save a generic pass for Apple Wallet.

```php
use Spatie\LaravelMobilePass\Builders\Apple\GenericPassBuilder;

GenericPassBuilder::make()
    ->setOrganizationName('Spatie Conference')
    ->setSerialNumber('BADGE-042')
    ->setDescription('Conference attendee badge')
    ->addField('name', 'Ringo Starr')
    ->addSecondaryField('track', 'All-access')
    ->save();
```

--------------------------------

### Add Metadata to Pass Classes

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Configure geographic locations, links, text modules, and image modules that appear on the back of the pass.

```php
EventTicketPassClass::make('beatles-shea-1965')
    ->setIssuerName('Fab Four Promotions')
    ->setEventName('The Beatles | Live at Shea')
    ->addLocation(40.7569, -73.8458)
    ->addLink('https://fabfour.example.com', 'Official site')
    ->addLink('tel:+15551234567')
    ->addTextModule('Doors', 'Doors open at 18:30')
    ->addImageModule('https://example.com/seating-chart.png', 'seating')
    ->save();
```

--------------------------------

### Registering Custom Actions in Configuration

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/customizing-actions

Update the mobile-pass configuration file to point the specific action key to your custom class implementation.

```php
// config/mobile-pass.php

return [
    // other keys

    'actions' => [
        // other actions

        'notify_apple_of_pass_update' => \App\Actions\CustomNotifyAppleOfPassUpdateAction::class,
    ],
];
```

--------------------------------

### Configure Google Loyalty Pass Labels

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/loyalty

Set secondary balance labels and values to display additional information on the card face.

```php
LoyaltyPassBuilder::make()
    ->setClass('spatie-rewards')
    ->setAccountId('USER-7842')
    ->setBalanceString('1,250')
    ->setBalanceLabel('Points')
    ->setSecondaryBalanceString('Gold')
    ->setSecondaryBalanceLabel('Tier')
    ->save();
```

--------------------------------

### Set pass images using public URLs

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/hosting-images

Use setLogoUrl and setHeroImageUrl on a Class builder to reference images hosted on a CDN or public server.

```php
use Spatie\LaravelMobilePass\Builders\Google\Entities\Image;
use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassClass;

EventTicketPassClass::make('beatles-shea-1965')
    ->setLogoUrl('https://cdn.example.com/beatles-logo.png')
    ->setHeroImageUrl('https://cdn.example.com/beatles-hero.png')
    ->save();
```

--------------------------------

### Catching all package exceptions

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/handling-errors

Use the MobilePassException interface to catch any exception thrown by the package.

```php
use Spatie\LaravelMobilePass\Exceptions\MobilePassException;

try {
    // something that touches the package
} catch (MobilePassException $exception) {
    report($exception);
}
```

--------------------------------

### Configuring the custom model

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/customizing-models

Update the mobile-pass configuration file to register your custom model class.

```php
// config/mobile-pass.php

return [
    'models' => [
        'mobile_pass' =>  App\Models\CustomMobilePass::class,
    ],
];
```

--------------------------------

### Extending an Action Class

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/customizing-actions

Create a custom class that extends the default action and override the execute method to inject custom logic before or after the parent execution.

```php
namespace App\Actions;

use Spatie\LaravelMobilePass\Actions\Apple\NotifyAppleOfPassUpdateAction;
use Spatie\LaravelMobilePass\Models\MobilePass;

class CustomNotifyAppleOfPassUpdateAction extends NotifyAppleOfPassUpdateAction
{
    public function execute(MobilePass $mobilePass)
    {
        // Your custom code here

        parent::execute($mobilePass);
    }
}
```

--------------------------------

### EventTicketPassClass::make

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Creates a new Google Wallet Pass Class with a unique suffix and saves it to Google's servers.

```APIDOC
## EventTicketPassClass::make(string $suffix)

### Description
Creates a new pass class instance. The suffix is used to generate the full class ID.

### Method
Static Method

### Parameters
- **$suffix** (string) - Required - A unique identifier for the class.

### Example
```php
EventTicketPassClass::make('beatles-shea-1965')
    ->setIssuerName('Fab Four Promotions')
    ->save();
```
```

--------------------------------

### PkPassReader Methods

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/reading-stored-passes

Methods available on the PkPassReader instance to inspect pass contents and properties.

```APIDOC
## PkPassReader Methods

### containingFiles()
Returns an array of files contained in the pass.

### containsFile(string $filename)
Returns a boolean indicating whether the pass contains a file with the given filename.

### manifestProperties()
Returns an array of properties from the pass manifest.

### manifestProperty(string $key)
Returns the value of the given property from the pass manifest.

### passProperties()
Returns an array of properties from the pass.json file.

### passProperty(string $key)
Returns the value of the given property from the pass.json file.

### toArray()
Returns an array representation of the pass.
```

--------------------------------

### Build an Apple Transit Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/boarding-pass

Use a custom subclass of BoardingPassBuilder to generate a transit pass for Apple Wallet.

```php
TrainPassBuilder::make()
    ->setOrganizationName('SNCB')
    ->setSerialNumber('TICKET-456')
    ->setDescription('Brussels to Antwerp, coach 3')
    ->setPassengerName(PersonName::make(givenName: 'George', familyName: 'Harrison'))
    ->setSeats(Seat::make(number: '24B'))
    ->addField('departure', 'BRU', label: 'Brussels-Central')
    ->addField('destination', 'ANT', label: 'Antwerp-Central')
    ->save();
```

--------------------------------

### Create an Apple Event Ticket

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/event-ticket

Use the EventTicketPassBuilder to define and save an Apple Wallet event ticket.

```php
use Spatie\LaravelMobilePass\Builders\Apple\EventTicketPassBuilder;

EventTicketPassBuilder::make()
    ->setOrganizationName('Fab Four Promotions')
    ->setSerialNumber('BTL-SHEA-0042')
    ->setDescription('The Beatles at Shea Stadium')
    ->addField('event', 'Beatles Live at Shea')
    ->addSecondaryField('section', 'B12')
    ->addSecondaryField('seat', 'Row 8, Seat 22')
    ->save();
```

--------------------------------

### Set Google Pass Images

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-images

Provide publicly reachable HTTPS URLs to the Class to set images for Google Wallet passes.

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

EventTicketPassClass::make('beatles-shea-1965')
    // ...
    ->setLogoUrl('https://cdn.example.com/beatles-logo.png')
    ->setHeroImageUrl('https://cdn.example.com/beatles-hero.png')
    ->save();
```

--------------------------------

### Generate a QR Code for a Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/handing-out-passes

Wrap the generated pass URL in a QR code for physical or screen-based distribution.

```php
use SimpleSoftwareIO\\\QrCode\\\Facades\\\QrCode;

QrCode::size(240)->generate($mobilePass->addToWalletUrl());
```

--------------------------------

### Laravel Mobile Pass configuration structure

Source: https://spatie.be/docs/laravel-mobile-pass/v1/installation-setup

The default configuration file structure for managing Apple and Google credentials, action classes, models, and queue settings.

```php
return [
    /*
     * Read the "Getting credentials from Apple" section in the documentation
     * to learn how to get these values.
     */
    'apple' => [
        'organization_name' => env('MOBILE_PASS_APPLE_ORGANIZATION_NAME'),
        'type_identifier' => env('MOBILE_PASS_APPLE_TYPE_IDENTIFIER'),
        'team_identifier' => env('MOBILE_PASS_APPLE_TEAM_IDENTIFIER'),

        'certificate' => env('MOBILE_PASS_APPLE_CERTIFICATE'),
        'certificate_path' => env('MOBILE_PASS_APPLE_CERTIFICATE_PATH'),
        'certificate_password' => env('MOBILE_PASS_APPLE_CERTIFICATE_PASSWORD'),

        'apple_push_base_url' => 'https://api.push.apple.com/3/device',
        'webservice' => [
            'secret' => env('MOBILE_PASS_APPLE_WEBSERVICE_SECRET'),
            'host' => env('MOBILE_PASS_APPLE_WEBSERVICE_HOST'),
        ],
    ],

    /*
     * Read the "Getting credentials from Google" section in the documentation
     * to learn how to get these values.
     */
    'google' => [
        'issuer_id' => env('MOBILE_PASS_GOOGLE_ISSUER_ID'),

        'service_account_key' => env('MOBILE_PASS_GOOGLE_KEY'),
        'service_account_key_path' => env('MOBILE_PASS_GOOGLE_KEY_PATH'),

        'origins' => [env('APP_URL')],

        'api_base_url' => env(
            'MOBILE_PASS_GOOGLE_API_BASE_URL',
            'https://walletobjects.googleapis.com/walletobjects/v1'
        ),
    ],

    /*
     * The actions perform core tasks offered by this package. You can customize the behaviour
     * by creating your own action class that extend the one that ships with the package.
     */
    'actions' => [
        'handle_google_callback' => Spatie\LaravelMobilePass\Actions\Google\HandleGoogleCallbackAction::class,
        'notify_apple_of_pass_update' => Spatie\LaravelMobilePass\Actions\Apple\NotifyAppleOfPassUpdateAction::class,
        'notify_google_of_pass_update' => Spatie\LaravelMobilePass\Actions\Google\NotifyGoogleOfPassUpdateAction::class,
        'register_device' => Spatie\LaravelMobilePass\Actions\Apple\RegisterDeviceAction::class,
        'unregister_device' => Spatie\LaravelMobilePass\Actions\Apple\UnregisterDeviceAction::class,
    ],

    /*
     * These are the models used by this package. You can replace them with
     * your own models by extending the ones that ship with the package.
     */
    'models' => [
        'mobile_pass' => Spatie\LaravelMobilePass\Models\MobilePass::class,
        'apple_mobile_pass_registration' => Spatie\LaravelMobilePass\Models\Apple\AppleMobilePassRegistration::class,
        'apple_mobile_pass_device' => Spatie\LaravelMobilePass\Models\Apple\AppleMobilePassDevice::class,
        'google_mobile_pass_event' => Spatie\LaravelMobilePass\Models\Google\GoogleMobilePassEvent::class,
    ],

    /*
     * Register custom pass builders here. Built-in builders are registered
     * automatically, so only add entries for builders you have authored yourself.
     * The array is keyed by the builder's snake_case name.
     */
    'builders' => [
        'apple' => [
            // 'my_custom_apple_pass' => MyCustomApplePassBuilder::class,
        ],
        'google' => [
            // 'my_custom_google_pass' => MyCustomGooglePassBuilder::class,
        ],
    ],

    /*
     * The queue connection and name used for pushing pass updates to the Apple and Google
     * wallet APIs. When the connection is `null`, updates will run synchronously.
     */
    'queue' => [
        'connection' => env('MOBILE_PASS_QUEUE_CONNECTION'),
        'name' => env('MOBILE_PASS_QUEUE_NAME', 'default'),
    ],
];
```

--------------------------------

### Inline Google service account key

Source: https://spatie.be/docs/laravel-mobile-pass/v1/getting-credentials-from-google

Provide the raw JSON content of the service account key directly in the environment variable.

```text
MOBILE_PASS_GOOGLE_KEY='{"type":"service_account",...}'
```

--------------------------------

### Add fields to Apple Wallet pass zones

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/field-zones

Use these methods to populate the different zones of an Apple Wallet pass. The $key parameter must be unique within the pass for future updates.

```php
addHeaderField(string $key, string $value, ?string $label, ?string $changeMessage, ?DateType $dateStyle, ?TimeStyleType $timeStyle, ?bool $showDateAsRelative)
addField(string $key, string $value, FieldType $type = FieldType::Primary, ...)
addSecondaryField(string $key, string $value, ...)
addAuxiliaryField(string $key, string $value, ...)
addBackField(string $key, string $value, ...)
```

--------------------------------

### Set Pass Background Colors

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-images

Apply a background color to Apple or Google passes using a hex string.

```php
$builder->setBackgroundColor('#1d72b8');
```

```php
EventTicketPassClass::make('beatles-shea-1965')
    ->setBackgroundColor('#1d72b8')
    ->save();
```

--------------------------------

### Build a Google Wallet Event Ticket

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/generating-your-first-pass

Use the Google EventTicketPassBuilder to create a ticket object linked to a pre-defined class.

```php
use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassBuilder;
use Spatie\LaravelMobilePass\Enums\BarcodeType;

$mobilePass = EventTicketPassBuilder::make()
    ->setClass('beatles-shea-1965')
    ->setAttendeeName('John Lennon')
    ->setSection('Floor A')
    ->setRow('12')
    ->setSeat('24')
    ->setBarcode(BarcodeType::Qr, 'TICKET-12345')
    ->save();
```

--------------------------------

### Apple CouponPassBuilder

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/coupon

Creates a coupon pass for Apple Wallet using the CouponPassBuilder class.

```APIDOC
## Apple CouponPassBuilder

### Description
Creates and saves a coupon pass for Apple Wallet.

### Usage
```php
use Spatie\LaravelMobilePass\Builders\Apple\CouponPassBuilder;

CouponPassBuilder::make()
    ->setOrganizationName('Spatie Store')
    ->setSerialNumber('COUPON-SUMMER25')
    ->setDescription('20% off everything this summer')
    ->addField('offer', '20%', label: 'Save')
    ->addSecondaryField('expires', '2026-08-31')
    ->save();
```
```

--------------------------------

### Retrieve Pass Classes

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Look up a specific class by its suffix or list all classes associated with the issuer account.

```php
$class = EventTicketPassClass::find('beatles-shea-1965');

if ($class) {
    // class exists on Google
}
```

```php
$classes = EventTicketPassClass::all();
```

--------------------------------

### Set Apple Pass High-Density Images

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-images

Provide multiple image paths to support different pixel densities for crisper rendering.

```php
$builder->setLogoImage(
    x1Path: public_path('images/logo.png'),
    x2Path: public_path('images/logo@2x.png'),
    x3Path: public_path('images/logo@3x.png'),
);
```

--------------------------------

### Class Builder Methods

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Methods available on all Class builders to add metadata like locations, links, and modules.

```APIDOC
## Class Builder Methods

### Methods
- **addLocation(float $latitude, float $longitude)** - Adds a geographic location.
- **addLink(string $uri, ?string $description)** - Adds a URI to the links module.
- **addTextModule(string $header, string $body, ?string $id)** - Adds a text module.
- **addImageModule(string $imageUrl, ?string $id)** - Adds an image module.

### Example
```php
EventTicketPassClass::make('id')
    ->addLocation(40.7569, -73.8458)
    ->addLink('https://example.com', 'Official site')
    ->save();
```
```

--------------------------------

### Google OfferPassBuilder

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/coupon

Creates an offer pass for Google Wallet using OfferPassClass for the offer definition and OfferPassBuilder for the individual redeemer object.

```APIDOC
## Google OfferPassBuilder

### Description
Defines an offer class and creates an individual offer pass for a redeemer in Google Wallet.

### Usage
```php
use Spatie\LaravelMobilePass\Builders\Google\OfferPassBuilder;
use Spatie\LaravelMobilePass\Builders\Google\OfferPassClass;

// Once, per offer
OfferPassClass::make('summer-2026-20off')
    ->setIssuerName('Spatie Store')
    ->setTitle('Save 20% this summer')
    ->setProvider('Spatie')
    ->setRedemptionChannel('ONLINE')
    ->setFinePrint('One use per customer. Expires 2026-08-31.')
    ->setLogoUrl('https://cdn.example.com/spatie-logo.png')
    ->save();

// Per redeemer
OfferPassBuilder::make()
    ->setClass('summer-2026-20off')
    ->setTitle('20% off for Dan')
    ->setRedemptionCode('DAN20SUMMER')
    ->save();
```
```

--------------------------------

### Handling Invalid Certificate Exceptions

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/handling-errors

Catch errors related to loading or using pass-signing certificates during generation.

```php
use Spatie\LaravelMobilePass\Exceptions\InvalidCertificate;

try {
    $mobilePass->generate();
} catch (InvalidCertificate $exception) {
    report($exception);
}
```

--------------------------------

### Field Addition Methods

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/field-zones

Methods available on the Apple builder to add fields to specific zones on a pass.

```APIDOC
## Field Addition Methods

### Description
Every Apple builder exposes specific methods to add fields to one of the five zones on a pass. Each field requires a unique key and a value, with optional parameters for labels, change messages, and date formatting.

### Methods
- `addHeaderField(string $key, string $value, ?string $label, ?string $changeMessage, ?DateType $dateStyle, ?TimeStyleType $timeStyle, ?bool $showDateAsRelative)`
- `addField(string $key, string $value, FieldType $type = FieldType::Primary, ...)`
- `addSecondaryField(string $key, string $value, ...)`
- `addAuxiliaryField(string $key, string $value, ...)`
- `addBackField(string $key, string $value, ...)`

### Parameters
- **$key** (string) - Required - A unique identifier for the field within the pass.
- **$value** (string) - Required - The content to display in the field.
- **$label** (string) - Optional - The display label for the field. Defaults to a title-cased version of the key.
- **$changeMessage** (string) - Optional - The notification message shown when the field value changes. Use :value as a placeholder.
- **$dateStyle** (DateType) - Optional - Formatting style for date values.
- **$timeStyle** (TimeStyleType) - Optional - Formatting style for time values.
- **$showDateAsRelative** (bool) - Optional - If true, renders the date as relative (e.g., "in 2 hours").
```

--------------------------------

### Create an Apple Airline Boarding Pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/boarding-pass

Use AirlinePassBuilder to generate a flight-specific boarding pass for Apple Wallet.

```php
use Spatie\LaravelMobilePass\Builders\Apple\AirlinePassBuilder;
use Spatie\LaravelMobilePass\Builders\Apple\Entities\Seat;

AirlinePassBuilder::make()
    ->setOrganizationName('Etihad')
    ->setSerialNumber('TICKET-123')
    ->setDescription('Etihad flight EY066 boarding pass')
    ->setDepartureAirportCode('AUH')
    ->setDestinationAirportCode('LHR')
    ->setPassengerName('Paul McCartney')
    ->setSeats(Seat::make(number: '12A'))
    ->addField('departure', 'AUH', label: 'Abu Dhabi')
    ->addField('destination', 'LHR', label: 'London')
    ->save();
```

--------------------------------

### Verify Pass Class Schema via API Round-trip

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/testing-your-passes

Use the find method to retrieve a pass class from Google's API and verify its properties against expected values to catch schema-level errors.

```php
$class = EventTicketPassClass::find('beatles-shea-1965');
expect($class->getEventName())->toBe('The Beatles | Live at Shea');
```

--------------------------------

### Test Pass Updates with Queued Jobs

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/testing-your-passes

Use Queue::fake to prevent actual push notifications during tests and verify that the correct update job is dispatched.

```php
use Illuminate\Support\Facades\Queue;
use Spatie\LaravelMobilePass\Jobs\PushPassUpdateJob;

Queue::fake();

$mobilePass->update(['content' => [...]]);

Queue::assertPushed(PushPassUpdateJob::class);
```

--------------------------------

### Mocking Google Wallet API requests

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/testing-your-passes

Fake requests to Google's API and ensure the access token cache is primed to prevent real OAuth calls.

```php
use Illuminate\Support\Facades\Http;

Http::fake();
cache()->put('mobile-pass.google.access-token', 'test-token', 3600);

$mobilePass = EventTicketPassBuilder::make()
    ->setClass('beatles-shea-1965')
    ->setAttendeeName('Test User')
    ->save();

Http::assertSent(fn ($request) => str_contains($request->url(), '/eventTicketObject')
    && $request->method() === 'POST'
    && $request['classId'] === '3388000000000000001.beatles-shea-1965'
);
```

--------------------------------

### Configure maximum distance for location relevance

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/pass-relevance

Override the default proximity radius for location-based relevance by specifying a distance in metres.

```php
$builder->setMaxDistance(500);
```

--------------------------------

### setDownloadName

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/apple-specific-methods

Sets the filename for the pass download.

```APIDOC
## setDownloadName(string $name)

### Description
Sets a custom filename for the pass download. If not set, it defaults to the pass's serial number.

### Parameters
- **$name** (string) - Required - The desired filename for the pass.
```

--------------------------------

### Handle MobilePassAdded event

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/events

Use this listener to perform actions when a user adds a pass to their wallet, such as updating user records.

```php
namespace App\Listeners;

use Spatie\LaravelMobilePass\Events\MobilePassAdded;

class TrackPassInstalls
{
    public function handle(MobilePassAdded $event): void
    {
        $event->mobilePass->user->update([
            'wallet_pass_installed_at' => now(),
        ]);
    }
}
```

--------------------------------

### Handling Google Wallet API failures

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/handling-errors

Catch GoogleWalletRequestFailed to inspect HTTP responses from Google's API when requests fail.

```php
use Spatie\LaravelMobilePass\Exceptions\GoogleWalletRequestFailed;

try {
    EventTicketPassClass::make('duplicate-id')
        ->setIssuerName('...')
        ->save();
} catch (GoogleWalletRequestFailed $exception) {
    logger()->error('Google Wallet rejected the request', [
        'status' => $exception->status,
        'body' => $exception->body,
        'endpoint' => $exception->endpoint,
    ]);
}
```

--------------------------------

### Store a mobile pass from a model

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/storing-mobile-passes

Use the generate method on a MobilePass model instance to retrieve the pass content and save it to the filesystem.

```php
use Spatie\LaravelMobilePass\Models\MobilePass;

$mobilePassContent = $mobilePass->generate();

file_put_contents('path/to/store/pass.pkpass', $mobilePassContent);
```

--------------------------------

### Google EventTicketPassBuilder and Class

Source: https://spatie.be/docs/laravel-mobile-pass/v1/available-pass-types/event-ticket

Usage of the Google EventTicketPassClass to define event metadata and EventTicketPassBuilder to create individual tickets.

```APIDOC
## Google EventTicketPassClass & EventTicketPassBuilder

### Description
Defines the event class (shared metadata) and individual ticket objects for Google Wallet.

### Methods (EventTicketPassClass)
- **make(string)**: Initializes the class with an ID.
- **setIssuerName(string)**: Sets the issuer name.
- **setEventName(string)**: Sets the event name.
- **setVenueName(string)**: Sets the venue name.
- **setVenueAddress(string)**: Sets the venue address.
- **setStartDate(Carbon)**: Sets the event start date.
- **setLogoUrl(string)**: Sets the logo URL.
- **save()**: Persists the class.

### Methods (EventTicketPassBuilder)
- **make()**: Initializes the builder.
- **setClass(string)**: Links the ticket to an EventTicketPassClass ID.
- **setAttendeeName(string)**: Sets the attendee name.
- **setSection(string)**: Sets the section.
- **setRow(string)**: Sets the row.
- **setSeat(string)**: Sets the seat.
- **setBarcode(BarcodeType, string)**: Sets the barcode type and value.
- **save()**: Persists the ticket.
```

--------------------------------

### Register event listeners

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/events

Explicitly register listeners in your EventServiceProvider if not using auto-discovery.

```php
protected $listen = [
    \Spatie\LaravelMobilePass\Events\MobilePassAdded::class => [
        \App\Listeners\TrackPassInstalls::class,
    ],
    \Spatie\LaravelMobilePass\Events\MobilePassRemoved::class => [
        \App\Listeners\ReactToUninstall::class,
    ],
];
```

--------------------------------

### Generate a MobilePass URL

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/handing-out-passes

Use the addToWalletUrl method to retrieve a platform-specific link for adding a pass to a digital wallet.

```php
$url = $mobilePass->addToWalletUrl();
```

```html
<a href="{{ $mobilePass->addToWalletUrl() }}">Add to Wallet</a>
```

--------------------------------

### Registering Mobile Pass Routes

Source: https://spatie.be/docs/laravel-mobile-pass/v1/installation-setup

Add the mobilePass macro to your routes file to enable Apple to reach your application.

```php
// in your routes file
Route::mobilePass();
```

--------------------------------

### Catching Apple Wallet Request Failures

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/handling-errors

Handle exceptions thrown when APNs rejects a pass update request.

```php
use Spatie\LaravelMobilePass\Exceptions\AppleWalletRequestFailed;

try {
    $mobilePass->updateField('seat', '13A');
} catch (AppleWalletRequestFailed $exception) {
    logger()->error('APNs push was rejected', [
        'status' => $exception->status,
        'body' => $exception->body,
        'endpoint' => $exception->endpoint,
    ]);
}
```

--------------------------------

### Reference a Pass Class

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/object-methods

Use setClass to link a pass object to a specific class suffix. Saving without a class will result in a RuntimeException.

```php
use Spatie\LaravelMobilePass\Builders\Google\EventTicketPassBuilder;

EventTicketPassBuilder::make()
    ->setClass('beatles-shea-1965')
    ->setAttendeeName('John Lennon')
    ->setSection('Floor A')
    ->setRow('12')
    ->setSeat('24')
    ->save();
```

--------------------------------

### Set total price on a pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/apple-specific-methods

Record a monetary value on the pass using the Price entity, which is useful for event tickets and coupons.

```php
use Spatie\LaravelMobilePass\Builders\Apple\Entities\Price;

$builder->setTotalPrice(Price::make(amount: '49.50', currencyCode: 'USD'));
```

--------------------------------

### Set Apple Pass Background Image

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-images

Use setBackgroundImage to define a background image for event tickets.

```php
$builder->setBackgroundImage(public_path('images/background.png'));
```

--------------------------------

### Bulk Update Apple Pass Fields

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/updating-a-pass

Use the builder to chain multiple field updates and save them in a single operation.

```php
$mobilePass->builder()
    ->updateField('seat', '13A')
    ->updateField('gate', 'D68')
    ->save();
```

--------------------------------

### Fetch mobile passes with advanced filtering

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/retrieving-mobile-passes

Use PassType, Platform, or a custom filter closure to scope the retrieved mobile pass.

```php
use Spatie\LaravelMobilePass\Enums\PassType;
use Spatie\LaravelMobilePass\Enums\Platform;

$couponPass = User::first()->firstMobilePass(PassType::Coupon);

$appleEventTicket = User::first()->firstMobilePass(PassType::EventTicket, Platform::Apple);

$customQuery = User::first()->firstMobilePass(filter: function ($query) {
    $query->where('type', PassType::Coupon);
});
```

--------------------------------

### Extending the MobilePass model

Source: https://spatie.be/docs/laravel-mobile-pass/v1/advanced-usage/customizing-models

Create a custom model class that extends the default MobilePass to include additional traits like SoftDeletes.

```php
use Illuminate\Database\Eloquent\SoftDeletes;
use Spatie\LaravelMobilePass\Models\MobilePass;

class CustomMobilePass extends MobilePass
{
    use SoftDeletes;
}
```

--------------------------------

### Generate and store a mobile pass without a model

Source: https://spatie.be/docs/laravel-mobile-pass/v1/apple-wallet/storing-mobile-passes

Call the generate method directly on an Apple builder class to create a pass without persisting a MobilePass model. Note that this prevents pushing updates to users.

```php
$mobilePassContent = AirlinePassBuilder::make()
    ->setOrganizationName('My organization')
//  other calls
    ->generate();

file_put_contents('path/to/store/pass.pkpass', $mobilePassContent);
```

--------------------------------

### Adding a barcode to an Apple pass

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/adding-barcodes

Use the setBarcode method on an Apple builder to define the barcode format and value.

```php
use Spatie\LaravelMobilePass\Builders\Apple\EventTicketPassBuilder;
use Spatie\LaravelMobilePass\Enums\BarcodeType;

EventTicketPassBuilder::make()
    ->setOrganizationName('Fab Four Promotions')
    ->setSerialNumber('BTL-SHEA-0042')
    ->setDescription('The Beatles at Shea Stadium')
    ->setBarcode(BarcodeType::Qr, 'TICKET-12345')
    ->save();
```

```php
$builder->setBarcode(
    BarcodeType::Qr,
    'TICKET-12345',
    altText: 'Show this at the gate',
);
```

--------------------------------

### Retire a Pass Class

Source: https://spatie.be/docs/laravel-mobile-pass/v1/google-wallet/pass-classes

Mark a class as retired by setting its review status to REJECTED, preventing further promotion while keeping existing passes functional.

```php
EventTicketPassClass::find('beatles-shea-1965')?->retire();
```

--------------------------------

### Return MobilePass from a Controller

Source: https://spatie.be/docs/laravel-mobile-pass/v1/basic-usage/handing-out-passes

Returning the MobilePass model directly from a controller leverages the Responsable interface to handle platform-specific delivery automatically.

```php
use Spatie\\\LaravelMobilePass\\\Models\\\MobilePass;

class AddToWalletController
{
    public function __invoke(MobilePass $mobilePass)
    {
        return $mobilePass;
    }
}
```
Tokens:
Raw