How I Reverse-Engineered ZKTeco’s Binary Protocol in Pure PHP 8 to Build a Direct Hardware Attendance Writer

说明与用途

纯 PHP 8 库实现与 ZKTeco 生物识别时钟的双向通信，支持直接写入设备记录，并可无缝集成 Laravel，无需外部 C++ SDK。

问题

Existing ZKTeco biometric clock integrations rely on abandoned Packagist packages that are UDP‑only, fail on PHP 8.x, and cannot write attendance back to the device.

结果

The library enables reliable, bidirectional communication with ZKTeco devices over TCP, allows writing attendance records directly to hardware, and integrates seamlessly with Laravel applications without external C++ SDKs.

工作流

• 1. Install the library via Composer.
• 2. Instantiate ZKTeco with PROTOCOL_AUTO to use TCP first, then UDP.
• 3. Use markAttendance() to write a punch directly to the device, triggering voice and LCD feedback.
• 4. In Laravel, call ZKTeco::getAttendanceStructured() to sync logs to the database.
• 5. Run CI tests across PHP 8.0–8.4 to ensure compatibility.

证据

Most existing Packagist packages are 6 to 10 years old abandonware.

来源

They are strictly UDP-only—meaning when deployed across remote offices over WAN routers or NAT firewalls, UDP packets drop silently without error messages.

来源

None of them support writing attendance back to the machine

来源

We implemented a Dual-Protocol Engine with automatic fallback

来源

By packaging this buffer with CMD_SET_DATA (3001) and immediately dispatching CMD_REFRESHDATA (1013) with CMD_VOICE (1014), the machine not only permanently logs the check-in/out record inside its memory—it also plays the hardware voice: "Thank you"!

来源