README

This package provides the backend ADMS protocol implementation for ZKTeco biometric devices in Laravel.

It handles device communication, attendance ingestion, user synchronization, and command dispatching. The package is intentionally tenancy-agnostic.

If you need tenant-aware behavior in Filament, use athwari/filament-zkteco-adms, which owns tenancy configuration and tenant column management.

Features

• Device lifecycle management (registration, activity tracking, stale device eviction command)
• ADMS protocol endpoints for cdata, registry, getrequest, devicecmd, inspect, and test
• Attendance log parsing and persistence
• User synchronization from device operation logs and user query responses
• Command queueing, polling, and confirmation handling
• Configurable model bindings via zkteco-adms.models.*
• Optional event dispatching for device, attendance, command, and user sync flows

Installation

Install the package via Composer:

composer require athwari/laravel-zkteco-adms

Configuration

Publish the configuration file:

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

Migrations are loaded automatically by the service provider.

Main configuration areas in config/zkteco-adms.php:

• table_prefix: prefix used for all ZKTeco tables
• routes: endpoint prefix, middleware, and optional domain
• device: registration and limits configuration
• response: handshake defaults
• models: model class overrides for device, user, attendance log, command, and event
• events: per-event dispatch toggles
• enable_inspect: enables the inspect endpoint

Usage

ADMS Endpoints

By default, routes are mounted under /iclock (configurable via zkteco-adms.routes.prefix):

• GET/POST /iclock/cdata
• GET/POST /iclock/registry
• GET /iclock/getrequest
• POST /iclock/devicecmd
• GET /iclock/inspect (when enabled)
• GET/POST /iclock/test

Services

Core services are container singletons:

• Athwari\LaravelZktecoAdms\Services\DeviceManager
• Athwari\LaravelZktecoAdms\Services\CommandManager
• Athwari\LaravelZktecoAdms\Services\AttendanceParser
• Athwari\LaravelZktecoAdms\Services\DeviceCommandBuilder

Models

Default models:

• Athwari\LaravelZktecoAdms\Models\ZktecoDevice
• Athwari\LaravelZktecoAdms\Models\ZktecoUser
• Athwari\LaravelZktecoAdms\Models\ZktecoAttendanceLog
• Athwari\LaravelZktecoAdms\Models\ZktecoDeviceCommand
• Athwari\LaravelZktecoAdms\Models\ZktecoDeviceEvent

You can override these through config('zkteco-adms.models.*') in your application.

Facade

The package ships with an auto-discovered facade alias: ZktecoAdms

use ZktecoAdms;

$device = ZktecoAdms::registerDevice('SN123456');

if (ZktecoAdms::deviceExists('SN123456')) {
    ZktecoAdms::setDeviceTimezone('SN123456', 'Asia/Riyadh');
}

$commandId = ZktecoAdms::sendCheckCommand('SN123456');

ZktecoAdms::commandBuilder()->reboot('SN123456');

If you prefer explicit imports:

use Athwari\LaravelZktecoAdms\Facades\ZktecoAdms;

Testing

Run the test suite with:

composer test

Additional useful scripts:

composer test-coverage
composer analyse
composer format

Tenancy Boundary

This package no longer owns multi-tenancy configuration.

• Core package responsibility: protocol and domain logic
• Filament plugin responsibility: tenant ownership, tenant columns, and tenant-scoped UI queries

Contributing

Please see CONTRIBUTING for details.

Security

Please review SECURITY if you discover a vulnerability in this package.

Credits

• Athwari
• All Contributors

License

The MIT License (MIT). Please see LICENSE.md for more information.