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

Description and use

A pure PHP 8 library implements bidirectional communication with ZKTeco biometric clocks, enabling direct attendance writes to the device and seamless Laravel integration without external C++ SDKs.

Problem

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.

Outcome

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.

Workflow

• 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.

Evidence

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

Source

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

Source

None of them support writing attendance back to the machine

Source

We implemented a Dual-Protocol Engine with automatic fallback

Source

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"!

Source