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

Источник