Weave Code
Laravel Zkteco Adms Core Laravel Package
dewanlab/laravel-zkteco-adms-core
Laravel package implementing the ZKTeco ADMS push protocol for biometric attendance terminals. It receives punches and heartbeats, syncs users and fingerprints, and stores records through configurable models and migrations, with ready-made routes and services for wiring ZKTeco devices into your app.
Comprehensive ZKTeco ADMS (Push Protocol) Core implementation for Laravel, supporting biometrics, door access control, and dynamic handshake state management.
Frequently asked questions about Laravel Zkteco Adms Core
- How do I install dewanlab/laravel-zkteco-adms-core in a Laravel application?
- Install it with Composer using composer require dewanlab/laravel-zkteco-adms-core, then publish and review the package configuration and migrations before running them. You need to expose the device-facing /iclock/* routes so ZKTeco terminals can reach your application over HTTP. Because this is a first release, verify the publish tags and route registration against the repository README rather than assuming defaults.
- Which Laravel and PHP versions does this package support?
- The package is described as Laravel-friendly with framework-agnostic core code, but the release notes do not list explicit Laravel, PHP, or database version constraints. Check the composer.json require block and the README compatibility section before committing, especially if you rely on composite unique indexes or JSON and date column handling. Test on your exact Laravel and database combination during a staging pilot before rolling out to production terminals.
- How does the ADMS protocol work with ZKTeco biometric devices in this package?
- ZKTeco terminals using ADMS push data to your server rather than being polled, so the package provides handlers for device registration, heartbeats, and data uploads. Incoming attendance and user records are parsed into structured DTOs, which keeps your controllers and models decoupled from raw device payloads. You then persist those DTOs through the storage contracts or your own Eloquent models.
- Are the /iclock/* routes secure, and do I need to add authentication?
- The release notes do not describe built-in authentication, request signing, or route middleware for the /iclock/* endpoints, so treat direct public exposure as high risk until you confirm otherwise. In practice you should front the routes with network restrictions such as a VPN, mTLS, IP allowlisting, or a WAF, and add custom middleware for device verification. Also plan how you map device serial numbers to tenants or sites so a device cannot spoof another terminal's identity.
- Can I store attendance and user records in my own database tables instead of the package defaults?
- Yes. The package ships pluggable storage contracts, which let you implement custom persistence instead of relying on the bundled models and migrations. This is useful when employee master data already lives in your application and you want device PINs mapped to existing user records. Review the migrations before publishing, and consider partitioning or indexing high-volume attendance rows for long-term performance.
- How do I push commands or sync users back to a ZKTeco device?
- The package includes a command queue for dispatching operations to devices, exposed through a fluent service API covering device scoping, employee CRUD, push, pull, sync, and remote controls. Command execution is asynchronous, so you must handle acknowledgment, timeout, retry, and reconciliation in your application logic. Listen for the CommandAcknowledged and CommandFailed events to track outcomes, and validate behavior against your specific firmware during the pilot.
- Can I use this package outside of Laravel or without Eloquent?
- The core library is framework-agnostic and does not couple itself to HTTP or Eloquent, so protocol handling, DTO parsing, and command queuing can be reused in other PHP contexts. Laravel bindings are provided as a convenience layer for service container resolution and route wiring. If you use a non-Laravel setup, expect to implement the storage contracts and your own transport layer.
- How should I handle biometric fingerprint templates (BIODATA) ingested from devices?
- BIODATA uploads can include multimodal biometric templates, which are sensitive personal data and usually fall under consent, retention, and access-control obligations. Encrypt templates at rest, restrict access to a narrow set of services, define a purge schedule, and confirm whether logs are redacted of personal data. Decide early whether you need to store templates at all, since many integrations only require attendance punches and user metadata.
- How can I test attendance ingestion and device events before going live?
- Start in a staging environment with a single lab terminal, confirm the handshake and ATTLOG ingestion, then map device PINs to application employees. The package emits events such as AttendanceLogged, UserSynchronized, CommandAcknowledged, and CommandFailed, which make it straightforward to assert domain effects in tests. Validate firmware behavior such as year-2000 clock drift and purge-before-update authorization stacking before enabling remote commands or destructive operations.
- Is this package production-ready, and what does it not cover?
- It is a strong protocol and core-layer fit, but it is not a complete device fleet management product: device onboarding, admin UI, tenant mapping, monitoring, and compliance controls remain your responsibility. The release notes flag medium-high technical risk driven by hardware and firmware variance, endpoint security, and sensitive data handling. Treat clearAttendanceLogs() as destructive and gate it behind acceptance criteria and backups, and clarify the API stability commitment after v1.0.0 before depending on it long term.
Weaver
How can I help you explore Laravel packages today?