Skip to content

Commit 79ac331

Browse files
tschoffelentschoffelen
committed
docs: add documentation
1 parent 28bc39f commit 79ac331

File tree

3 files changed

+532
-5
lines changed

3 files changed

+532
-5
lines changed

‎README.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,13 @@ style it, take a look at the [docs at developers.apple.com](https://developer.ap
3434
- ✈️ [Flight ticket example](examples/full_sample/)
3535
- ☕️ [Starbucks card example](examples/starbucks_sample/)
3636

37-
### Functions to add files
37+
## API Documentation
3838

39-
- `addFile` : add a file without locale like `icon.png`
40-
- `addRemoteFile` : add a file from a url without locale like `https://xyz.io/icon.png`
41-
- `addLocaleFile` : add a localized file like `strip.png`
42-
- `addLocaleRemoteFile` : add a localized file from a url like `https://xyz.io/strip.png`
39+
API documentation is available for all main classes:
40+
41+
- **[PKPass API Documentation](docs/PKPass.md)** - Main class for creating Apple Wallet passes
42+
- **[PKPassBundle API Documentation](docs/PKPassBundle.md)** - Bundle multiple passes into a single `.pkpasses` file
43+
- **[FinanceOrder API Documentation](docs/FinanceOrder.md)** - Create Apple Wallet Orders for financial transactions
4344

4445
## Requesting the Pass Certificate
4546

@@ -91,6 +92,10 @@ The `key_new.p12` file should now be compatible with OpenSSL v3+.
9192

9293
## Changelog
9394

95+
**Version 2.4.0 - October 2024**
96+
97+
- Add `PKPassBundle` class to bundle multiple passes into a single `.pkpasses` file.
98+
9499
**Version 2.3.2 - September 2024**
95100

96101
- Fix order mime type, add better error reporting.

‎docs/FinanceOrder.md

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
# FinanceOrder API Documentation
2+
3+
The `FinanceOrder` class extends `PKPass` to create Apple Wallet Orders for financial transactions. It inherits all functionality from PKPass but generates orders with the `.order` extension and uses SHA-256 hashing instead of SHA-1.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Constructor](#constructor)
9+
- [Inherited Methods](#inherited-methods)
10+
- [Constants](#constants)
11+
- [Key Differences from PKPass](#key-differences-from-pkpass)
12+
- [Usage Example](#usage-example)
13+
- [Error Handling](#error-handling)
14+
15+
## Overview
16+
17+
The FinanceOrder class is designed for creating Apple Wallet Orders, which are used for financial transactions like purchases, invoices, and receipts. Orders differ from passes in that they use:
18+
19+
- SHA-256 hashing algorithm (instead of SHA-1)
20+
- `order.json` as the payload file (instead of `pass.json`)
21+
- `.order` file extension (instead of `.pkpass`)
22+
- `application/vnd.apple.finance.order` MIME type
23+
24+
## Constructor
25+
26+
### `__construct($certificatePath = null, $certificatePassword = null)`
27+
28+
Creates a new FinanceOrder instance. Same parameters as PKPass.
29+
30+
**Parameters:**
31+
- `$certificatePath` (string|bool, optional): Path to the P12 certificate file
32+
- `$certificatePassword` (string|bool, optional): Password for the certificate
33+
34+
**Example:**
35+
```php
36+
use PKPass\FinanceOrder;
37+
38+
// Create with certificate
39+
$order = new FinanceOrder('/path/to/certificate.p12', 'password');
40+
41+
// Create without certificate (set later)
42+
$order = new FinanceOrder();
43+
```
44+
45+
## Inherited Methods
46+
47+
The FinanceOrder class inherits all public methods from PKPass:
48+
49+
### Configuration Methods
50+
- `setCertificatePath($path)` - Sets the path to the certificate file
51+
- `setCertificatePassword($password)` - Sets the certificate password
52+
- `setWwdrCertificatePath($path)` - Sets the path to the WWDR certificate
53+
- `setTempPath($path)` - Sets the temporary directory path
54+
55+
### Data Management
56+
- `setData($data)` - Sets the order data (JSON content)
57+
- `setName($name)` - Sets the filename for the generated order
58+
- `getName()` - Gets the filename for the generated order
59+
60+
### File Management
61+
- `addFile($path, $name = null)` - Adds a file to the order package
62+
- `addRemoteFile($url, $name = null)` - Adds a file from a URL
63+
- `addFileContent($content, $name)` - Adds file content directly as a string
64+
65+
### Localization
66+
- `addLocaleStrings($language, $strings = [])` - Adds localized strings
67+
- `addLocaleFile($language, $path, $name = null)` - Adds a localized file
68+
- `addLocaleRemoteFile($language, $url, $name = null)` - Adds a localized file from URL
69+
- `addLocaleFileContent($language, $content, $name)` - Adds localized file content
70+
71+
### Order Creation
72+
- `create($output = false)` - Creates the actual `.order` file
73+
74+
## Constants
75+
76+
### Class Constants
77+
78+
- `FILE_TYPE` - 'order' - The type identifier for orders
79+
- `FILE_EXT` - 'order' - The file extension for orders
80+
- `MIME_TYPE` - 'application/vnd.apple.finance.order' - The MIME type for orders
81+
- `PAYLOAD_FILE` - 'order.json' - The main payload file name
82+
- `HASH_ALGO` - 'sha256' - The hashing algorithm used
83+
84+
**Example:**
85+
```php
86+
echo FinanceOrder::MIME_TYPE; // 'application/vnd.apple.finance.order'
87+
echo FinanceOrder::HASH_ALGO; // 'sha256'
88+
```
89+
90+
## Key Differences from PKPass
91+
92+
1. **File Extension**: Orders use `.order` instead of `.pkpass`
93+
2. **MIME Type**: `application/vnd.apple.finance.order` instead of `application/vnd.apple.pkpass`
94+
3. **Payload File**: `order.json` instead of `pass.json`
95+
4. **Hash Algorithm**: SHA-256 instead of SHA-1 for better security
96+
5. **Locale Files**: Uses `order.strings` instead of `pass.strings` for localization
97+
98+
## Usage Example
99+
100+
```php
101+
use PKPass\FinanceOrder;
102+
103+
try {
104+
// Create order
105+
$order = new FinanceOrder('/path/to/certificate.p12', 'password');
106+
107+
// Set order data
108+
$orderData = [
109+
'schemaVersion' => '1.0',
110+
'orderTypeIdentifier' => 'order.com.mycompany.myorder',
111+
'orderIdentifier' => 'ORDER12345',
112+
'webServiceURL' => 'https://example.com/orders/',
113+
'authenticationToken' => 'vxwxd7J8AlNNFPS8k0a0FfUFtq0ewzFdc',
114+
'merchant' => [
115+
'merchantIdentifier' => 'merchant.com.mycompany',
116+
'displayName' => 'My Company Store'
117+
],
118+
'orderNumber' => 'ORD001',
119+
'createdAt' => '2024-01-01T12:00:00Z',
120+
'orderState' => 'open',
121+
'payment' => [
122+
'summaryItems' => [
123+
[
124+
'label' => 'Subtotal',
125+
'amount' => '10.00'
126+
],
127+
[
128+
'label' => 'Tax',
129+
'amount' => '0.80'
130+
],
131+
[
132+
'label' => 'Total',
133+
'amount' => '10.80'
134+
]
135+
]
136+
]
137+
];
138+
139+
$order->setData($orderData);
140+
141+
// Add required files
142+
$order->addFile('/path/to/icon.png');
143+
$order->addFile('/path/to/logo.png');
144+
145+
// Add localization
146+
$order->addLocaleStrings('en', [
147+
'ORDER_TOTAL' => 'Total',
148+
'ORDER_DATE' => 'Order Date'
149+
]);
150+
151+
// Create and save the order
152+
$orderContent = $order->create(false);
153+
file_put_contents('myorder.order', $orderContent);
154+
155+
// Or output directly to browser
156+
// $order->create(true);
157+
158+
} catch (PKPassException $e) {
159+
echo 'Error creating order: ' . $e->getMessage();
160+
}
161+
```
162+
163+
## Error Handling
164+
165+
FinanceOrder inherits the same error handling as PKPass. All methods that can fail will throw a `PKPassException`. Always wrap critical operations in try-catch blocks:
166+
167+
```php
168+
try {
169+
$order->setData($orderData);
170+
$order->addFile('/path/to/icon.png');
171+
$orderContent = $order->create(false);
172+
} catch (PKPassException $e) {
173+
echo 'Error: ' . $e->getMessage();
174+
}
175+
```
176+
177+
### Common Errors
178+
179+
- **Missing certificate**: Ensure certificate path and password are correct
180+
- **Invalid order data**: Order data must be valid JSON or array
181+
- **Missing icon.png**: Orders require an icon.png file
182+
- **File not found**: Check that all file paths exist before adding them
183+
- **Invalid localization**: Locale strings must be a non-empty array
184+
185+
## Required Files
186+
187+
Like passes, every order must include an `icon.png` file. The class will throw a `PKPassException` if this file is missing.
188+
189+
**Recommended files:**
190+
- `icon.png` (required) - 29×29 points
191+
- `icon@2x.png` - 58×58 points
192+
- `icon@3x.png` - 87×87 points
193+
- `logo.png` - 160×50 points (max)
194+
- `logo@2x.png` - 320×100 points (max)
195+
- `logo@3x.png` - 480×150 points (max)

0 commit comments

Comments
 (0)