Download the PHP package nugsoft/hikbridge-laravel-sdk without Composer

HikBridge Laravel SDK

A Laravel SDK for the HikBridge External Integration API — a brand-agnostic REST API that sits between external business applications (HR, POS, clinic) and physical Hikvision access-control devices. This package abstracts the HikBridge API behind a clean, fluent PHP interface so your application never speaks the underlying device protocol directly.

Table of Contents

• Requirements
• Installation
• Configuration
• How It Works
• Demo Project
• Authentication & Scopes
• Resources
  • Business
  • Devices
  • Persons
  • Biometrics
  • Events
  • Webhooks
  • Operations
• Async Operations & PendingOperation
• Exception Handling
• Testing
• Source Layout

Requirements

• PHP 8.2+
• Laravel 11+

Installation

The service provider and HikBridge facade are auto-discovered by Laravel — no manual registration is needed.

Publish the config file:

Configuration

Add the following to your .env file:

The published config/hikbridge.php exposes additional options:

Retries vs. error responses. Retries apply only to ConnectionException (the request never reached the server). Any HTTP response the server returns — including 5xx — flows straight through to the SDK's exception mapping, so a 500/503 becomes a ServerException you can catch, not a raw HTTP-client exception.

How It Works

The SDK exposes a single HikBridge facade. Every method group is accessed through a resource accessor:

Return types:

• Most methods return a plain PHP array (decoded JSON).
• Single-resource responses are wrapped: ['data' => [...]]
• List responses are cursor-paginated: ['data' => [...], 'meta' => ['next_cursor' => '...']]
• Endpoints that fan out to all devices return a PendingOperation object (HTTP 202) instead of an array — see Async Operations.

Demo Project

Get hands-on with the SDK through our demo project. You can either explore the source code or try the live hosted application:

• Source Repository: https://github.com/nugsoft/hikbridge-demo — a complete Laravel application showcasing the SDK in action
• Live Demo: https://hikbridge-demo.nugsoftstagging.com/ — test the SDK features in a running environment

The demo covers all major workflows including person management, biometric enrollment, access card registration, and webhook integration.

Authentication & Scopes

Every request to /v1/* is authenticated with the API key set in HIKBRIDGE_API_KEY. The key is sent as Authorization: Bearer hbk_... automatically.

Keys are scoped to a set of abilities. Attempting an endpoint the key is not scoped for returns a ForbiddenException (403).

Resources

Business

Returns the single business the API key belongs to. Requires ability business:read.

Devices

Devices are the access-control units registered to the business. Every biometric operation requires a device_id from this list.

Device object includes: id, name, integration_mode, capabilities (e.g. face_capture, fingerprint_capture, card_enrollment).

Persons

Persons are the people managed across the business's devices. person_code is the cross-system identifier — it must be unique, alphanumeric, max 16 characters, and is immutable after creation.

List persons

Get one person

Create a person

Person creation has two modes depending on whether you include device_id:

Async (no device_id) — fans out to all active devices:

Sync (with device_id) — syncs to one device only:

Update a person

Delete a person from all devices (async)

Always returns a PendingOperation — the deletion fans out to every device.

Delete a person from one device (sync)

Biometrics

Biometric operations are always device-specific. Access them through HikBridge::biometrics(int $personId).

Capability check: Live capture endpoints (face capture, fingerprint capture) return 422 early if the device does not support that capability. Check $device['data']['capabilities'] beforehand if needed.

Summary

Face

Upload a face photo:

Live face capture (person stands in front of the device camera):

Delete face:

Fingerprint

finger_index uses the convention: 0 = right thumb, 1–4 = right index to right little, 5 = left thumb, 6–9 = left index to left little.

Store a fingerprint template:

Live fingerprint capture (person places finger on the scanner):

Delete a fingerprint:

Access Card

Register a card:

Remove a card:

Events

Access events are aggregated from all devices and stored in HikBridge. They are returned newest-first and are cursor-paginated.

List events

Paginate through all events:

Trigger a manual sync

HikBridge polls devices on a 5-minute schedule. Call triggerSync() for an on-demand pull. Both parameters are optional — the server defaults to the last 24 hours.

Webhooks

Webhooks push signed payloads to an external URL when events occur in HikBridge.

Supported event types:

Create a subscription

List, get, update, delete

Send a test ping

Dispatches a signed test payload to the subscription URL. Useful for verifying your endpoint is reachable. Requires the queue worker running.

View delivery history

Verifying incoming webhook signatures

Every webhook delivery includes an X-HikBridge-Signature header signed with HMAC-SHA256.

Operations

Any endpoint that fans out to all devices returns HTTP 202 with an operation_id. Poll the operation to track per-device progress.

In practice, prefer PendingOperation::waitUntilDone() over manual polling — see the next section.

Async Operations & PendingOperation

Operations that target all active devices (create person, delete person, event sync) return a PendingOperation instead of an array. This object wraps the 202 response and lets you either poll manually or block until done.

Properties

waitUntilDone()

Blocks the current process, polling GET /v1/operations/{id} at regular intervals until the operation completes or the timeout expires.

Queues: Async operations require the Laravel queue worker to be running. In local development, php artisan queue:work (or composer dev if configured) handles this.

Exception Handling

All exceptions extend Nugsoft\HikBridge\Exceptions\HikBridgeException, so you can catch them individually or with the base class.

ValidationException field errors:

Testing

The SDK wraps Laravel's Http facade, so Http::fake() is all you need — no custom mock layer or test doubles required.

Faking a successful response

Faking an async (202) create

Faking an error response

Faking a validation error

Asserting request details

License

MIT License. See LICENSE for details.