Download the PHP package shaykhnazar/hikvision-isapi without Composer
On this page you can find all versions of the php package shaykhnazar/hikvision-isapi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download shaykhnazar/hikvision-isapi
More information about shaykhnazar/hikvision-isapi
Files in shaykhnazar/hikvision-isapi
Package hikvision-isapi
Short Description Laravel package for Hikvision ISAPI Face Recognition Terminals integration
License MIT
Informations about the package hikvision-isapi
Hikvision ISAPI for Laravel
Talk to Hikvision access-control terminals from Laravel: enrol people, push cards and faces, and read who went through which door.
Why this exists
A Hikvision terminal already holds everything an attendance or access system needs. Getting it out is the problem. ISAPI is XML over digest auth, sparsely documented, and inconsistent between models — and the parts that go wrong go wrong quietly:
- Paging. A search is a session: every page has to carry the same
searchID, and a device given a new one starts over and serves page one again. Nothing errors. You read plausible records and simply never reach the end of the list. This package holds one session for a whole walk and stops on what the device reports, not on a guess. - Totals. An event count comes back under
AcsEventTotalNumon some firmware and flat on others, sometimes as a string. Read one shape and you get a confident zero forever. - Faces in stack traces. PHP records call arguments in a trace unless
zend.exception_ignore_argssays otherwise; its compiled default is to record them and the officialphp:*-alpineimages set no ini at all. One logged trace publishes somebody's face. Everything this package owns is marked#[\SensitiveParameter]. - Model differences. Capacity limits, which endpoints exist, and the
subStatusCodebehind each refusal vary by model and firmware, and the documentation does not say.bin/hikvision-probeasks a device and writes the answers down.
Where the device's behaviour genuinely cannot be known without hardware, this package says so rather than guessing — see Device compatibility.
Features
- Real-Time Event Webhooks: Configure devices to push events to your API endpoints (v1.4.0+)
- Multi-Device Support: Manage unlimited Hikvision terminals simultaneously (v1.2.0+)
- Universal Device Providers: Load devices from config, database, API, or custom sources (v1.3.0+)
- Multi-Tenant Ready: Tenant-scoped device loading with runtime registration (v1.3.0+)
- Device Management: Get device info, status, and capabilities
- Person Management: Add, update, search, and delete persons
- Card Management: Handle access cards with full CRUD operations
- Face Recognition: Upload and manage face images with advanced search (v1.1.0+)
- Fingerprint Support: Register and manage fingerprints
- Access Control: Control doors remotely
- Event Handling: Search and subscribe to access events
- Event Notifications: HTTP webhooks for real-time event delivery (v1.4.0+)
- Clean Architecture: SOLID principles, dependency injection, contracts
- Type Safety: PHP 8.2+ features (enums, readonly properties)
- Performance: Built-in caching with configurable TTL (v1.3.0+)
- XML/JSON Support: Automatic format detection and conversion (v1.4.0+)
- Laravel 12/13: Supports Laravel 12.x and 13.x with service provider and facade
Table of Contents
- Device compatibility
- Requirements
- Installation
- Configuration
- Quick Start
- Probing a device
- Event Webhooks & Notifications
- Configure Webhook Endpoint
- Simple Webhook Setup
- Advanced Webhook Configuration
- Testing Webhooks
- Receiving Webhook Events
- Multi-Device Support
- Configuration from Config Files
- Loading Devices from Database
- Using Eloquent Models with CallbackProvider
- Multi-Tenant Support
- Runtime Device Registration
- Device Manager Methods
- Services Overview
- DTOs (Data Transfer Objects)
- Enums
- Error Handling
- Advanced Usage
- Testing
- Troubleshooting
- Security
- Contributing
- Changelog
Device compatibility
No model in this table has been confirmed yet. The package is written against the ISAPI specification and its own test suite; nobody has run it against a terminal and reported back. Saying so is more useful than an unsourced list — if this table claimed five models and was wrong about one, every row would stop being worth reading.
| Model | Firmware | Paging | Event total | Faces | Reported by |
|---|---|---|---|---|---|
| (nothing confirmed yet) |
Adding a row
Run the probe against your device and open a pull request with the result:
It is read-only — it never creates, updates or deletes anything, and the refusals it records are provoked with reads. It puts no employee name, card or number in the report; the person list is read for its shape only. Read the file before attaching it, as the tool tells you to.
The report answers every column above, including the two this package could not settle on its own: whether the device honours a search session across pages, and which key it returns an event total under.
Requirements
- PHP ^8.2
- Laravel / illuminate/support ^12.0 || ^13.0
- PHP ^8.3 is required when installing with Laravel 13
- Guzzle HTTP ^7.8
- ext-curl
- ext-json
- ext-simplexml
- ext-libxml
Installation
Install the package via Composer:
Publish the configuration file:
Configuration
Add these environment variables to your .env file:
Configuration File
The published config/hikvision.php supports multiple devices:
Probing a device
Terminals differ. Capacity limits, which endpoints exist, and the exact
subStatusCode behind each refusal all vary by model and firmware, and the
documentation does not say. bin/hikvision-probe asks a device directly and
writes the answers to a JSON file:
Two things it guarantees, both enforced by tests:
It never writes. Every request is a read, including the ones that provoke refusals. It is safe to run against a terminal a business depends on.
It never carries anybody out. The person list is read for its shape — row counts, paging fields, what a row's keys are called. Field names are kept, field values are not, and the address you probed is not in the report either. What the file does contain is the device's own identity and behaviour, which is the point of it.
The report also lists what it could not answer and why — a file with ten answers and no mention of the eleventh question reads as complete.
If you run this against a model that is not in the compatibility notes yet, the report is exactly what a pull request adding it needs.
Quick Start
Check Device Status
Add a Person
Upload Face Image
Search and Manage Face Data
Search Persons
Paginating by hand? Pass the same
$searchIdto every call. ISAPI treats it as the identity of a search session, and changing it mid-walk makes the device start over — silently.all()handles this for you.
Add Card
Control Doors
Search Events
Event Webhooks & Notifications (v1.4.0+)
Configure Hikvision devices to automatically push events (access granted, face recognized, etc.) to your application's webhook endpoint in real-time. This eliminates the need for polling and provides instant event notifications.
Configure Webhook Endpoint
The EventNotificationService allows you to configure HTTP event notifications on Hikvision devices:
Simple Webhook Setup
The easiest way to set up a webhook is using the configureWebhook() method:
Advanced Webhook Configuration
For more control over webhook configuration, use configureHttpHost():
Managing Webhook Hosts
Testing Webhooks
Test if your webhook endpoint is reachable from the device:
Receiving Webhook Events
Create a controller to receive webhook events from Hikvision devices:
Route setup:
Multi-Device Webhook Setup
Configure webhooks for multiple devices:
Webhook Security
Protect your webhook endpoint:
Webhook Event Examples
Access Control Event (Face Recognition):
Motion Detection Event:
Using the Facade
Services Overview
DeviceService
PersonService
CardService
FaceService
FingerprintService
AccessControlService
EventService
EventNotificationService
DTOs (Data Transfer Objects)
Person DTO
Card DTO
Face DTO
Enums
UserType
EventType
Error Handling
All exceptions extend HikvisionException:
Multi-Device Support
The package supports managing multiple Hikvision devices simultaneously. This is useful when you have multiple terminals at different locations (entrance, exit, canteen, etc.).
Device Sources Supported:
- ✅ Config files (default)
- ✅ Database tables
- ✅ Custom callbacks (API, Redis, cache, etc.)
- ✅ Runtime registration
Configuration from Config Files (Default)
Configure multiple devices in config/hikvision.php:
Environment Variables
Add device-specific environment variables to .env:
Using Multiple Devices with Facade
Using Multiple Devices with Services
Syncing Employee to Multiple Devices
Device Manager Methods
The DeviceManager provides the following methods:
Backward Compatibility
The package maintains 100% backward compatibility. If you're using the default device setup, your existing code will work without any changes:
Loading Devices from Database
For applications that store terminal configurations in database (multi-tenant, dynamic terminals, etc.), use the DatabaseDeviceProvider:
Step 1: Create Terminals Table
Step 2: Register Database Provider
In your AppServiceProvider or custom service provider:
Step 3: Use Terminals from Database
Step 4: Reload Devices When Database Changes
Using Eloquent Models with CallbackProvider
For more complex scenarios with Eloquent relationships:
Multi-Tenant Support Example
For multi-tenant applications where each tenant has their own terminals:
Runtime Device Registration
Register devices dynamically at runtime:
Switching Providers at Runtime
Change device provider dynamically:
Advanced Usage
Batch Operations
Pagination
Custom HTTP Requests
Testing
Troubleshooting
Authentication Failed (401)
Check your credentials in .env:
Connection Timeout
- Verify device IP and network connectivity
- Increase timeout in config:
HIKVISION_TIMEOUT=60 - Check firewall rules
Face Upload Fails
- Ensure image is JPEG format
- Check image size (max 200KB)
- Verify person exists on device first
- Image quality should be good with clear face
Device Not Found
- Check IP address in
.env - Verify device is powered on
- Ensure device is on same network
Security
See SECURITY.md for supported versions, vulnerability reporting instructions, and disclosure policy. Do not open public GitHub issues for suspected vulnerabilities; report them privately through the channels described there.
- Store Hikvision device and webhook credentials in environment variables or a secret manager; never commit them
- Prefer HTTPS/TLS for device and webhook communication where supported
- Enable SSL certificate verification with valid certificates in production
- Restrict device access with firewalls, VPNs, or private networks
- Implement rate limiting on your API endpoints
- Validate webhook payloads and all user-controlled input
- Treat XML input as untrusted and parse it defensively
- Avoid logging credentials, tokens, face images, biometric data, or raw personally identifiable data
- Rotate device and webhook credentials after suspected compromise
Contributing
Two contributions are worth more than the rest: a compatibility report from a real device, and a failure where nothing threw. Both are explained in CONTRIBUTING.md, along with how to run the tests.
Nobody has confirmed this package against a terminal yet. If you have one, the probe takes a minute and answers questions the specification does not.
Changelog
For full release history, see CHANGELOG.md and the GitHub releases/tags.
v1.5.4 (2025-11-05)
- Current stable release on Packagist.
- Fixed FaceService image filenames so supported face upload/update flows use unique
{fpid}.jpgfilenames.
v1.4.0 (2025-10-30)
- EventNotificationService: New service for configuring HTTP event notifications (webhooks)
- Real-Time Webhooks: Configure devices to push events to your API endpoints automatically
- XML Support: Added
putXml()method to HikvisionClient for XML-only endpoints - HTTP Client Enhancements:
- Added
arrayToXml()method for converting arrays to XML format - Added
xmlToArray()method for parsing XML responses - Automatic XML/JSON format detection based on Content-Type
- Added
- Event Notification Methods:
configureWebhook()- Simple one-line webhook setupconfigureHttpHost()- Advanced webhook configuration with authenticationenableHttpHost()/disableHttpHost()- Enable/disable webhookstestHttpNotification()- Test webhook connectivitygetCapabilities()- Get notification capabilities
- Dependencies: Added
ext-simplexmlandext-libxmlfor XML processing - Multi-Device Webhooks: Configure webhooks for multiple devices simultaneously
- Webhook Security: Support for HTTP Basic and Digest authentication
- 100% backward compatible with v1.3.0
v1.3.0 (2025-10-13)
- Universal Device Providers: Framework for loading devices from any source
- DatabaseDeviceProvider: Load terminals from database tables with built-in caching
- CallbackDeviceProvider: Maximum flexibility with custom callbacks (API, Redis, etc.)
- Multi-Tenant Support: Tenant-scoped device loading and isolation
- Runtime Device Registration: Register devices dynamically at runtime
- Provider Switching: Change device providers on-the-fly
- Hot Reload: Update database-driven configurations without restart
- Configurable Caching: Built-in cache support with TTL control
- 100% backward compatible with v1.2.0
v1.2.0 (2025-10-13)
- Multi-Device Support: Manage unlimited Hikvision devices simultaneously
- DeviceManager: Central manager with lazy initialization and caching
- New Hikvision Facade: Multi-device access with
Hikvision::device() - Device Discovery: List and validate configured devices
- Device-Specific Clients: Automatic client caching per device
- 100% backward compatible with single-device setups
v1.1.0 (2025-10-13)
- Face Search Functionality: Search face data with pagination support
- Face Data Record Upload: Multipart/form-data support for face images
- Fixed PersonService Delete Endpoint: Updated to match ISAPI specification
- Configuration Validation: Required username/password validation
- Extended HTTP Client: Added multipart form-data upload support
- Enhanced error handling and validation
v1.0.0 (2025-10-09)
- Initial release
- Full ISAPI support
- Person, Card, Face, Fingerprint management
- Access control and event handling
- Laravel 11/12/13 support
- PHP 8.2+ with modern features
License
This package is open-sourced software licensed under the MIT license.
Credits
- Author: Shaykhnazar
- Email: [email protected]
Support
For issues, questions, or contributions:
- GitHub Issues: https://github.com/shaykhnazar/hikvision-isapi/issues
- Email: [email protected]
Built on this package
Davomat — a finished attendance product for companies that already own Hikvision terminals (closed source; this package is the part that is not): an on-site agent that reaches the devices behind NAT, a multi-tenant cloud that turns swipes into a monthly timesheet, Excel export, and a daily Telegram summary for the director.
If you are reading this because you were asked to "get the timesheet out of the terminal", that is the same problem, already solved. Ask: [email protected].
Disclaimer
This package is designed for legitimate access control systems and defensive security purposes only. Do not use for malicious purposes.
Made with ❤️ for the Laravel community
All versions of hikvision-isapi with dependencies
illuminate/support Version ^12.0|^13.0
guzzlehttp/guzzle Version ^7.8
ext-curl Version *
ext-json Version *
ext-simplexml Version *
ext-libxml Version *