From 97da4026508647c1b74922c2ae59bd7ed79e30cd Mon Sep 17 00:00:00 2001 From: Auston Bunsen Date: Tue, 31 Mar 2026 00:52:43 -0400 Subject: [PATCH] Update README with doc-matching examples and feature matrix --- README.md | 302 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 248 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index cd502d8..6248bb6 100644 --- a/README.md +++ b/README.md @@ -19,97 +19,269 @@ composer require accessgrid/accessgrid-php ## Quick Start +### Initializing the Client + ```php getAccessCards()->issue([ - 'template_id' => 'your-template-id', - 'full_name' => 'John Doe', - 'expiration_date' => '2024-12-31' +```php +$card = $client->accessCards->provision([ + 'card_template_id' => '0xd3adb00b5', + 'employee_id' => '123456789', + 'tag_id' => 'DDEADB33FB00B5', + 'allow_on_multiple_devices' => true, + 'full_name' => 'Employee name', + 'email' => 'employee@yourwebsite.com', + 'phone_number' => '+19547212241', + 'classification' => 'full_time', + 'start_date' => (new DateTime('now', new DateTimeZone('UTC')))->format('c'), + 'expiration_date' => '2026-04-01T00:00:00.000Z', + 'employee_photo' => '[image_in_base64_encoded_format]', + 'title' => 'Engineering Manager', + 'metadata' => [ + 'department' => 'engineering', + 'badge_type' => 'contractor' + ] ]); -echo "Card issued: " . $card->id . "\n"; - -// Get a specific card -$card = $client->getAccessCards()->get('0xc4rd1d'); -echo "Card ID: " . $card->id . "\n"; -echo "State: " . $card->state . "\n"; -echo "Full Name: " . $card->full_name . "\n"; -echo "Install URL: " . $card->install_url . "\n"; -echo "Expiration Date: " . $card->expiration_date . "\n"; -echo "Card Number: " . $card->card_number . "\n"; -echo "Site Code: " . $card->site_code . "\n"; +echo "Install URL: {$card->url}\n"; +``` + +### Getting an Access Card + +```php +$card = $client->accessCards->get('0xc4rd1d'); + +echo "Card ID: {$card->id}\n"; +echo "State: {$card->state}\n"; +echo "Full Name: {$card->full_name}\n"; +echo "Install URL: {$card->install_url}\n"; +echo "Expiration Date: {$card->expiration_date}\n"; +echo "Card Number: {$card->card_number}\n"; +echo "Site Code: {$card->site_code}\n"; echo "Devices: " . count($card->devices) . "\n"; echo "Metadata: " . json_encode($card->metadata) . "\n"; +``` + +### Updating an Access Card + +```php +$card = $client->accessCards->update([ + 'card_id' => '0xc4rd1d', + 'employee_id' => '987654321', + 'full_name' => 'Updated Employee Name', + 'classification' => 'contractor', + 'expiration_date' => (new DateTime('now', new DateTimeZone('UTC')))->modify('+3 months')->format('c'), + 'employee_photo' => '[image_in_base64_encoded_format]', + 'title' => 'Senior Developer' +]); + +echo "Card updated successfully\n"; +``` -// List cards for a template -$cards = $client->getAccessCards()->list('your-template-id'); +### Listing Access Cards + +```php +$cards = $client->accessCards->list('0xd3adb00b5'); foreach ($cards as $card) { echo $card . "\n"; } +// With state filter +$activeCards = $client->accessCards->list('0xd3adb00b5', 'active'); +``` + +### Managing Card States + +```php // Suspend a card -$suspendedCard = $client->getAccessCards()->suspend($card->id); -echo "Card suspended: " . $suspendedCard->state . "\n"; +$client->accessCards->suspend(['card_id' => '0xc4rd1d']); + +// Resume a card +$client->accessCards->resume(['card_id' => '0xc4rd1d']); + +// Unlink a card +$client->accessCards->unlink(['card_id' => '0xc4rd1d']); + +// Delete a card +$client->accessCards->delete(['card_id' => '0xc4rd1d']); +``` + +## Console (Enterprise Features) + +### Creating a Card Template + +```php +$template = $client->console->createTemplate([ + 'name' => 'Employee Access Pass', + 'platform' => 'apple', + 'use_case' => 'employee_badge', + 'protocol' => 'desfire', + 'allow_on_multiple_devices' => true, + 'watch_count' => 2, + 'iphone_count' => 3, + 'background_color' => '#FFFFFF', + 'label_color' => '#000000', + 'label_secondary_color' => '#333333', + 'support_url' => 'https://help.yourcompany.com', + 'support_phone_number' => '+1-555-123-4567', + 'support_email' => 'support@yourcompany.com', + 'privacy_policy_url' => 'https://yourcompany.com/privacy', + 'terms_and_conditions_url' => 'https://yourcompany.com/terms', + 'metadata' => [ + 'version' => '2.1', + 'approval_status' => 'approved' + ] +]); + +echo "Template created successfully: {$template->id}\n"; ``` -## API Reference +### Updating a Card Template -### AccessGridClient +```php +$template = $client->console->updateTemplate([ + 'card_template_id' => '0xd3adb00b5', + 'name' => 'Updated Employee Access Pass', + 'allow_on_multiple_devices' => true, + 'watch_count' => 2, + 'iphone_count' => 3, + 'background_color' => '#FFFFFF', + 'label_color' => '#000000', + 'label_secondary_color' => '#333333', + 'support_url' => 'https://help.yourcompany.com', + 'support_phone_number' => '+1-555-123-4567', + 'support_email' => 'support@yourcompany.com', + 'privacy_policy_url' => 'https://yourcompany.com/privacy', + 'terms_and_conditions_url' => 'https://yourcompany.com/terms', + 'metadata' => [ + 'version' => '2.2', + 'last_updated_by' => 'admin' + ] +]); -The main client class for interacting with the AccessGrid API. +echo "Template updated successfully: {$template->id}\n"; +``` -#### Constructor +### Reading a Card Template ```php -new AccessGridClient(string $accountId, string $secretKey, string $baseUrl = 'https://api.accessgrid.com') +$template = $client->console->readTemplate([ + 'card_template_id' => '0xd3adb00b5' +]); + +echo "Template ID: {$template->id}\n"; +echo "Name: {$template->name}\n"; +echo "Platform: {$template->platform}\n"; +echo "Protocol: {$template->protocol}\n"; +echo "Multi-device: {$template->allow_on_multiple_devices}\n"; ``` -### Access Cards Service +### Event Logs -Access the access cards service via `$client->getAccessCards()`. +```php +$events = $client->console->eventLog([ + 'card_template_id' => '0xd3adb00b5', + 'filters' => [ + 'device' => 'mobile', + 'start_date' => (new DateTime('30 days ago'))->format('c'), + 'end_date' => (new DateTime('now'))->format('c'), + 'event_type' => 'install' + ] +]); -#### Methods +foreach ($events as $event) { + echo "Event: {$event->type} at {$event->timestamp} by {$event->user_id}\n"; +} +``` -- `issue(array $data): AccessCard` - Issue a new access card -- `provision(array $data): AccessCard` - Alias for issue() -- `get(string $cardId): AccessCard` - Get details about a specific access card -- `update(string $cardId, array $data): AccessCard` - Update an existing card -- `list(string $templateId, ?string $state = null): AccessCard[]` - List cards for a template -- `suspend(string $cardId): AccessCard` - Suspend a card -- `resume(string $cardId): AccessCard` - Resume a suspended card -- `unlink(string $cardId): AccessCard` - Unlink a card -- `delete(string $cardId): AccessCard` - Delete a card +### Ledger Items -### Console Service +```php +$result = $client->console->ledgerItems([ + 'page' => 1, + 'per_page' => 50, + 'start_date' => (new DateTime('30 days ago'))->format('c'), + 'end_date' => (new DateTime('now'))->format('c') +]); -Access the console service via `$client->getConsole()`. +foreach ($result['ledger_items'] as $item) { + echo "Amount: {$item['amount']}, Kind: {$item['kind']}, Date: {$item['created_at']}\n"; +} +``` -#### Methods +### iOS In-App Provisioning Preflight -- `createTemplate(array $data): Template` - Create a new card template -- `updateTemplate(string $templateId, array $data): Template` - Update a template -- `readTemplate(string $templateId): Template` - Get template details -- `getLogs(string $templateId, array $params = []): array` - Get event logs +```php +$response = $client->console->iosPreflight([ + 'card_template_id' => '0xt3mp14t3-3x1d', + 'access_pass_ex_id' => '0xp455-3x1d' +]); -## Error Handling +echo "Provisioning Credential ID: " . $response->provisioningCredentialIdentifier . "\n"; +echo "Sharing Instance ID: " . $response->sharingInstanceIdentifier . "\n"; +echo "Card Template ID: " . $response->cardTemplateIdentifier . "\n"; +echo "Environment ID: " . $response->environmentIdentifier . "\n"; +``` + +### Pass Template Pairs + +```php +$result = $client->console->listPassTemplatePairs([ + 'page' => 1, + 'per_page' => 50 +]); + +foreach ($result['pass_template_pairs'] as $pair) { + echo "Pair: {$pair->name} (ID: {$pair->id})\n"; + if ($pair->androidTemplate) { + echo " Android: {$pair->androidTemplate->name}\n"; + } + if ($pair->iosTemplate) { + echo " iOS: {$pair->iosTemplate->name}\n"; + } +} +``` -The SDK throws the following exceptions: +### HID Organizations -- `AccessGrid\Exceptions\AccessGridException` - Base exception for all API errors -- `AccessGrid\Exceptions\AuthenticationException` - Thrown for authentication failures +```php +// Create HID org +$org = $client->console->hid->orgs->create([ + 'name' => 'My Org', + 'full_address' => '1 Main St, NY NY', + 'phone' => '+1-555-0000', + 'first_name' => 'Ada', + 'last_name' => 'Lovelace' +]); + +// List all HID orgs +$orgs = $client->console->hid->orgs->list(); + +// Complete HID org registration +$result = $client->console->hid->orgs->activate([ + 'email' => 'admin@example.com', + 'password' => 'hid-password-123' +]); +``` + +## Error Handling ```php try { - $card = $client->getAccessCards()->issue($data); + $card = $client->accessCards->provision($data); } catch (AccessGrid\Exceptions\AuthenticationException $e) { echo "Authentication failed: " . $e->getMessage(); } catch (AccessGrid\Exceptions\AccessGridException $e) { @@ -119,4 +291,26 @@ try { ## License -MIT License \ No newline at end of file +MIT License + +## Feature Matrix + +| Feature | Supported | +|---|:---:| +| POST /v1/key-cards (issue) | Y | +| GET /v1/key-cards/{id} | Y | +| PATCH /v1/key-cards/{id} | Y | +| GET /v1/key-cards (list) | Y | +| POST .../suspend | Y | +| POST .../resume | Y | +| POST .../unlink | Y | +| POST .../delete | Y | +| POST /v1/console/card-templates | Y | +| PUT /v1/console/card-templates/{id} | Y | +| GET /v1/console/card-templates/{id} | Y | +| GET .../logs | Y | +| GET /v1/console/pass-template-pairs | Y | +| GET /v1/console/ledger-items | Y | +| POST /v1/console/ios-preflight | Y | +| Webhooks (list/create/delete) | Y | +| HID orgs (create/activate/list) | Y |