Hikvision Isapi Laravel Package

Product Decisions This Supports

• Event reliability and data-loss recovery: EventService::between() is a generator that pages through access events in a time window using a stable searchID, advancing by records actually returned. This directly supports backfilling events dropped by webhook delivery — a common failure mode in device-integration products.
• Retry and incident-handling strategy: The new exception taxonomy (isRetryable(), statusCode(), responseBody(), DeviceUnreachableException, DeviceBusyException, and AuthenticationException on HTTP 401) lets the application make principled retry decisions instead of treating all device/API failures the same. This affects queue design, alerting, and operator runbooks.
• Platform roadmap and upgrade planning: Dropping Laravel 11 is a security-driven breaking change. Teams on Laravel 11 must stay on 1.x, while teams on Laravel 12/13 can plan toward v2 after beta validation.
• Build vs. buy / integration ownership: The package continues to own Hikvision device communication, pagination, XML handling, and HTTP concerns. A pre-configured Guzzle client option improves testability and lets teams inject proxies, middleware, or custom TLS settings without forking.
• Quality and operability investment: CI across PHP 8.2–8.4 and Laravel 12/13, Pint, PHPStan level 5 with no baseline, 88 tests (up from 31), and cleared Composer audit advisories signal maintainer investment in production hygiene.
• Caveat for roadmap timing: v2 is a beta and the new APIs have not run against a real terminal. It should not anchor production commitments until validated against actual hardware.

When to Consider This Package

• Consider for pilot/evaluation when: the product runs Laravel 12 or 13, needs reliable access-event ingestion, and would benefit from backfilling dropped webhook events or more precise retry behavior.
• Strong fit when: you operate Hikvision devices at scale and want a maintained integration layer with pagination correctness, structured exceptions, and testable HTTP injection rather than building device/event plumbing in-house.
• Stay on 1.x when: the application is on Laravel 11. The package cannot be installed or tested against Laravel 11 under Composer 2.9+ because of unresolved framework security advisories.
• Avoid production adoption of v2.0.0-beta.1 when: you require proven terminal behavior, stable APIs, or immediate production rollout. The release explicitly notes the new APIs have not run against a real terminal.
• Look elsewhere or reassess when: you need vendor-supported SLAs, multi-vendor device support, or cannot tolerate a beta upgrade cycle for critical event ingestion.

How to Pitch It (Stakeholders)

For executives: This release is a security-driven modernization plus a reliability upgrade. Laravel 11 support is dropped because unresolved framework advisories make it uninstallable under current Composer; teams on Laravel 11 stay on 1.x. For teams on Laravel 12/13, v2 adds event backfilling to recover dropped webhook data, structured retry/error handling, and a cleaner HTTP integration path. It is a beta, so the recommendation is to pilot and validate against real hardware before committing production roadmaps.

For engineering: v2.0.0-beta.1 introduces a breaking platform change — Laravel 11 is out, Laravel 12/13 and PHP 8.2–8.4 are in. The new EventService::between() generator reuses a searchID across pages and is the primitive for backfilling dropped events. search() now accepts a searchId for correct pagination. The exception taxonomy enables retry decisions via isRetryable(), statusCode(), and responseBody(), with dedicated unreachable/busy exceptions and 401 mapped to authentication failure. A custom Guzzle client can be injected. Quality gates improved substantially: 88 tests, PHPStan level 5 with no baseline, Pint, and cleared audit advisories. Do not treat the beta as production-ready until it has been exercised against a real terminal.