Download the PHP package shaykhnazar/hikvision-isapi without Composer

Hikvision ISAPI Laravel Package

A clean, modern Laravel package for integrating with Hikvision ISAPI Face Recognition Terminals and access control devices. Supports multi-device management, universal device providers (config, database, API), multi-tenant architectures, and real-time event webhooks.

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: Full Laravel 12.x support with service provider and facade

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
• 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

Requirements

• PHP ^8.2
• Laravel ^12.0
• Guzzle HTTP ^7.8
• ext-curl
• ext-json

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:

Quick Start

Check Device Status

Add a Person

Upload Face Image

Search and Manage Face Data

Search Persons

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

• Store credentials in .env file (never commit)
• Use HTTPS in production
• Enable SSL verification with valid certificates
• Implement rate limiting on your API endpoints
• Validate all user input

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Follow PSR-12 coding standards
5. Submit a pull request

Changelog

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
• Event Notification Methods:
  • configureWebhook() - Simple one-line webhook setup
  • configureHttpHost() - Advanced webhook configuration with authentication
  • enableHttpHost() / disableHttpHost() - Enable/disable webhooks
  • testHttpNotification() - Test webhook connectivity
  • getCapabilities() - Get notification capabilities
• Dependencies: Added ext-simplexml and ext-libxml for 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 12.x 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]

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