In attendance management system projects, one of the biggest challenges was reliably and stably integrating a fingerprint device with a PHP Laravel-based system.
I tried libraries… I got tired. Looked into SDKs… gave up.
But in the end…
I found the solution! I'm sharing my full experience below 👇
The Challenge: Issues with Traditional Libraries
For example:
I used the library mehedijaman/laravel-zkteco, but it failed when connecting externally (on a VPS).
https://github.com/mehedijaman/laravel-zkteco
Reason:
The device operates on a local network (192.101.x.x), while the system is hosted on a remote server.
ZKTeco SDK tools (work only locally)
Solutions that rely on UDP/Port 4370
All of them work locally (localhost), but they:
Don't work on external hosting (WHM/VPS)
Don’t support some ZKTeco models
Require apps to always run on the same network
The Best & Most Reliable Solution:
ZKBioTime + Port Forwarding + Laravel API Integration
After deep research, I discovered the only trusted solution 🔐 is using ZKBioTime API by ZKTeco.
Device Used and Connectivity Method:
I used the ZKTeco SpeedFace V5L, an advanced device that supports both facial recognition and fingerprint scanning.
Connected via Wi-Fi:
Instead of connecting the device using a LAN cable, I opted for a wireless connection to reduce wiring and simplify the infrastructure.
I made sure that:
The device is connected to the same Wi-Fi network as the local server
The device IP is static so it doesn’t change on every reboot
The Cloud Server settings on the device are configured to send data
Important Note:
Even though the device is on Wi-Fi, it must be in the same network as ZKBioTime. Otherwise, synchronization will fail.
Steps for Successful Integration:
1️⃣ Install mehedijaman/laravel-zkteco library in Laravel
2️⃣ Update connection config:
Located at: config/zkteco.php
3️⃣ Install the official ZKBioTime software on a local server in the same network
4️⃣ Assign a Static IP to the ZKTeco device
5️⃣ Update ZKTeco Cloud Server Settings:
Server Address = 00.000.00. (Your Laravel server IP)
Port = 4370
6️⃣ Enable Port Forwarding on your router:
Forward port 4370 to the device's local IP 00.000.00
7️⃣ Open the port in the firewall using iptables + firewalld on the server
8️⃣ Connect ZKBioTime with the device and make sure the logs appear live
9️⃣ Test ZKBioTime API using Laravel
Handling Attendance Data:
ZKBioTime doesn’t send "in" or "out" flags — it only sends punch timestamps.
So I developed custom logic inside Laravel:
First punch of the day = “Clock In”
Last punch before shift end = “Clock Out”
With validation of time and employee status
Smart Syncing (e.g. Every 10 Minutes):
I created a Scheduled Job in Laravel
It fetches punches from /iclock/api/transactions/
(Path: App\Console\Kernel.php)
Stores them in the attendances table with logic to identify Clock In/Out
Then I activated a Cron Job on the server
Every 10 minutes, attendance data updates automatically ✅
Frequently Asked Questions:
Does the device need Internet?
Yes, and it must be on the same network as ZKBioTime.
Does this work with all ZKTeco models?
Yes, as long as ZKBioTime supports the device, Laravel just reads from the API.
Is ZKBioTime considered middleware?
Yes — it's an official API gateway that lets you communicate with the device without SDKs or USB connections.
Can the router change the IP?
Yes — use a Static IP and check DHCP Lease settings.
Can this work with a remote server?
Yes — via Port Forwarding and open ports.
Do I need an internal/local server?
Yes — to install ZKBioTime, which must be on the same network as the device.
The Final Result:
✅ A fully working, stable attendance system
🔁 Auto-sync every 10 minutes
🕒 Accurate clock-in and clock-out times
📊 Real-time & accurate data
📅 100% integrated with shifts, leaves, and reporting
If you're a developer or business owner facing the same challenge — this setup is the solution.
And if you need help integrating your device, DM me or drop a comment ✌️