PHP 8 中以純 Socket 連接 ZKTeco 生物識別裝置,無需 Windows DLL
Connecting Physical Biometric Devices in PHP 8: Pure Sockets Without Windows DLLs
taha-rafi/php-zkteco v2.1 為 PHP 8.x 和 Laravel 提供原生 Socket 通訊,可直接連接 ZKTeco 生物識別裝置,無需 Windows DLL、外部 C 擴充或中介服務。套件支援 TCP/UDP 通訊、自動協議回退、CommKey 驗證,以及直接寫入和選擇性刪除考勤記錄。
The 15-Year Legacy Problem in PHP Biometric Integration
For more than a decade, integrating physical biometric hardware (specifically ZKTeco time-and-attendance and access control terminals) into PHP web applications was notoriously painful.
Historically, developers were forced into one of three brittle workarounds:
- Running a dedicated 32-bit Windows Server virtual machine executing the vendor COM component (
zkemkeeper.dll), querying it via PHPCOMextensions or external VB/C# scripts. - Deploying Python or Node.js intermediate middleware daemons to communicate with hardware and push data into MySQL via REST or database polling.
- Using unmaintained PHP 5.x packages written in 2012 that relied on raw UDP sockets without stream framing, dropping packets across VLANs, failing silently on network partitions, and throwing fatal errors on PHP 8.1+ due to deprecated dynamic properties and type mismatches.
With the release of PHP 8.4, userland network socket capabilities in PHP are mature, high-performance, and resilient. The open-source package taha-rafi/php-zkteco implements a pure native socket communication engine for ZKTeco terminals that requires zero external C extensions, zero Windows DLLs, and zero middleware services.
taha-rafi
/
php-zkteco
🚀 Pure Native PHP 8.x ZKTeco Biometric Library: Direct Hardware ATT_LOG Writer (CMD_SET_DATA 3001), Selective Deletion, Dual TCP/UDP Socket Engine, CommKey Auth, Cloud POST Sync, ADMS Push Server & HMAC-SHA256 Webhooks
🚀 php-zkteco v2.1 (Pure Native PHP 8.x & Laravel ZKTeco TCP/UDP, Direct Hardware ATT_LOG Writer, Cloud POST Sync, ADMS Push & Webhook Engine)
A next-generation, standalone Pure Native PHP 8.x & Laravel communication, Direct Hardware Attendance Writer, Cloud POST Sync, ADMS Push Server, and Real-Time Webhook library for ZKTeco Biometric Time & Attendance Devices (TX628, iClock, K-Series, uFace, SpeedFace, MB-Series, ZMM-Series).
Unlike legacy PHP ZKTeco packages that only support unreliable UDP polling and only GET raw arrays, php-zkteco v2.1 introduces:
-
Direct Hardware Attendance Writing (
CMD_SET_DATA = 3001): The first and only ZKTeco library capable of writing attendance punches (Check-In/Check-Out) directly into the physical ZKTeco machine's internalATT_LOGmemory (ZKDB.db), plus selective attendance deletion by time range (CMD_TIME_ATTLOG_DELE = 10005). -
Dual-Protocol Socket Engine (
auto,tcp,udp): Full native ZKTeco TCP framing (\x50\x50\x82\x7d) with…
Core Socket Architecture: TCP Framing and Dual-Protocol Fallback
Standard ZKTeco terminal firmware communicates using a proprietary binary packet protocol across port 4370. Older legacy libraries only supported UDP. While UDP is lightweight, corporate enterprise networks, firewalls, and multi-subnet VLANs regularly drop UDP packets under high traffic or cross-switch hops.
The modern taha-rafi/php-zkteco engine solves this by implementing dual-protocol negotiation with native TCP stream encapsulation.
TCP Stream Framing
TCP is a byte-stream protocol without inherent packet boundaries. To prevent packet fragmentation or stream coalescing, the package encapsulates standard ZKTeco binary commands inside an 8-byte framing envelope:
- 4-Byte Magic Header:
\x50\x50\x82\x7d(ASCIIPP\x82}) - 4-Byte Little-Endian Payload Length
- Raw ZK binary payload (Header, Checksum, Session ID, Reply Code, Command Data)
When initialized with Constants::PROTOCOL_AUTO, the driver establishes a TCP socket handshake first. If the physical machine operates an older firmware revision lacking TCP daemon support, it automatically catches the timeout and falls back to UDP without crashing the parent process.
Native CommKey Authentication
When a terminal is protected by a communication password (CommKey), unauthenticated requests return reply code CMD_ACK_UNAUTH (2005). Legacy libraries failed at this point. The modern engine reverses the firmware MakeKey algorithm: it takes the numeric communication key and session tick count, executes 32-bit arithmetic bitwise scrambling, and dispatches CMD_AUTH (1102) to unlock privileged device operations.
Complete Standalone Implementation
Let us construct a production-ready script that connects to a physical device, gathers hardware diagnostic telemetry, synchronizes system clocks, retrieves attendance records, and performs safe selective memory maintenance.
1. Installation
Install the package via Composer:
composer require taha-rafi/php-zkteco
Ensure your PHP environment has the ext-sockets and ext-json extensions enabled in php.ini.
2. Device Diagnostics, Clock Synchronization, and Attendance Retrieval
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use TahaRafiZKTeco\ZKTeco;
use TahaRafi\ZKTeco\Constants;
/**
* Production script demonstrating device connection, diagnostics,
* attendance retrieval, selective cleanup, and live event monitoring.
*/
$deviceIp = '192.168.1.201';
$devicePort = 4370;
$commKey = 0; // Communication password configured on terminal
$protocol = Constants::PROTOCOL_AUTO; // Attempts TCP first, falls back to UDP
$timeout = 10.0; // Socket connection timeout in seconds
echo "[INFO] Initializing ZKTeco client for {$deviceIp}:{$devicePort}...\n";
$zk = new ZKTeco($deviceIp, $devicePort, $commKey, $protocol, $timeout);
// Connection retry loop
$maxRetries = 3;
$connected = false;
for ($attempt = 1; $attempt <= $maxRetries; $attempt++) {
echo "[INFO] Connection attempt {$attempt}/{$maxRetries}...\n";
if ($zk->connect()) {
$connected = true;
break;
}
if ($attempt < $maxRetries) {
usleep(500000); // 500ms backoff
}
}
if (!$connected) {
echo "[ERROR] Failed to connect to biometric device at {$deviceIp}:{$devicePort}.\n";
exit(1);
}
try {
// 1. Diagnostics and Device Metadata
echo "\n--- Device Diagnostics ---\n";
echo "Device Name: " . $zk->getDeviceName() . "\n";
echo "Serial Number: " . $zk->getSerialNumber() . "\n";
echo "Platform: " . $zk->getPlatform() . "\n";
echo "Firmware Ver: " . $zk->getVersion() . "\n";
echo "OS Version: " . $zk->getOSVersion() . "\n";
echo "PIN Width: " . $zk->getPinWidth() . " digits\n";
echo "Device Time: " . $zk->getTime() . "\n";
// Synchronize device clock if drifted by more than 5 seconds
$deviceTimestamp = strtotime($zk->getTime());
$serverTimestamp = time();
if (abs($serverTimestamp - $deviceTimestamp) > 5) {
echo "[INFO] Clock drift detected (" . ($serverTimestamp - $deviceTimestamp) . "s). Synchronizing clock...\n";
$zk->setTime(date('Y-m-d H:i:s', $serverTimestamp));
echo "[INFO] Device clock synchronized to: " . $zk->getTime() . "\n";
}
// 2. Fetch Enrolled Users
echo "\n--- Enrolled Users ---\n";
$users = $zk->getUser();
echo "Total Enrolled Users: " . count($users) . "\n";
foreach (array_slice($users, 0, 5) as $user) {
echo sprintf(
" UID: %-4d | ID: %-8s | Name: %-15s | Role: %d\n",
$user['uid'],
$user['userid'],
$user['name'],
$user['role']
);
}
// 3. Retrieve Attendance Records
echo "\n--- Attendance Punch Logs ---\n";
$attendanceLogs = $zk->getAttendance();
echo "Total Punch Records in Terminal: " . count($attendanceLogs) . "\n";
$stateLabels = [
Constants::ATT_STATE_CHECK_IN => 'Check-In',
Constants::ATT_STATE_CHECK_OUT => 'Check-Out',
Constants::ATT_STATE_BREAK_OUT => 'Break-Out',
Constants::ATT_STATE_BREAK_IN => 'Break-In',
Constants::ATT_STATE_OVERTIME_IN => 'Overtime-In',
Constants::ATT_STATE_OVERTIME_OUT => 'Overtime-Out',
];
$verifyLabels = [
Constants::VERIFY_PASSWORD => 'Password',
Constants::VERIFY_FINGERPRINT => 'Fingerprint',
Constants::VERIFY_CARD => 'RFID Card',
];
$recentPunches = array_slice($attendanceLogs, -10);
foreach ($recentPunches as $punch) {
$stateText = $stateLabels[$punch['state']] ?? "State({$punch['state']})";
$verifyText = $verifyLabels[$punch['type']] ?? "Type({$punch['type']})";
echo sprintf(
" User ID: %-8s | Timestamp: %s | State: %-12s | Verify: %s\n",
$punch['id'],
$punch['timestamp'],
$stateText,
$verifyText
);
}
// 4. Safe Selective Log Maintenance
// Do NOT call clearAttendance() which completely purges hardware memory!
// Instead, prune records older than 30 days using CMD_TIMEPOINT_ATTLOG_DELE.
$purgeThreshold = date('Y-m-d 00:00:00', strtotime('-30 days'));
echo "\n[MAINTENANCE] Safely pruning attendance records older than {$purgeThreshold}...\n";
$pruneSuccess = $zk->deleteAttendanceBefore($purgeThreshold);
echo $pruneSuccess
? "[MAINTENANCE] Selective purge acknowledged by terminal.\n"
: "[WARNING] Terminal did not acknowledge selective purge.\n";
} catch (\Throwable $e) {
echo "[EXCEPTION] Communication error: " . $e->getMessage() . "\n";
} finally {
$zk->disconnect();
echo "\n[INFO] Device connection terminated cleanly.\n";
}
Real-Time Event Streaming: Subscribing to Live Punches
In addition to polling, php-zkteco allows your PHP process to register as an event listener directly on the device using command CMD_REG_EVENT (500). When an employee clocks in with fingerprint, facial recognition, or badge, the device immediately dispatches a real-time UDP packet to your listening socket.
<?php
declare(strict_types=1);
require_once __DIR__ . '/vendor/autoload.php';
use TahaRafi\ZKTeco\ZKTeco;
use TahaRafi\ZKTeco\Constants;
$zk = new ZKTeco('192.168.1.201', 4370);
if (!$zk->connect()) {
die("Connection failed\n");
}
echo "Subscribed to live biometric attendance events. Press Ctrl+C to exit...\n";
// Register specifically for attendance punch events (EF_ATTLOG)
$zk->listenRealTime(
onEvent: function (array $event) {
echo sprintf(
"[%s] Live Punch -> User PIN: %s | State: %d | Punch Time: %s\n",
date('Y-m-d H:i:s'),
$event['user_id'] ?? 'Unknown',
$event['state'] ?? 0,
$event['timestamp'] ?? date('Y-m-d H:i:s')
);
},
eventMask: Constants::EF_ATTLOG
);
$zk->disconnect();
Conclusion
By shifting from legacy 32-bit Windows binaries to a native PHP 8 socket engine, engineering teams can containerize attendance services in Docker, deploy onto lightweight Alpine Linux instances, and achieve sub-second synchronization with physical hardware across standard local networks.
來源:DEV Community · dev.to
