Download the PHP package olorunda/laravel-zkteco-push without Composer

ZKTeco ADMS Push SDK Laravel Package & REST API Interpreter Bridge

A clean, native Laravel Package (olorunda/laravel-zkteco-push) that acts as an interpreter bridge between ZKTeco Biometric Devices (Fingerprint, Face, Palm, RFID Access Control) and any External Application / API (HR, ERP, Payroll System).

🚀 Key Package Features

• 🔌 Native Laravel Auto-Discovery: Automatically registers Service Provider, Facades, Routes, and Database Migrations.
• ⚡ Fluent ZkTecoPush Facade: Chain device actions using expressive array parameters (deleteUser, addUser, queueCommand, reboot, syncTime, unlockDoor).
• 🕒 Delayed Action Scheduler: Queue user deletions or command dispatches with time delays (delay_minutes, delay_seconds, or delaySeconds: 120).
• 🎧 Native Laravel Events: Automatically dispatches AttendancePushed, DeviceHeartbeat, and CommandExecuted events for queued listeners/jobs.
• 🗄️ Configurable Table Prefix: Custom prefix setting (table_prefix => 'zk_') for all database tables.
• 📊 Built-In Admin UI Dashboard: Glassmorphism web dashboard at /zkteco/admin to monitor connected devices and logs.

📦 Installation

Step 1: Install Package via Composer

Or for local development in your main Laravel composer.json:

Step 2: Publish Configuration & Migrations

⚙️ Environment Configuration (.env)

🔒 Protecting the Admin UI with Auth Middleware

You can secure the /zkteco/admin dashboard behind Laravel's standard auth middleware or custom authorization guards by updating config/zkteco-push.php:

Or via environment variable:

⚡ Using the ZkTecoPush Facade

Array Payload Syntax:

Fluent Device Chaining Syntax:

🎧 Detailed Examples of Available Laravel Events

The package automatically fires native Laravel events whenever connected biometric machines push data or execute commands. You can attach queued listeners or event callbacks in your AppServiceProvider or EventServiceProvider.

1. AttendancePushed Event

Fired in real time whenever an employee scans a fingerprint, face, palm, RFID card, or enters a password on any ZKTeco terminal.

Listener Callback Example:

Dedicated Queued Listener Class Example (app/Listeners/ProcessZkTecoPunch.php):

2. DeviceHeartbeat Event

Fired whenever a ZKTeco biometric device connects to the server, completes an initial ADMS handshake, or sends a periodic ping.

Listener Callback Example:

3. CommandExecuted Event

Fired when a hardware machine finishes executing a queued command (such as user creation, user deletion, delayed deletion, device reboot, or log clearance).

Listener Callback Example:

🏭 Production-Ready Integration Guide

Below is a complete, production-grade implementation pattern for real-world Laravel applications. Reference file: ProductionLaravelExample.php.

1. Queued Event Listener (app/Listeners/SyncBiometricAttendanceListener.php)

2. Employee Management Controller (app/Http/Controllers/BiometricEmployeeManagementController.php)

🧪 Running Tests

Run the PHPUnit test suite using Composer:

Or run PHPUnit directly: