README

A production-grade, enterprise-ready ZKTeco ADMS (Automatic Data Master Server) Push Protocol engine for Laravel applications.

Unlike lightweight attendance-only libraries, laravel-zkteco-adms-core implements the complete ZKTeco ADMS Push protocol specification: dynamic handshake configuration (GET OPTION FROM), multimodal biometrics (biodata face & palm, templatev10 fingerprints), physical access control matrices (userauthorize), 10-byte hex relay actuations (CONTROL DEVICE), interactive remote biometric enrollment, and asynchronous execution status tracking (/iclock/devicecmd).

Key Features

Dynamic State & Handshake Management: Generates full GET OPTION FROM: <SN> configuration responses with cursor tracking (Stamp, OpStamp), polling timing (Delay, Realtime=1), and encryption flags.
Multimodal Biometrics Support: Ingestion and provisioning for Visible Light Facial meshes (BioType::VisibleLightFace), Palm print templates (BioType::Palm), Finger veins, and Fingerprints (templatev10).
Physical Access Control & Timezones: Manage door authorization matrices with built-in bug mitigation that prevents access rights stacking on terminal firmware.
Hardware Relays & Remote Control: Door actuation (e.g., open door 1 for 5 seconds: CONTROL DEVICE 010101FF05), canceling duress alarms, remote reboots, and clock drift synchronization.
Interactive Remote Biometrics: Trigger enrollment loops directly on physical terminals (ENROLL_BIO, ENROLL_FP).
Asynchronous Command Loop & ACK Tracking: Queues commands, delivers them via /iclock/getrequest, and tracks asynchronous execution callbacks (Return=0, -1002, -30).
Event-Driven Architecture: Rich Laravel events for attendance punches, user syncs, command execution confirmations, and ghost enrollment detection.
Strict Quality: 100% PHPStan Level 8 clean, fully Pint formatted, with extreme test coverage across edge cases and malformed hardware data.

Installation

You can install the package via Composer:

composer require dewanlab/laravel-zkteco-adms-core

Publish configuration and migrations:

php artisan vendor:publish --tag="zkteco-adms-core-config"
php artisan vendor:publish --tag="zkteco-adms-core-migrations"
php artisan migrate

Quick Start

1. Configure Hardware Terminal

Point your ZKTeco biometric terminal's Cloud Server / ADMS Settings to your server:

Server IP / Domain: your-domain.com
Server Port: 80 (or 443 for HTTPS)
Server Path / URL: /iclock/cdata (or enable cloud mode)

The package automatically handles all endpoints:

GET /iclock/cdata & /iclock/registry (Handshake)
POST /iclock/cdata (Log ingestion: ATTLOG, OPERLOG, BIODATA)
GET /iclock/getrequest (Command delivery heartbeat)
POST /iclock/devicecmd (Asynchronous execution confirmation)
GET /iclock/rtdata (Clock synchronization)

2. Using the Facade

use DewanLab\LaravelZktecoAdmsCore\Facades\ZktecoAdms;
use DewanLab\LaravelZktecoAdmsCore\DTOs\BiodataPayload;
use DewanLab\LaravelZktecoAdmsCore\Enums\BioType;

// Unlock Door 1 for 5 seconds
ZktecoAdms::unlockDoor('SN123456789', doorId: 1, durationSeconds: 5);

// Sync an employee/user to a terminal
ZktecoAdms::syncUser(
    device: 'SN123456789',
    pin: '1001',
    name: 'John Doe',
    privilege: 0,
    card: '99887766'
);

// Authorize door access (safely removes previous rights to avoid firmware stacking bug)
ZktecoAdms::authorizeUserAccess(
    device: 'SN123456789',
    pin: '1001',
    doorId: 1,
    timezoneId: 1
);

// Provision a Visible Light Face template
ZktecoAdms::syncBiodata(
    device: 'SN123456789',
    biodata: new BiodataPayload(
        pin: '1001',
        bioType: BioType::VisibleLightFace,
        index: 0,
        template: 'BASE64_ENCODED_FACE_MESH...'
    )
);

// Trigger interactive enrollment directly on the device
ZktecoAdms::triggerRemoteEnrollment('SN123456789', pin: '1001', type: BioType::VisibleLightFace);

// Reboot device remotely
ZktecoAdms::rebootDevice('SN123456789');

3. Listening to Events

Listen to events in your EventServiceProvider or listeners:

use DewanLab\LaravelZktecoAdmsCore\Events\AttendanceLogged;
use DewanLab\LaravelZktecoAdmsCore\Events\CommandAcknowledged;
use DewanLab\LaravelZktecoAdmsCore\Events\CommandFailed;
use DewanLab\LaravelZktecoAdmsCore\Events\UserSynchronized;

Event::listen(AttendanceLogged::class, function (AttendanceLogged $event) {
    // $event->attendanceLog (ZkAttendanceLog)
    // $event->device (ZkDevice)
    Log::info("Employee {$event->attendanceLog->pin} punched at {$event->attendanceLog->recorded_at}");
});

Event::listen(CommandAcknowledged::class, function (CommandAcknowledged $event) {
    Log::info("Command #{$event->command->id} executed successfully by terminal {$event->device->serial_number}");
});

Documentation

Detailed documentation is available in the docs/ directory:

Testing & Quality

Run the test suite:

composer test

Run static analysis (PHPStan Level 8):

composer run types:check

Format code:

composer run format

License

The MIT License (MIT). Please see License File for more information.

dewanlab / laravel-zkteco-adms-core

Package info

Security

Statistics