PHP code example of nugsoft / hikbridge-laravel-sdk

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

nugsoft / hikbridge-laravel-sdk example snippets

return [
    // Base URL of the HikBridge API (no trailing slash needed)
    'base_url' => env('HIKBRIDGE_BASE_URL', 'https://hikbridge.clocknesthr.com/api'),

    // Per-business API key (hbk_...) — sent as Authorization: Bearer on every request
    'api_key' => env('HIKBRIDGE_API_KEY'),

    // HTTP timeout in seconds
    'timeout' => (int) env('HIKBRIDGE_TIMEOUT', 30),

    // Automatic retry on transient connection-level failures (timeouts,
    // DNS/refused connections). HTTP error responses (4xx/5xx) are never
    // retried — they are surfaced immediately as typed exceptions (see below).
    // Set 'times' to 0 to disable retries entirely
    'retry' => [
        'times' => 3,
        'sleep' => 100, // milliseconds between retries
    ],
];

use Nugsoft\HikBridge\Facades\HikBridge;

HikBridge::business()->get();
HikBridge::devices()->list();
HikBridge::persons()->get(57);
HikBridge::biometrics(57)->uploadFace(35, $base64);
HikBridge::events()->list(['per_page' => 50]);
HikBridge::webhooks()->create([...]);
HikBridge::operations()->get('op_abc123');

$business = HikBridge::business()->get();
// $business['data']['id'], $business['data']['name'], ...

// List all devices in the business
$devices = HikBridge::devices()->list();

foreach ($devices['data'] as $device) {
    echo $device['id'] . ' — ' . $device['name'];
}

// Get a single device
$device = HikBridge::devices()->get(35);

$persons = HikBridge::persons()->list([
    'per_page' => 25,
    'search'   => 'john',      // matches person_code, first_name, last_name
    'status'   => 'active',    // active | inactive
    'cursor'   => $nextCursor, // for pagination
]);

$nextCursor = $persons['meta']['next_cursor'] ?? null;

$person = HikBridge::persons()->get(57);
echo $person['data']['first_name'];

$op = HikBridge::persons()->create([
    'person_code' => 'EMP1003',
    'first_name'  => 'Amina',
    'last_name'   => 'Nakato',
    'status'      => 'active',
]);
// Returns PendingOperation (HTTP 202) — poll until all devices finish
$result = $op->waitUntilDone(timeout: 60);

$person = HikBridge::persons()->create([
    'person_code' => 'EMP1003',
    'first_name'  => 'Amina',
    'last_name'   => 'Nakato',
    'status'      => 'active',
    'device_id'   => 35,
]);
// Returns array (HTTP 201) — person + device_sync_status
echo $person['data']['device_sync_status'];

$person = HikBridge::persons()->update(57, [
    'first_name' => 'Amina',
    'last_name'  => 'Nakato-Smith',
    'status'     => 'active',
]);
// person_code cannot be updated
// If name changes on a synced person, device_sync_status resets to 'pending'

$op = HikBridge::persons()->delete(57);
$result = $op->waitUntilDone(timeout: 60);

$result = HikBridge::persons()->deleteFromDevice(personId: 57, deviceId: 35);
// Local record is soft-deleted even if the device is unreachable

$summary = HikBridge::biometrics(57)->summary(deviceId: 35);
// Returns face, fingerprint, and access card status for the person on that device

$base64 = base64_encode(file_get_contents('/path/to/photo.jpg'));
// data-URI prefix (data:image/jpeg;base64,...) is accepted but not aved locally but could not be pushed to the device
    // $result['warning']['pushed_to_device'] === false
    logger()->warning('Face not pushed to device', $result['warning']);
}

// Trigger capture
HikBridge::biometrics(57)->captureFace(deviceId: 35);

// Poll until done
do {
    sleep(2);
    $progress = HikBridge::biometrics(57)->faceCaptureProgress(deviceId: 35);
} while ($progress['data']['status'] === 'capturing');

HikBridge::biometrics(57)->deleteFace(deviceId: 35);

// With a base64 template — downloaded to the device immediately
HikBridge::biometrics(57)->storeFingerprint(
    deviceId: 35,
    fingerIndex: 1,
    template: $base64Template,
);

// With template: null — enrollment recorded locally, no device push
HikBridge::biometrics(57)->storeFingerprint(deviceId: 35, fingerIndex: 1);

// Trigger capture — specify which finger
HikBridge::biometrics(57)->captureFingerprint(deviceId: 35, fingerIndex: 1);

// Poll until done
do {
    sleep(2);
    $progress = HikBridge::biometrics(57)->fingerprintCaptureProgress(deviceId: 35);
} while ($progress['data']['status'] === 'capturing');

HikBridge::biometrics(57)->deleteFingerprint(deviceId: 35, fingerIndex: 1);

HikBridge::biometrics(57)->addAccessCard(
    deviceId: 35,
    cardNo: '1234567890',
    cardType: 1, // 1 = normal; device-defined, up to 4
);

HikBridge::biometrics(57)->deleteAccessCard(deviceId: 35, cardNo: '1234567890');

$page = HikBridge::events()->list([
    'per_page'    => 50,
    'from'        => '2026-06-01T00:00:00',  // ISO 8601
    'to'          => '2026-06-13T23:59:59',  // ISO 8601
    'person_code' => 'EMP1001',
    'event_type'  => 'face',                 // face | card | fingerprint
    'device_id'   => 35,
    'cursor'      => $nextCursor,
]);

$nextCursor = $page['meta']['next_cursor'] ?? null;

$cursor = null;

do {
    $page   = HikBridge::events()->list(['per_page' => 100, 'cursor' => $cursor]);
    $cursor = $page['meta']['next_cursor'] ?? null;

    foreach ($page['data'] as $event) {
        // process each event
    }
} while ($cursor);

$result = HikBridge::events()->triggerSync(
    from: '2026-06-12T00:00:00',
    to:   '2026-06-13T23:59:59',
);
// Returns 202 — 

$webhook = HikBridge::webhooks()->create([
    'url'         => 'https://yourapp.com/webhooks/hikbridge',
    'event_types' => ['access.event', 'person.synced'],
    'is_active'   => true,
]);

// The signing secret is returned EXACTLY ONCE — store it immediately
$secret = $webhook['data']['secret']; // whsec_...

$webhooks = HikBridge::webhooks()->list();

$webhook = HikBridge::webhooks()->get(1);

HikBridge::webhooks()->update(1, [
    'event_types' => ['*'],
    'is_active'   => true,
    // 'url' can also be updated; 'secret' cannot be changed
]);

HikBridge::webhooks()->delete(1); // returns void, HTTP 204

$result = HikBridge::webhooks()->sendTestPing(1);
// Returns 202 with a delivery_id — check deliveries() for the result

$deliveries = HikBridge::webhooks()->deliveries(1);
// Paginated log of payloads, HTTP response codes, and retry status

$payload   = $request->getContent();
$signature = $request->header('X-HikBridge-Signature');
$secret    = config('services.hikbridge_webhook_secret'); // the whsec_... you stored

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (! hash_equals($expected, $signature)) {
    abort(401, 'Invalid webhook signature');
}

$event = $request->json()->all();
// $event['type'], $event['data'], ...

$operation = HikBridge::operations()->get('op_abc123');

// $operation['data']['status']      → pending | completed | failed
// $operation['data']['devices'][]   → per-device results

$op->operationId; // string — the operation ID, e.g. "op_abc123"
$op->data;        // array — the entity being created or deleted
$op->isPending(); // bool — always true (the operation was just created)

$op = HikBridge::persons()->create([
    'person_code' => 'EMP1003',
    'first_name'  => 'Amina',
    'last_name'   => 'Nakato',
    'status'      => 'active',
]);

try {
    $result = $op->waitUntilDone(timeout: 60, interval: 2);
    // $result['data']['status'] === 'completed'
    // $result['data']['devices'] → per-device sync results
} catch (\Nugsoft\HikBridge\Exceptions\HikBridgeException $e) {
    // Operation failed or timed out
    logger()->error('Sync failed: ' . $e->getMessage());
}

use Nugsoft\HikBridge\Exceptions\NotFoundException;
use Nugsoft\HikBridge\Exceptions\ValidationException;
use Nugsoft\HikBridge\Exceptions\ForbiddenException;
use Nugsoft\HikBridge\Exceptions\HikBridgeException;

try {
    $person = HikBridge::persons()->get($id);

} catch (NotFoundException $e) {
    return response()->json(['error' => 'Person not found'], 404);

} catch (ValidationException $e) {
    // $e->errors() returns ['field' => ['message', ...], ...]
    return response()->json(['errors' => $e->errors()], 422);

} catch (ForbiddenException $e) {
    // API key does not have the 

try {
    HikBridge::persons()->create(['first_name' => 'Amina']); // missing person_code
} catch (ValidationException $e) {
    $errors = $e->errors();
    // ['person_code' => ['The person code field is 

use Illuminate\Support\Facades\Http;
use Nugsoft\HikBridge\Facades\HikBridge;

Http::fake([
    '*/v1/persons/57*' => Http::response([
        'data' => ['id' => 57, 'first_name' => 'Amina', 'person_code' => 'EMP001'],
    ], 200),
]);

$person = HikBridge::persons()->get(57);

expect($person['data']['id'])->toBe(57);
Http::assertSentCount(1);

Http::fake([
    '*/v1/persons'           => Http::response([
        'operation_id' => 'op_abc123',
        'data'         => ['id' => 10, 'person_code' => 'EMP001'],
    ], 202),
    '*/v1/operations/op_abc123' => Http::response([
        'data' => ['status' => 'completed', 'devices' => []],
    ], 200),
]);

$op = HikBridge::persons()->create([
    'person_code' => 'EMP001',
    'first_name'  => 'Amina',
    'last_name'   => 'Nakato',
    'status'      => 'active',
]);

expect($op)->toBeInstanceOf(\Nugsoft\HikBridge\PendingOperation::class)
    ->and($op->operationId)->toBe('op_abc123');

$result = $op->waitUntilDone(timeout: 10, interval: 0);
expect($result['data']['status'])->toBe('completed');

use Nugsoft\HikBridge\Exceptions\NotFoundException;

Http::fake([
    '*/v1/persons/999*' => Http::response(['message' => 'Not found'], 404),
]);

expect(fn () => HikBridge::persons()->get(999))
    ->toThrow(NotFoundException::class);

use Nugsoft\HikBridge\Exceptions\ValidationException;

Http::fake([
    '*/v1/persons' => Http::response([
        'message' => 'The given data was invalid.',
        'errors'  => ['person_code' => ['The person code field is 

Http::fake(['*/v1/persons*' => Http::response(['data' => []], 200)]);

HikBridge::persons()->list(['per_page' => 10, 'status' => 'active']);

Http::assertSent(function ($request) {
    return str_contains($request->url(), 'per_page=10')
        && str_contains($request->url(), 'status=active');
});

bash
php artisan vendor:publish --tag=hikbridge-config