Download the PHP package msaied/zkteco without Composer

zkteco

A PHP client for ZKTeco biometric attendance devices, with an optional, auto-discovered Laravel bridge. It speaks both directions of the wire:

• the TCP socket protocol (a port of pyzk) — you dial the device on port 4370 to read users, attendance, and templates, stream live punches, and run interactive fingerprint enrollment; and
• the ADMS push protocol — the device dials you over HTTP, uploading attendance, photos, biometric data, and audit logs while polling for typed commands you queue back to it.

The socket protocol is verified end-to-end against real hardware (read, write, template upload, realtime streaming, and interactive enrollment all work — see Tested hardware). The ADMS read path is fully implemented behind a trust-but-gate admission model; some outbound ADMS command layouts are still provisional (see Limitations).

Two ways to talk to a device

You can use either or both. The two paths share the same domain (value objects & enums): a punch arriving over the socket stream and one pushed over ADMS both surface as the same AttendanceRecord and the same PunchReceived event.

Features

• Agnostic core in src/TCP and src/ADMS with no illuminate/* dependency — the binary socket protocol and the ADMS HTTP protocol are both framework-neutral.
• Grouped sub-service API reached from a single Device entry point rather than one god class: $device->users(), ->attendance(), ->templates(), ->control(), ->info(), ->realtime().
• Managed session scope that disables the device for the duration of the work and guarantees it is re-enabled and disconnected even when the body throws.
• Immutable value objects (User, AttendanceRecord, Template, OperationLog, AttendancePhoto, BiometricTemplate) and typed enums (Privilege, PunchState, VerifyMode, OperationType) — no loose arrays.
• Realtime punch streaming via a PHP Generator.
• Interactive fingerprint enrollment driven from your code.
• ADMS push endpoints that ingest attendance, attendance photos, biometric templates, user syncs, and audit logs — with a trust-but-gate device admission model (strict allowlist or accept-then-approve).
• Typed outbound ADMS commands — queue reboot, syncTime, upsertUser, pushTemplate, etc. for a device to run on its next poll; outcomes arrive as events.
• Optional Laravel bridge: facade, config, three artisan commands, a set of events, and Eloquent models — auto-discovered when installed inside a Laravel app, dormant otherwise.

Requirements

• PHP 8.3+
• The Laravel bridge requires Laravel 11, 12, or 13 (provided by the host app; not a hard dependency of the package).

Installation

The Laravel bridge is auto-discovered. To customise connections, publish the config:

Part 1 — Socket client (you dial the device)

Quick start

Connecting

The Device constructor only describes the connection — no socket is opened until you connect.

Non-ASCII names (Arabic, Chinese, …)

The device stores user names in a fixed byte field and renders them using its own configured language codepage, not UTF-8. Writing UTF-8 names to a device set to another codepage shows mojibake on the panel even though the device can display the script. Set nameEncoding to the device's codepage so names are converted on write and back on read:

Common values: Windows-1256 (Arabic), GB2312 (Chinese), Windows-1251 (Cyrillic). Leave it UTF-8 for ASCII-only or Unicode firmware. Encoding is done with iconv, so any encoding it supports is valid.

There are two ways to scope a connection:

Managed scope (preferred) — session() connects, disables the device while the callback runs, then re-enables and disconnects in a finally, even on exceptions. Use this for ordinary read/write work:

Explicit lifecycle — connect() / disconnect() for long-lived work such as realtime listening or interactive enrollment, where you do not want the device disabled:

Note: session() disables the device, which also locks the fingerprint sensor. Use connect()/disconnect() for realtime()->live() and templates()->enroll().

Working with the device

Users

uid is the device-local record slot (1..N); userId is the human-facing employee number string. They are distinct and must never be conflated.

Attendance

Templates & fingerprint enrollment

A Template is one biometric enrollment belonging to a user; a user may have several. data is the raw, opaque, firmware-specific template payload — this package does not interpret it.

Interactive enrollment triggers the device's fingerprint sensor and blocks while the person presses their finger (typically 3×). It returns true on a successful capture. Run it on an explicit connection, not inside session() (which would disable the sensor):

Because the enroll event stream is firmware-specific (see Tested hardware), enroll() accepts an optional $trace closure — fn (string $event, array $context) — invoked at each step of the handshake: the CMD_STARTENROLL payload and reply, every event packet (with its raw hex), the parsed completion, and the trailing records drained afterwards. On a terminal whose firmware differs from the verified one, pass it to record exactly what the device returns instead of guessing:

The fingerIndex (0–9) is the device's finger slot, used by enroll(), delete() and Template. It runs from the left pinky across to the right pinky, with the thumbs meeting in the middle — matching the device's on-screen Enroll layout:

Face enrollment is not supported over the socket protocol — see Limitations.

Device info

Device control

Realtime punches

live() registers for live attendance events and returns a Generator that yields an AttendanceRecord per punch, or null on an idle heartbeat (so the loop never blocks forever). Run it on an explicit connection:

Part 2 — ADMS push (the device dials you)

ADMS is ZKTeco's device-initiated HTTP protocol — the inverse of the socket client. Instead of you dialing the device, the device is configured with your server's address and pushes to it: it handshakes, uploads attendance (and, on capable firmware, attendance photos, biometric templates, and audit logs), and polls for commands you've queued. This is the right fit for always-on fleets, devices behind NAT, or any case where you want push-on-punch without holding an open socket.

The package ships the whole HTTP surface as routes plus a controller; you wire your app in through events (for data the device uploads) and the ZkTeco::push() fluent API (for commands you send back).

Enabling the endpoints

The ADMS routes stay dormant by default so an app that only uses the socket client never exposes a push surface. Turn them on in config/zkteco.php (or via env):

With enabled = true, the bridge mounts these routes under the prefix (default iclock), which is the path ZKTeco firmware expects:

On the device, point Comm → Cloud Server / ADMS Setup at your server's address and port (disable "Enable Domain Name" if you're using an IP). Deploy behind HTTPS — TLS is not terminated in-package.

You also need the device/command tables (see Persistence):

Device admission: trust but gate

Recording a device is never the same as trusting its data. Admission has two postures, set by auto_register:

• Strict (auto_register = false, the default). Only serials in allowed_serials are admitted, and they are approved on sight. Every other device is rejected and never recorded.
• Open (auto_register = true). Any device may dial in and is recorded, but an unknown one lands as pending — visible, yet its attendance is held (the device is told to retry) until you approve it. Serials in allowed_serials are still approved on sight. This is "accept all, but choose which to keep".

A device is always in one of three states — pending, approved, or blocked (ZkTeco\ADMS\Registry\DeviceStatus).

Approving devices

Two artisan commands manage the fleet:

You can also approve programmatically through the registry contract (ZkTeco\ADMS\Registry\DeviceRegistry), resolvable from the container:

Reacting to uploaded data

Each kind of upload is parsed into a value object and dispatched as a Laravel event carrying the originating serial number as $connection. Listen to the ones you care about:

PunchReceived is the same event the socket listener fires (see zkteco:listen), so a single listener can absorb punches from both transports — telling them apart by $connection (a configured connection name from the socket path, a device serial from the ADMS path) if you need to.

Attendance photos and biometric blobs are handed to you as opaque bytes — the package never persists them for you:

Sending commands back to a device

ADMS is poll-based, so commands are asynchronous: you queue a typed command, the device drains it on its next getrequest poll, and the outcome arrives later as a CommandAcknowledged event. ZkTeco::push($serial) returns a fluent builder over an already-registered device (it throws CommandException::unknownDevice for an unknown serial):

Each call returns a QueuedCommand handle (its id correlates the later acknowledgement). The full set:

Then react to outcomes:

Wire-format caveat: the power, SET OPTIONS, and data-write command layouts are provisional and not yet pinned against real hardware (the attendance/registration read path is). See Limitations.

Persistence (models & migrations)

These migrations are optional — the package never runs them for you. The service provider only publishes them; it does not auto-load them, so they exist only if you deliberately publish and migrate. Publishing zkteco-migrations copies three tables into your app, each with a matching Eloquent model under ZkTeco\Laravel\Models:

When do you actually need them?

zkteco_devices and zkteco_commands back the ADMS registry and command queue, so they are required only once you enable the push endpoints with the built-in Eloquent persistence. Bind your own DeviceRegistry / CommandQueue implementations (in-memory, Redis, …) and you can skip the tables entirely.

zkteco_attendance is always optional — it's an opt-in convenience store for your own listeners, and the package never writes to it itself.

Using the ADMS core without Laravel

The ADMS core (ZkTeco\ADMS) is framework-neutral. You can mount it on any HTTP stack by feeding requests to PushRouter and implementing the sink interfaces (AttendanceSink, AttendancePhotoSink, BiometricSink, UserSink, OperationLogSink) and the DeviceRegistry / CommandQueue contracts yourself. A runnable, dependency-free demo lives in examples/:

Value objects & enums

• Verify mode is how identity was confirmed (pyzk's confusingly named status field).
• Punch state is what the punch means (pyzk's punch field).

The socket path fills AttendanceRecord->uid (the device slot); the ADMS path leaves it null and keys on userId, because the device doesn't send its internal slot over push.

Laravel integration reference

When installed inside a Laravel app the ZkTecoServiceProvider is auto-discovered. Configure socket connections in config/zkteco.php:

Resolve a configured socket Device through the facade:

Streaming socket punches (zkteco:listen)

The socket realtime stream is a blocking, infinite loop, so it needs its own long-running process — you can't run it inside an HTTP request. The zkteco:listen command is that daemon: it holds the connection open and fires a PunchReceived event for every punch.

Run it under a supervisor (Horizon, systemd, or supervisord) so it restarts after a dropped connection; it traps SIGINT/SIGTERM for graceful shutdown.

Reach for it only when you need to react the instant someone punches and you're dialing the device (socket path). If the device pushes to you over ADMS, you already get PunchReceived with no daemon. If periodic syncing is enough, schedule a job that calls attendance()->all() instead.

Artisan commands

Error handling

All failures derive from ZkTeco\Exceptions\ZkException (each carries a typed ErrorCode and a context array):

• ConnectionException — could not connect/authenticate, device not connected, or an unsupported transport (e.g. UDP).
• NetworkException — socket-level read/write failures and timeouts.
• ResponseException — the device received the command but rejected it.
• CommandException — an ADMS command targeted an unknown device, or the device's protocol generation can't render that command.

Localizing error messages

Every exception pairs a human-readable English getMessage() (for logs and developers) with two machine-stable fields that drive translation:

• $e->errorCode — a ZkTeco\Exceptions\ErrorCode enum whose backing string (connection_failed, timeout, …) is the translation key. These values are part of the public contract and never change.
• $e->context — an array of the values that shaped the message (host, port, command, …), used as the placeholder bindings.

In a Laravel app the bridge resolves each code through zkteco::errors.<code>, passing context as the replacement bindings and falling back to the English getMessage() when no translation exists for the active locale. Any ZkException reaching the handler on a JSON request is rendered as { "message": "<localised>", "error_code": "<code>" } with HTTP 503.

To translate them:

This copies the catalogue to lang/vendor/zkteco/en/errors.php. Add a sibling locale folder using the same keys (the placeholders are filled from each exception's context):

Set the app locale and the JSON message switches accordingly. Outside Laravel, map errorCode->value to your own catalogue — the codes are stable, so no parsing of message strings is required.

The full list of keys lives in lang/en/errors.php, one per ErrorCode case.

Tested hardware

The socket protocol is verified end-to-end against a physical unit:

Verified on this device: handshake + metadata read, buffered user and attendance reads, clock set/read, user create/read/delete, fingerprint template upload (byte-for-byte round-trip), realtime event registration, and interactive fingerprint capture via CMD_STARTENROLL.

The enrollment event stream is firmware-specific and differs from pyzk's published sequence; enroll() was written against this firmware. Only the success path has been observed so far — failure result codes (e.g. duplicate finger) are not yet characterised.

A gated integration suite exercises all of the above against real hardware — see Testing.

Compatibility notes

The package targets the generic ZK protocol, not one firmware build, so other ZKTeco terminals are expected to interoperate. The following newer build has been checked at the protocol level but has not yet had a full end-to-end hardware run, so it is listed separately from the verified unit above:

What this implies per path:

• Socket read/write/clock/control/realtime — same model as the verified unit, over the same generic ZK6 wire format; expected to work unchanged.
• Fingerprint enroll() — the event stream was only ever observed on the 6.60 unit, so it is unconfirmed here. Use the $trace hook (see enrollment) to capture the real sequence before relying on it.
• ADMS push (Push Service 2.0.30S) — the device's pushver resolves to the PushV2 generation, so it is served by the full PUSH-SDK read path (attendance, photos, biometric templates, user syncs, audit logs). The outbound command and config/registry layouts remain provisional (see Limitations).

Limitations

• No remote face enrollment over the socket protocol. Even on a device with a working face engine, the legacy binary protocol exposes no network path to capture or enroll a face. CMD_STARTENROLL drives only the fingerprint sensor, and buffered reads of face templates are rejected by the firmware. Faces must be enrolled at the device itself, via its on-screen menu. Fingerprints, by contrast, are network-enrollable via templates()->enroll(). (Over ADMS, capable firmware can push existing biometric templates — including faces — to you as BiometricReceived events, but that's the device uploading what it already has, not remote capture.)
• Socket transport is TCP only. useUdp: true (config 'udp' => true) throws ConnectionException::udpUnsupported(). A UDP transport is not implemented yet.
• Some ADMS outbound commands are provisional. The attendance/photo/biodata read path and device registration are implemented and gated. The write path — power, SET OPTIONS (e.g. syncTime), and data writes (upsertUser, deleteUser, pushTemplate) — rides on best-effort wire layouts that have not yet been pinned against real hardware.

Testing

The unit and Laravel suites use a fake transport and need no hardware. A separate Integration suite talks to a real device and is skipped unless ZKTECO_DEVICE_HOST is set:

Optional overrides: ZKTECO_DEVICE_COMM_KEY (default 0) and ZKTECO_DEVICE_TIMEOUT (seconds, default 5). The interactive enrollment test is additionally gated behind ZKTECO_ENROLL_INTERACTIVE=1 because it needs a person to physically press a finger on the sensor. The write-path tests are reversible by design (throwaway probe users that are cleaned up afterwards).

Design

Architecture decisions are recorded as ADRs in docs/adr/, and the ubiquitous language lives in CONTEXT.md.

License

MIT.