- How do I install and configure the taha-rafi/php-zkteco package in Laravel?
- Install it with composer require taha-rafi/php-zkteco. Laravel 8 through 12 auto-discovers the service provider and registers the ZKTeco facade. Publish the config with php artisan vendor:publish to create config/zkteco.php, then set your device IP, port (default 4370), and CommKey. Keep those values in environment variables rather than committing them to source control.
- Which Laravel versions does php-zkteco support?
- The package supports Laravel 8, 9, 10, 11, and 12 and uses package auto-discovery, so you do not need to register the provider manually. The provider binds the ZKTeco facade and merges the package configuration into config/zkteco.php. If you disable auto-discovery, register the package service provider in config/app.php yourself. On Laravel versions older than 8, expect to add your own wiring and test thoroughly.
- How do I connect to a ZKTeco device on port 4370 and read attendance logs?
- Resolve the ZKTeco facade, point it at the device IP and port 4370, and call the log-reading method to pull attendance records. The library speaks the vendor binary protocol over TCP or UDP directly, so no vendor SDK is needed on the device. Because socket I/O is blocking, run the read inside a queued job instead of a web request. Persist and deduplicate records by user ID and timestamp before storing them in your own schema.
- What is CommKey authentication and how do I configure it in config/zkteco.php?
- CommKey is the vendor's 4-byte key used in a challenge-response handshake and is configured per device. Set it in config/zkteco.php or pass it when connecting to the terminal. It is obfuscation rather than encryption: it does not encrypt biometric templates or attendance data in transit. Treat it as a minimum control and rely on VLAN segmentation and firewall ACLs to restrict which hosts can reach port 4370.
- Can ZKTeco devices push attendance data to my Laravel app instead of me polling them?
- Yes. The package includes an ADMS push server and Cloud POST sync so devices can initiate the connection and send attendance data to your Laravel application. This is usually the better production pattern because it tolerates NAT and avoids polling every terminal on a schedule. You must add your own authentication, replay protection, and rate limiting on the receiving endpoint, since it becomes an internet or LAN-facing route. HMAC-SHA256 webhooks are supported for verifying pushed payloads.
- Is it safe to use the ATT_LOG writer and selective deletion features in production?
- Treat these as privileged operations. The ATT_LOG writer (CMD_SET_DATA 3001) and selective deletion (CMD_TIME_ATTLOG_DELE 10005) mutate device state, bypass device-side business rules, and deletion is not reversible. Gate them behind config flags, RBAC, an approval workflow, and an immutable audit log recording who did what on which device. Keep them out of default scheduled jobs and take a snapshot before any destructive call.
- How do I test ZKTeco integration code in Laravel without real hardware?
- Because all device I/O goes through the ZKTeco facade, you can bind a fake implementation in the container during tests and assert that your service layer calls the right methods with the right DTOs. That covers your application logic without hardware. It does not prove firmware compatibility with a specific terminal model, so keep a separate integration environment with real devices for smoke tests. Never point automated test suites at production terminals.
- Why do my ZKTeco socket calls block or time out during web requests?
- Socket calls are synchronous and blocking, and per-device latency varies, so a slow or offline terminal can stall a PHP-FPM worker and exhaust your pool. Run every read and write through a queue worker with explicit connection and read timeouts plus retry and backoff. Add circuit breaking so one unreachable device does not back up the whole queue. Never call device methods directly from a controller.
- Should I use TCP or UDP to talk to ZKTeco biometric devices?
- The library ships a dual TCP and UDP socket engine, and both speak the device's binary protocol on port 4370. UDP is lighter and common for quick commands but offers no delivery guarantee, while TCP gives ordered delivery and is generally preferable for larger attendance log reads. Whichever you choose, the Laravel host must be reachable from the device on the same LAN segment or VPN. Serverless and PaaS environments without private network egress will not work.
- What are the alternatives to php-zkteco for Laravel projects?
- Alternatives include implementing the ZKTeco protocol yourself, wrapping a Python library such as pyzk behind a small relay service, or using vendor middleware. php-zkteco's advantage is that it is native PHP 8.x with a Laravel service provider and facade, so it drops into your app without a sidecar. The tradeoff is a thin supply-chain footprint: it is effectively single-maintainer and publishes no formal deprecation or security disclosure policy. If that matters, plan to vendor the code or contribute upstream.