pkpass / pkpass
PHP PKPass class for iOS Wallet
Fund package maintenance!
tschoffelen
Installs: 1 856 596
Dependents: 2
Suggesters: 0
Security: 0
Stars: 917
Watchers: 54
Forks: 187
Open Issues: 5
Requires
- php: >=7.0
- ext-json: *
- ext-openssl: *
- ext-zip: *
Requires (Dev)
- phpunit/phpunit: ^9.6
README
This class provides the functionality to create passes for Wallet in Apple's iOS. It creates,
signs and packages the pass as a .pkpass
file according to Apple's documentation.
Requirements
- PHP 7.0 or higher (may also work with older versions)
- PHP ZIP extension (often installed by default)
- Access to filesystem to write temporary cache files
Installation
Simply run the following command in your project's root directory to install via Composer:
composer require pkpass/pkpass
Or add to your composer.json: "pkpass/pkpass": "^2.0.0"
Usage
Please take a look at the examples/example.php file for example usage. For more info on the JSON for the pass and how to style it, take a look at the docs at developers.apple.com.
Included demos
Functions to add files
addFile
: add a file without locale likeicon.png
addRemoteFile
: add a file from a url without locale likehttps://xyz.io/icon.png
addLocaleFile
: add a localized file likestrip.png
addLocaleRemoteFile
: add a localized file from a url likehttps://xyz.io/strip.png
Requesting the Pass Certificate
- Go to the iOS Provisioning portal.
- Create a new Pass Type ID, and write down the Pass ID you choose, you'll need it later.
- Click the edit button under your newly created Pass Type ID and generate a certificate according to the instructions shown on the page. Make sure not to choose a name for the Certificate but keep it empty instead.
- Download the .cer file and drag it into Keychain Access.
- Find the certificate you just imported and click the triangle on the left to reveal the private key.
- Select both the certificate and the private key it, then right-click the certificate in Keychain Access and
choose
Export 2 items…
. - Choose a password and export the file to a folder.
OpenSSL error
When you get the error 'Could not read certificate file. This might be related to using an OpenSSL version that has deprecated some older hashes. More info here: https://schof.link/2Et6z3m OpenSSL error: error:0308010C:digital envelope routines::unsupported' this is due to osx exporting the .p12 file using an old version of OpenSSL. To fix this issue, use the following commands:
openssl pkcs12 -legacy -in key.p12 -nodes -out key_decrypted.tmp
(replace key.p12 with your .p12 file name).
openssl pkcs12 -in key_decrypted.tmp -export -out key_new.p12
(use the newly generated key_new.p12 file in your pass generation below)
Getting the example.php sample to work
- Request the Pass certificate (
.p12
) as described above and upload it to your server. - Set the correct path and password on line 22.
- Change the
passTypeIdentifier
andteamIndentifier
to the correct values on lines 29 and 31 (teamIndentifier
can be found on the Developer Portal).
After completing these steps, you should be ready to go. Upload all the files to your server and navigate to the address of the examples/example.php file on your iPhone.
Debugging passes
If you aren't able to open your pass on an iPhone, plug the iPhone into a Mac and open the 'Console' application. On the left, you can select your iPhone. You will then be able to inspect any errors that occur while adding the pass:
Trust evaluate failure: [leaf TemporalValidity]
: If you see this error, your pass was signed with an outdated certificate.Trust evaluate failure: [leaf LeafMarkerOid]
: You did not leave the name of the certificate empty while creating it in the developer portal.
Changelog
Version 2.1.0 - April 2023
- Add alternative method for extracting P12 contents to circumvent issues in recent versions of OpenSSL.
Version 2.0.2 - October 2022
- Switch to
ZipArchive::OVERWRITE
method of opening ZIP due to PHP 8 deprecation (#120).
Version 2.0.1 - October 2022
- Update WWDR certificate to v6 (#118).
Version 2.0.0 - September 2022
- Changed signature of constructor to take out third
$json
parameter. - Remove deprecated
setJSON()
method. - Removed
checkError()
andgetError()
methods in favor of exceptions.
Support & documentation
Please read the instructions above and consult the Wallet Documentation before submitting tickets or requesting support. It might also be worth to check Stackoverflow, which contains quite a few questions about this library.
Custom consulting sessions availabe for implementation support and feature development.