Iam Laravel Package

Technical Evaluation

gdbots/iam is not a Laravel package and does not pretend to be one. It is a schema-implementation library: it supplies the concrete PHP message classes (users, roles, permissions, grants, and related IAM entities) generated from the gdbots:iam PBJ schemas. It carries a hard dependency on the gdbots/pbj runtime (schema registry, validation, JSON serialization) and, by extension, on the wider GDBots message/command/event stack. There is no service provider, no configuration file, no facade, no migrations, no guards, no HTTP surface, and no storage layer. A TPM should evaluate it as a domain model dependency, not as an auth solution.

Architecture fit. Fit is narrow but real. The library gives you immutable, validated, JSON-serializable IAM value objects with strict field typing — attractive if your architecture is already command/event-oriented, or if you want a canonical IAM contract that is decoupled from Eloquent. It is a poor fit if your team expects Auth::user(), policies, and a role_user pivot table on day one. Adopting it means owning the persistence, hydration, caching, and authorization-decision layers yourself.

Integration feasibility. Mechanically simple — composer require gdbots/iam plus the PBJ runtime — but the real work is mapping schema objects to your database. Expect to write repository adapters, Eloquent casts or custom serializers, and a translation layer between PBJ messages and your application's domain models. Budget the integration as a small project, not a dependency bump. The v3.0.0 release is a major version bump (PHP 8.1 support), so any prior prototyping or spike work against v2.x must be re-validated; the breaking changes are not enumerated in the release note and must be discovered from the diff or changelog before committing to a version pin.

Technical risk. High, concentrated in three places: (1) Staleness / cadence — v3.0.0 is a genuine, if minimal, sign of life and it raises the PHP floor to 8.1, which partially addresses the previous "unverified on modern PHP" concern. But it targets 8.1 specifically; PHP 8.2/8.3 support is still unverified, and the release note mentions no test matrix or CI. The library still has zero stars, zero dependents, and no visible downstream usage to shake out bugs, and the cadence (one release since December 2021) is far too slow for a security-sensitive dependency. (2) Governance — IAM is security-sensitive; a major-version-only-with-a-one-line-note release is a signal about maintainer engagement, and an unmaintained dependency at the core of authorization is a finding in most security reviews. Apache-2.0 mitigates this somewhat by permitting a vendored fork. (3) Schema semantics — the gdbots:iam schemas reflect one vendor's modeling choices (entity naming, grant/permission structure, tenancy assumptions); they may not express your RBAC/ABAC requirements without extension, and v3.0.0 adds a major-version compatibility surface on top of that. (4) Migration surface — a breaking v3.0.0 means any early adopter now carries a fork-and-patch obligation if the new major is incompatible with their stack.

Key questions. Who owns this library now, and is there a security disclosure channel? What exactly broke in v3.0.0, and does the schema set or the PBJ runtime contract change? Does it install cleanly under our PHP (8.2/8.3) and Laravel versions, and what does composer why-not gdbots/iam v3.0.0 say? Is the schema set complete for our model (hierarchical roles, resource-scoped permissions, multi-tenancy, service accounts)? Does it handle any credential or secret material, or purely authorization data? Are we prepared to vendor and maintain a fork — now including absorbing v3.x's breaking changes? And critically: does the cost of adopting a foreign domain model beat defining our own schema informed by it?

Integration Approach

Stack fit. Poor as a drop-in; workable as a bounded domain layer. The natural placement is a Domain/Iam or Packages/IamSchema module that knows nothing about HTTP, Eloquent, or Laravel's auth guard. Laravel-facing code (guards, policies, middleware) should depend on your own interfaces, which the PBJ-backed implementation satisfies. This keeps the dependency swappable and contains the blast radius if the library is abandoned upstream.

Migration path. Do not retrofit an existing app's auth tables. Introduce it in greenfield authorization surface area only — e.g., a new permission catalog or role-definition service — behind an adapter interface. Run it in shadow mode against existing Gate/Policy logic, compare decisions, and only then let it become authoritative for a single bounded context. If it underdelivers, you delete one adapter rather than unwind your auth stack. Target v3.0.0 directly for any new spike; do not build against v2.x with an intent to upgrade later, given the unenumerated breaking changes.

Compatibility. Pin exact versions and commit the lockfile. v3.0.0 confirms PHP 8.1 but says nothing about 8.2/8.3 — verify empirically with a spike, not from the release note. Expect to declare Composer conflict rules if the PBJ runtime drags in Symfony or PSR versions that clash with Laravel's, and expect the v3.0.0 bump to have moved those constraints in ways that may collide. Treat any PHP minor upgrade as a migration event for this dependency.

Sequencing. (1) Two-day spike: install v3.0.0, construct a User/Role/Permission, round-trip to JSON, validate a failure case — and diff the public API against v2.x to record the breaking changes. (2) Schema gap analysis against your authorization requirements. (3) Persistence adapter and mapping tests. (4) Guard/policy bridge. (5) Shadow-mode comparison. (6) Bounded production cutover. Gate each step on a go/no-go; the spike in step 1 should be allowed to kill the initiative cheaply.

Operational Impact

Maintenance. Assume you own it. The v3.0.0 release is a single data point and does not constitute a maintenance guarantee — one release in roughly four years, with a one-line breaking-change description, is not the cadence you want on an IAM dependency. The realistic posture is still a vendored fork under an internal namespace, with a documented patch policy and a calendar reminder to reassess. The Apache-2.0 license permits this; the absence of an upstream community means no free bug fixes, no CVE triage, and no compatibility work for new PHP or Laravel releases — including PHP 8.2/8.3 and future Laravel majors.

Support. No vendor, no maintainer responsiveness, no Stack Overflow corpus. Internal support means one or two engineers who understand PBJ's schema/codegen model — a bus-factor risk worth naming explicitly in any approval. v3.0.0 gives you no new escalation path.

Scaling. The library itself is data objects and validation; it adds negligible runtime cost and no state. All scaling characteristics (query patterns, caching, N+1 role lookups, permission-resolution latency) come from the persistence and resolution layer you build. Authorization checks on hot paths will need caching regardless of this dependency.

Failure modes. Validation exceptions thrown at serialization boundaries if upstream schema revisions drift; silent data loss on JSON round-trips when fields are added but not mapped; hydration failures after PHP/runtime upgrades (now including the v3.0.0 → future-major boundary); Composer resolution deadlocks during unrelated dependency updates; and the strategic failure — the library stops being maintained while sitting on your critical path. The v3.0.0 release adds a specific risk: a breaking major with no documented migration path, so any future upstream bump is an unbudgeted project rather than a routine update.

Ramp-up. Roughly one to two weeks for a competent PHP engineer to become productive with PBJ concepts (schemas, message construction, codegen workflow) before they can contribute meaningfully to the adapter layer. That is real onboarding cost for a library the team did not choose and cannot escalate to.

TPM recommendation. The v3.0.0 release is a positive signal on the staleness axis but does not change the fundamentals: a single PHP-8.1-targeted major release does not establish maintenance cadence, security responsiveness, or Laravel compatibility, and the unenumerated breaking changes add migration risk rather than reduce it. Default position remains: do not take a production dependency on the upstream package. Either (a) use it as a design reference and implement an internal IAM model in Eloquent/Laravel-native terms, or (b) vendor a fork only if the existing GDBots event/command stack is already in your architecture. Fund a two-day spike against v3.0.0 — explicitly to confirm PHP 8.2/8.3 behaviour and enumerate the breaking changes — to make that call with evidence rather than inference.