Ami React Laravel Package

Technical Evaluation

Architecture fit — poor-to-conditional. clue/ami-react is a ReactPHP client, meaning it operates on an event loop with non-blocking streams. Laravel's default execution model is synchronous, per-request, and lifecycle-scoped, so this library cannot be consumed from a controller, job, or middleware without either blocking the loop or being reduced to a thin synchronous wrapper that defeats its purpose. It only fits where a long-running PHP process is acceptable: a dedicated Artisan daemon under Supervisor/systemd, a standalone worker container, or a sidecar. Treat it as infrastructure, not as an application dependency.

Integration feasibility — viable with deliberate boundaries. The realistic pattern is a single long-lived process that authenticates to Asterisk's AMI (TCP 5038, optionally TLS), maintains the event stream, and bridges events into Laravel through Redis pub/sub, a queue, or internal HTTP. Laravel then handles persistence, policy, and UI against a normal request/response flow. This keeps async complexity confined to one deployable unit and lets the rest of the team stay in familiar territory.

Technical risk — moderate, and mostly not about the code. Several factors:

• Metadata integrity. The repository is listed as unknown and the last release is dated in the future. Both should be verified before adoption; a future-dated release is either a metadata error or a signal the feed is unreliable.
• Project maturity. 84 stars and a narrow consumer base imply a small surface of production users. No Laravel service provider, config publishing, facade, or contracts — all glue is yours to write and own.
• Protocol characteristics. AMI is a plaintext, line-oriented protocol whose event volume scales with call activity. Reconnect/backoff, login retry, and event-loss windows during reconnection are not solved for you.
• Event-loop coexistence. Running this inside Laravel Octane or alongside Swoole is an anti-pattern — two competing loops. Isolate it.
• Bidirectional need. If requirements include issuing AMI actions (originate, hangup, queue control) and correlating responses to requests, scope grows meaningfully versus read-only event consumption.

Key questions for the vendor/stakeholder:

1. What is the concrete use case — call event visibility, CRM screen-pop, CDR ingestion, or active call control? Read-only vs. bidirectional changes the estimate by a large multiple.
2. What is peak events-per-second and the acceptable event-loss window during a PBX restart or network blip?
3. Who owns the Asterisk estate, and is AMI enabled, ACL-restricted, and reachable from the target network segment? Are credentials rotated?
4. Does the team have any production async PHP experience, and is there appetite to own a daemon long-term?
5. Was Asterisk ARI, or an AMI-to-HTTP bridge, evaluated as a lower-complexity alternative for this specific use case?

Integration Approach

Stack fit. Composer-installable, MIT-licensed, PHP 8.x with ReactPHP transitive dependencies (react/socket, react/stream, evenement). It composes cleanly with a Laravel 10/11 codebase as a library, but the runtime should be a separate process or container sharing the same repository — not the web tier. Package it internally as a small domain module (app/Ami or a private Composer package) exposing an event DTO layer and a publisher, so application code never touches ReactPHP types.

Migration path. Greenfield — there is no incumbent to migrate away from, which is an advantage. The migration risk is organizational rather than technical: introducing a daemon deployment unit and an async ownership boundary into a conventionally synchronous Laravel shop. Mitigate by keeping the daemon small, single-purpose, and stateless apart from the connection.

Compatibility. Verify PHP version constraints against the host application, confirm no event-loop package conflicts (revolt/event-loop vs. legacy react/event-loop), and validate Composer resolution against the full Laravel dependency set before committing. Confirm the AMI target (Asterisk 16/18/20/21) and which events are actually emitted — the library transports events, it does not normalize them. TLS support depends on the underlying socket layer and the PBX's certificate posture.

Sequencing.

1. Spike (1 week). Prove connectivity, login, event receipt, and reconnect against a non-production Asterisk instance. Validate the release metadata.
2. Event taxonomy. Enumerate the AMI events that matter and define the internal DTO contract. This is the durable asset; the transport is replaceable.
3. Process skeleton. Artisan command with signal handling, structured logging, health endpoint/file, and Supervisor config.
4. Bridge. Publish to Redis or the Laravel queue; make consumers idempotent with an event dedupe key.
5. Observability. Connection state metrics, event counters, reconnect counts, lag indicators.
6. Hardening. Load test at expected peak, chaos test (kill PBX, drop network), memory soak test over 72 hours.

Operational Impact

Maintenance. Low upstream velocity is a double-edged sword: fewer breaking changes, but also a thin maintainer bench and no guaranteed security response. Pin to an exact version, mirror the repository internally, and budget a designated owner with a documented fork-and-patch path. Budget roughly 10–15% of one engineer's time for ongoing stewardship.

Support. Community-only. There is no vendor SLA, no paid support tier, and no Laravel-ecosystem precedent to lean on for answers. Internal runbooks and a clear escalation path are mandatory before go-live. Expect troubleshooting to require reading the library source.

Scaling. One TCP connection per AMI account, and Asterisk's AMI has practical connection limits — horizontal scaling means either provisioning multiple AMI accounts or introducing a single ingestion tier that fans out to consumers. The event loop is single-threaded, so throughput is bounded by per-event handler cost; keep handlers trivial (serialize and publish) rather than doing work inline. Long-running PHP processes are memory-sensitive — enforce periodic graceful recycling and monitor RSS.

Failure modes to design for explicitly:

• Silent or half-open connection loss with no client-side detection → mandatory heartbeat/Ping with timeout.
• Event loss during reconnect windows → accept and document the gap, or reconcile periodically from CDR/queue logs.
• Unbounded queue growth under backpressure → bounded buffers with drop-and-alert semantics.
• Authentication failure loops or credential rotation without restart → support config reload.
• PBX-initiated restarts and AMI reloads → exponential backoff with jitter.
• Blocking calls (synchronous DB writes, HTTP) inside the loop → architectural review gate.
• Deploy-time disruption → graceful drain and connection handoff, or accept a short ingestion gap and alert on it.

Ramp-up. A mid-level PHP engineer unfamiliar with async patterns needs roughly two to three weeks to be productive in this codebase, and one to two sprints to reach production-hardened. The learning curve is ReactPHP's mental model, not the AMI protocol. Plan for pairing or a spike-driven knowledge transfer, and require the daemon's runbook to be written by the implementer, not after handover. Given 84 stars and unknown repository provenance, add an explicit adoption decision gate after the spike — the fallback of shelling out to an AMI-capable sidecar in another language should remain on the table.