Lighthouse Passport Laravel Package

Technical Evaluation

Architecture fit

• v1.0.0 is the package's first published release; the changelog ("initial version of the package") carries no signal about scope, design intent, or the problem it solves. There is no prior assessment to diff against, so this is a cold-start evaluation rather than a change review.
• The 1.0.0 version number is the only meaningful data point available. In Composer/Packagist semantics it signals an intent to honor backward compatibility under semver, but an initial release cannot have earned that stability — treat ^1.0 as "author asserts stability," not "stability demonstrated."
• Laravel fit is unverified: confirm the package ships a service provider with package auto-discovery, publishable config/migrations, and no reliance on private framework internals (Illuminate\* non-public APIs, container internals, Facade base-class reflection).

Integration feasibility

• Blocking unknowns before any spike: supported PHP versions (php constraint), supported Laravel major versions (illuminate/support constraint range), whether it is framework-agnostic PHP with a Laravel adapter or Laravel-coupled throughout, and the transitive dependency footprint.
• Dependency weight is the main feasibility risk for a Laravel package. A wide illuminate/* range that is only CI-tested against one version is a common source of silent breakage.
• Integration cost is bounded and cheap to measure: install into a scratch Laravel app, run composer why, inspect the published config surface, and exercise the primary code path. This is a half-day diligence task, not a program-level commitment.

Technical risk

• Low verifiability, not necessarily low quality. With one release and no changelog detail, we cannot distinguish a mature internal tool being open-sourced from an unfinished prototype. Absence of evidence should be scored as risk, not as a neutral.
• Maintainer continuity is the dominant risk. Single-release packages frequently have a bus factor of one. Check commit cadence, issue/PR responsiveness, license, and whether the repo is public and linked from composer.json.
• Security surface is unknown: no data on whether it registers routes, middleware, scheduled tasks, or handles user input. Any package that auto-registers routes or publishes migrations touches the attack surface and deployment process.
• Abandonment cost is asymmetric — a thin utility is cheap to fork or replace; anything that owns schema, auth, or queue semantics is not.

Key questions

1. What problem does this package solve, and what is the documented alternative (build in-house, existing package, framework-native feature)?
2. What are the declared php and illuminate/* constraints, and what is actually covered in CI (PHP × Laravel matrix)?
3. Is the source repository public, licensed permissively, and does composer.json point to it?
4. Does it publish migrations, register routes, schedule jobs, or alter auth/queue/container behavior?
5. What is the total transitive dependency count, and does it conflict with our existing lockfile?
6. Who maintains it, and what is the observed release/issue cadence?
7. Is there a documented upgrade policy or deprecation process?

Integration Approach

Stack fit

• Fit is currently unproven and should be recorded as such. The relevant question is not "is this good Laravel code" but "does it sit at a layer we already own." Packages that duplicate framework-native capability (HTTP client wrappers, cache/queue abstractions, auth scaffolding) create long-term divergence cost.
• Green-field Laravel services are the lowest-friction target; legacy apps pinned to older Laravel majors should be treated as out of scope until the constraint range is read from composer.json.

Migration path

• There is nothing to migrate from — this is a net-new adoption decision, not a replacement. The realistic path is: sandbox spike → single non-critical service → broader rollout.
• Because it is a 1.0.0, pin exactly (1.0.0) rather than floating (^1.0) for the first integration. Loosen only after observing one minor release pass without breaking changes.
• Require an ADR or short decision record capturing the alternative-considered and the exit plan. For a package this unproven, the exit plan is the deliverable, not the integration.

Compatibility

• Verify against our actual runtime matrix, not the package's claimed matrix: our PHP version(s), our Laravel major(s), and PHPUnit/Pest version alignment if the package ships test helpers.
• Check for global side effects that conflict with our conventions: config key naming collisions, facade alias collisions, published asset/migration timestamps, and any boot()-time behavior that assumes a specific environment.
• Confirm compatibility with our static analysis and style baselines (PHPStan/Larastan level, Pint/PHP-CS-Fixer) — a package that fails our own gates forces an exclusion rule, which is recurring cost.

Sequencing

1. Diligence (day 1): read composer.json, README, license, repo history; run the sandbox install and inspect published artifacts.
2. Decision gate: adopt / pilot / defer. Default to defer if the package touches persistence, auth, or request lifecycle without documentation.
3. Pilot: one service, one code path, exact version pin, feature-flagged if it sits on a request path.
4. Review at 30 days: issue count encountered, upgrade behavior, maintainer responsiveness.
5. Broaden or remove. Treat removal as a first-class outcome.

Operational Impact

Maintenance

• Ongoing cost is composed of upgrade effort (tracking Laravel majors), version-pin churn, and the tax of any local patches we must carry. A package we fork is a package we now maintain.
• Establish renewal criteria up front: re-evaluate at the next Laravel major, or if the package goes >6 months without a release while our framework version moves on.

Support

• Support model is unknown: no data on SLA, commercial backing, or maintainer responsiveness. Assume community-only, best-effort.
• Internally, name an owner. Unowned third-party packages in a Laravel app become permanent, unremovable dependencies because nobody remembers why they were added.

Scaling

• Scaling risk depends entirely on what it does at runtime, which is undocumented. A helper library is horizontally irrelevant; anything doing per-request I/O, holding state in singletons, or adding middleware to every request needs load testing before it goes anywhere near production traffic.
• Watch for boot-time work (boot() doing discovery, filesystem reads, or network calls) — these compound under Octane/Swoole, where singletons persist across requests.

Failure modes

• Silent abandonment: no releases, no responses, and a pinned version that blocks our next Laravel upgrade. Most likely failure.
• Transitive conflict: package pins a dependency version that collides with our lockfile, forcing a partial upgrade we did not plan.
• Hidden global behavior: auto-registered middleware or routes that change request handling in ways not visible in application code.
• Semver violation: a 1.x minor ships a breaking change, breaking our pinning assumptions.
• Octane incompatibility: container/state assumptions that only surface under persistent workers.

Ramp-up

• Zero organizational familiarity today. Budget roughly half a day of engineering for the diligence spike, plus one to two days for a pilot integration and rollback rehearsal.
• Documentation burden falls on us: whoever integrates must write the internal "why we use this and when to remove it" note, because the package's own docs are unproven.
• Recommendation: do not treat v1.0 as an approved dependency. Open a diligence ticket, keep the default position at defer, and re-assess once the package has a substantive changelog, a public repo, a declared version-support matrix, and at least one subsequent release demonstrating the maintenance cadence.