Friendship Laravel Package

Technical Evaluation

Architecture fit

• Laravel-native package: service provider with auto-discovery, publishable config and migrations, an Eloquent trait applied to "friendable" models, and a facade/service layer for requests, acceptance, denial, blocking, and mutual-friend lookups.
• Polymorphic design (morph sender/recipient) means the graph is not hard-coded to User — it can extend to Team, Page, or Organization without a schema change. That is the main architectural reason to prefer it over a hand-rolled friendships table.
• Fits a modular monolith or a single Laravel service. It is not a distributed/graph-database solution; it assumes the friendship graph lives in the same relational database as the entities.
• Events dispatched on state transitions make it composable with existing notification, feed, and activity-log infrastructure.

Integration feasibility

• Low-friction install: composer require, publish migrations/config, add the trait to one or two models, wrap the facade in a thin domain service. Realistic spike effort is 1–3 engineer-days including tests.
• Surface area is small and legible, which lowers review cost — a senior engineer can audit the whole package in an afternoon.
• Primary friction is not technical but procedural: deciding where the trait lives, whether to expose the package's API directly or hide it behind an interface, and how to enforce authorization (who may request/block whom) outside the package.

Technical risk

• The confidence signals are weak: 18 stars, zero dependents, a single maintainer, and an aggregate score of 0.09. There is essentially no ecosystem validation and no evidence of production use at scale.
• Bus factor of one. Laravel major-version cadence is roughly annual; an unmaintained dependency here becomes a forced fork within 12–18 months.
• Correctness risk concentrates in concurrency and state transitions: parallel friend requests, accept-after-block, block-after-accept, and deletion of a friendable model leaving orphaned polymorphic rows. These are the exact paths small packages tend to under-test.
• Query-cost risk: "mutual friends" is an intersection over two edge sets and degrades quickly without deliberate indexing and caching.
• License is MIT — no legal blocker, fork and vendor are permitted.
• The opportunity: 7 sub-score is the counterweight: the domain problem is real and recurring, and the alternative is building and maintaining this state machine in-house.

Key questions

• Which Laravel and PHP versions are declared in composer.json, and is the test matrix actually run in CI across them?
• What is the exact status model (pending/accepted/denied/blocked) and are transitions enforced, or can arbitrary rows be written?
• Does blocking remove or merely mask existing friendships, and are blocks symmetric in both query directions?
• Are there unique constraints preventing duplicate or mirrored request rows, and are they enforced at the database level or only in PHP?
• How is the mutual-friends query implemented, and what indexes ship with the migration?
• What is test coverage, and are there open issues describing data-integrity bugs?
• Does it support soft deletes, multi-tenancy, or non-users tables cleanly?

Integration Approach

Stack fit

• Requires a conventional Laravel stack with MySQL/Postgres and standard Eloquent. No queue, cache, or external service dependency, so it slots into existing infrastructure without new operational surface.
• Pairs naturally with existing notification (database/mail), authorization (policies/gates), and API resource layers. The package owns persistence; the application should own policy and presentation.

Migration path

• Greenfield: publish migrations, review the generated schema, add composite indexes (sender_type, sender_id, status and recipient_type, recipient_id, status) before any production data exists.
• Brownfield (existing friend/connection tables): do not run both systems live. Backfill into the package schema in a single migration window, map legacy statuses explicitly, and validate row counts and symmetry with a reconciliation script before cutting reads over.
• If the graph is currently denormalized (e.g., a friends pivot), expect a one-way conversion and keep the legacy table read-only for one release as a rollback path.

Compatibility

• Pin an exact version in composer.json and treat upgrades as deliberate work, not composer update residue.
• Verify the package's Laravel constraint against the application's current and next major version before committing — this determines whether you are adopting a dependency or adopting a fork.
• Confirm the package does not pull dev-only or abandoned transitive dependencies.
• Verify PHP version floor matches the runtime; PHP 8.1+ type strictness occasionally breaks older package code paths.

Sequencing

1. Timeboxed spike in a throwaway branch: install, publish, exercise the full state machine against SQLite/MySQL, and write failure-case tests (duplicate request, accept-after-block, model deletion).
2. Schema and index review by the engineer who owns the database; add indexes and constraints the package omits.
3. Wrap the facade behind an internal FriendshipService interface so the package is replaceable and call sites never depend on it directly.
4. Integrate on a single low-risk model behind a feature flag; keep the existing feature path intact.
5. Add authorization policies, rate limiting on requests, and notification wiring — these are out of scope for the package and are the bulk of the actual product work.
6. Roll out by cohort, then remove the flag and the legacy path.

Operational Impact

Maintenance

• Assume internal ownership from day one. Even if upstream is active, the package is small enough that the pragmatic posture is "vendor the code into the repo or maintain a fork," not "wait for a PR."
• Budget recurring effort for Laravel major upgrades and dependency bumps. Realistically a few days per framework cycle, plus ad-hoc patches.
• The migration is published into the application, so schema evolution is under your control even if the package stalls — a meaningful de-risking factor.

Support

• No commercial support and a thin issue tracker. Internal documentation of the state machine and its invariants is mandatory, not optional — the next engineer will not infer blocking semantics from the code.
• Establish an escalation path: who can patch the fork, who reviews schema changes, and what the rollback looks like.

Scaling

• Friendship graphs grow superlinearly in query cost. Friend-list reads are cheap with proper indexes; mutual-friend and "friends of friends" reads are not and should be precomputed or cached with an explicit invalidation strategy on accept/block/unfriend.
• Blocking checks are on the hot path of feed, messaging, and search. Cache a blocked-ID set per user with short TTL rather than joining on every request.
• Watch for N+1 loading on polymorphic relations — eager-loading morphs requires explicit morphWith/morphWithCount usage that the package will not do for you.
• Write volume is low (human-paced actions), so write scaling is a non-issue; read amplification is the real concern.

Failure modes

• Duplicate or mirrored friendship rows from concurrent requests if uniqueness is enforced only in application code.
• Inconsistent state after block: accepted friendship rows surviving a block and leaking through unfiltered queries.
• Orphaned polymorphic rows when a friendable model is hard-deleted without morphMany cleanup, causing silent join misses and count drift.
• Event listener failures — if downstream listeners throw, the transition may partially succeed; verify whether dispatch is transactional.
• Mutual-friend queries returning stale results after cache invalidation gaps, which surfaces to users as visible inconsistency.
• Migration rollback leaving data in the new shape with no path back; test migrate:rollback before production.

Ramp-up

• Low for any Laravel developer: trait + facade is a familiar idiom, and the domain is intuitive.
• The real ramp-up cost is semantic, not syntactic — engineers must learn the status transition rules, block semantics, and query-direction conventions. Capture these in a short internal README with a state diagram.
• Expect roughly half a day for a mid-level Laravel engineer to be productive, contingent on that documentation existing.