Ardaccess Bridge Bundle Laravel Package

Technical Evaluation

What this release is: maillotf/ardaccess-bridge-bundle 1.0.2 is a patch-level release of a Symfony bundle (not a Laravel package) that wraps the ARD Access REST API. The published notes are the package README, not release-specific changelog content — no migration notes, deprecations, or breaking changes are declared, so 1.0.2 should be treated as a routine patch from a baseline of 1.0.x. Since there is no prior assessment, this document establishes the baseline rather than tracking a delta.

Architecture fit: The vendor is not framed for our stated stack. It ships as a Symfony bundle using Symfony's DI container and YAML configuration (framework.yaml, services.yaml), autowiring by service id (@ardaccess.service). A Laravel application has no framework.yaml, no bundle registration, and no convention that would auto-discover ArdaccessService. Adopting it as-is means either standing up a Symfony DI container inside Laravel or bypassing the bundle entirely. Functionally, the package is a thin, fluent facade over a remote system: carrier (cardholder CRUD), creator (attribute and criterion builders), supervision (event queries), and a smart-object helper (handbackSmartObject). Those map to physical access-control domain objects — carriers/cardholders, access events, smart objects — which means this is a system-of-record integration for security-adjacent data, not a utility library.

Integration feasibility: Technically workable, operationally thin.

• The public surface demonstrated is small and readable: fluent builders for attributes and criteria, one domain namespace per API area, boolean return on handback.
• Configuration is minimal: protocol, host, port, username, password.
• No openapi/schema reference, no DTOs or typed responses, no exception taxonomy shown. Return types are undocumented beyond bool on one call and implied arrays elsewhere.
• No evidence in the release notes of CI, test coverage, static analysis, or a changelog. That is a material gap for a package touching access-control records.

Technical risk:

• Credential handling (high): The documented pattern is a plaintext username/password in framework.yaml with protocol: "http" and port: "80" as defaults. That is credentials-in-VCS and plaintext-over-the-wire unless we override to HTTPS and move secrets to environment variables. ARD Access credentials are likely privileged.
• Stack mismatch (high): Symfony-only packaging against a Laravel estate. Every integration path carries adapter work; there is no first-party Laravel service provider, facade, or publishable config.
• Vendor maturity (medium–high): Single-maintainer, niche package at 1.0.2, no visible release cadence or support commitment. Bus factor and abandonment risk are the dominant long-term concerns.
• Undocumented fluent API (medium): $aas->carrier, $aas->creator, $aas->supervision behave magically (__get-style access or declared properties is unclear). Builder semantics — whether newCriterion returns a new builder, how addSubCriterion nests, whether getCriterionsArray is reusable — are only inferable from the sample.
• Data-correctness risk (medium): The sample hardcodes Unix timestamps for begindate/enddate (1627602000 is 30 Jul 2021, already in the past). Teams copying the example will create expired access records and may not notice, because failures are not clearly surfaced.
• Error semantics (medium): One method returns true/false; the rest are unspecified. Without a documented exception model, callers cannot distinguish auth failure, network timeout, validation rejection, and "not found."
• Compliance exposure (medium): Payloads carry personal data (firstname, lastname, country, usergroup) and access events. GDPR retention and auditability need to be designed around the vendor API, not this wrapper.

Key questions:

1. Is there a standalone PHP client library (maillotf/ardaccess-*) beneath this bundle that we could use directly, avoiding Symfony DI entirely?
2. What is the target ARD Access server version and its REST API contract — is there an OpenAPI/Swagger spec, and does the wrapper pin to an API version?
3. What are the actual error semantics — exceptions, HTTP codes, or boolean/null returns? Is there a retry/timeout mechanism?
4. Does authentication support tokens, service accounts, or mTLS, or is HTTP Basic over plaintext the only documented option?
5. What PHP and Symfony version constraints, license (MIT vs. other), and security disclosure process apply?
6. Is handbackSmartObject and the uid/rid/usergroup attribute set specific to one ARD Access deployment, or universal? Are any IDs tenant-scoped?
7. What is the expected call volume and rate limit for ListCarriers / ListEvents, and is bulk/paged retrieval supported?

Integration Approach

Stack fit: Poor as-shipped, acceptable behind an adapter. Recommendation: do not install this bundle into the Laravel application as the integration mechanism. Two viable tracks:

• Track A (preferred): Use the underlying ARD Access REST client directly if a non-Symfony package exists, wrapped in a Laravel service provider with config/ardaccess.php bound to .env (ARDACCESS_HOST, ARDACCESS_USERNAME, ARDACCESS_PASSWORD, ARDACCESS_SCHEME=https), registered as a singleton, and exposed through an ArdAccessGateway interface plus a thin facade.
• Track B (fallback): Keep the bundle but isolate it — instantiate the bundle's services in a dedicated Laravel provider (or a small standalone Symfony container built only for this concern), and never let MaillotF\... types leak past the gateway boundary. This is deliberately more work and more fragile.

Either way, the gateway interface is the real deliverable; the vendor package is an implementation detail we expect to replace.

Migration path: Greenfield integration — there is no incumbent to migrate from, so the risk is architectural rather than transitional. Define the anti-corruption layer first (Carrier, EventQuery, SmartObject domain models of our own), implement it against a stubbed gateway, then wire the vendor in. If we later swap the vendor or fork it, call sites do not change. If an existing direct-HTTP or manual ARD Access integration is in place, port it behind the same interface so behavior can be diffed.

Compatibility: Two compatibility surfaces to clear before commitment: (1) PHP version — the badge indicates support but the composer constraint must be read directly; (2) Symfony component versions the bundle requires vs. what Laravel already pulls in transitively (console, http-foundation, event-dispatcher). Symfony components usually coexist fine with Laravel, but conflicting version pins are the most likely installation blocker. Also confirm Laravel's HTTP client is not required — the bundle likely brings its own transport (Guzzle or Symfony HttpClient), which becomes a second HTTP stack to configure for proxies, retries, and TLS.

Sequencing:

1. Spike (3–5 days): Composer-resolve against the actual Laravel version, prove a single authenticated call (ListCarriers) against a non-production ARD Access instance over HTTPS. This single test retires the largest unknowns: DI friction, transport config, and error shape.
2. ADR + security review: Decide Track A vs. B; security sign-off on credential storage (secrets manager, not YAML), HTTPS enforcement, and log redaction of personal data.
3. Gateway build: Interface, DTOs, provider, config, feature flag, and contract tests against recorded fixtures.
4. Pilot: One non-critical capability — read-only listing and event search — behind a flag, with production credentials rotated and scoped.
5. Write path: Enable carrier updates and smart-object handback only after error semantics are understood and idempotency/retry behavior is defined. Physical access mutations deserve a staged rollout.

Operational Impact

Maintenance: Highest ongoing cost is ownership of a niche, single-maintainer dependency. Expect to vendor the source or fork within 12–18 months; budget for that at design time by keeping the adapter thin and the vendor surface small. Patch releases like 1.0.2 arrive without changelogs, so upgrades need our own regression tests rather than release-note reading. The README-as-release-notes pattern also means deprecations will likely be discovered at upgrade time.

Support: No SLA, no commercial backing evident, GitHub issues only. Escalation for a broken integration is "we fix it." For an access-control integration that is a real operational constraint and should be documented as an accepted risk with a named internal owner and an on-call path that does not assume vendor responsiveness. Pair this with a maintained fallback: direct REST calls to ARD Access via Laravel's HTTP client, which the gateway interface makes exercisable.

Scaling: Every operation is a synchronous HTTP round-trip to the ARD Access server, so our throughput ceiling is the vendor server's, not ours. Specific concerns:

• ListCarriers and ListEvents are unbounded-looking list calls with no documented pagination — assume full-result retrieval and cache aggressively.
• Read paths (carrier lists, event queries) should be cached with short TTLs and warmed by scheduled jobs; do not call them inline in user-facing requests.
• Write paths (carrier update, smart-object handback) belong on a queue with timeouts, bounded retries, and dead-lettering, because they are the calls where a timeout leaves ambiguous state.
• Configure explicit connect/read timeouts and a circuit breaker; the package exposes no such configuration in the documented surface.

Failure modes:

• Credential/auth failure — silent or opaque depending on error handling; surfaces as empty lists or false, which is easy to misread as "no records."
• Network timeout mid-write — carrier update or handback may have applied server-side; without idempotency keys, retries risk duplicate or contradictory state. This is the most dangerous failure for a physical access system.
• Configuration drift — credentials and host live in YAML; rotation without redeploy is not supported by the documented pattern, so a rotation becomes a release.
• Schema/mapping drift — ARD Access attribute names (uid, rid, usergroup) are string-typed and unvalidated; upstream changes fail at runtime, not at boot.
• Sample-induced defect — copying the example's stale begindate/enddate timestamps silently creates expired access rights.
• Dependency abandonment — no upstream fix for a PHP/Laravel upgrade; the gateway interface is the mitigation.

Ramp-up: The example controller is genuinely helpful for orientation — one screen shows the fluent style for attributes, criteria, and helper calls. Beyond that, ramp-up depends on a linked docs table of contents and, critically, on ARD Access domain knowledge (what a carrier is, how smart objects relate to cardholders, how supervision events are queried) which this package does not teach. Estimate 1–2 days for a PHP developer to be productive with the client, plus 3–5 days of ARD Access domain and environment onboarding with whoever owns the access-control system. The binding constraint is domain access, not the library. Document our gateway interface rather than the vendor API so future engineers learn our abstraction first.