athwari/laravel-zkteco-adms

Laravel package implementing the ZKTeco ADMS protocol for biometric attendance devices.

v1.0.1 2026-07-01 01:19 UTC

Requires

• php: ^8.1
• illuminate/database: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/http: ^8.0|^9.0|^10.0|^11.0|^12.0
• illuminate/support: ^8.0|^9.0|^10.0|^11.0|^12.0

Requires (Dev)

• laravel/pint: ^1.1
• orchestra/testbench: ^6.47|^7.22|^8.25|^9.10|^10.0
• pestphp/pest: ^1.0|^2.0|^3.0
• pestphp/pest-plugin-laravel: ^1.0|^2.0|^3.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^1.10|^2.0
• phpunit/phpunit: ^9.0|^10.0 <10.5.60|^11.0
• rector/rector: ^1.0|^2.0

MIT

• laravel
• attendance
• Fingerprint
• biometric
• zkteco
• adms
• athwari
• iclock

Published on Packagist.org on 2026-07-01 01:23 UTC

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"

Publish and run the package migrations:

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

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
• default_timezone: fallback timezone used to interpret device-local attendance times
• storage_timezone: timezone used for normalized occurred_at values (defaults to UTC)

Set the normalized attendance storage timezone with:

ZKTECO_ADMS_STORAGE_TIMEZONE=UTC

Attendance logs retain the device-local time in recorded_at for backward compatibility. The same instant is also stored in occurred_at, converted to storage_timezone; use this field when comparing or reporting attendance across devices in different timezones.

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.