Relation Bundle Laravel Package

Technical Evaluation

TPM verdict: Do not add as a dependency. Treat the repository as prior art — a one-to-two day reference read whose only deliverable is a schema spec and a set of invariants we reimplement in Eloquent.

Architecture fit

• The artifact is a Symfony 2 bundle: a *Bundle class, a DependencyInjection extension, container YAML/XML, and Doctrine ORM mappings. None of that bootstraps inside a Laravel application without pulling symfony/framework-bundle and the Doctrine bridge into the app — effectively hosting a second framework and a second persistence model alongside Eloquent.
• The domain it covers (typed relations between entities: friends, contacts, follows, membership) is already native to Laravel via morphToMany / morphMany with pivot columns for relation type, status, and direction. There is no functional gap the bundle fills that we cannot express in a first-party pivot table.
• Net position for a TPM: framework mismatch is dispositive, and the capability is redundant. This is a no-go as a dependency, not a trade-off to weigh.

Integration feasibility

• Three paths exist; only one is a real option:
  1. Install it — rejected on framework and persistence grounds.
  2. Fork and port — technically possible because the domain logic is small, but it starts from an abandoned codebase with no trusted test baseline. Cost exceeds a clean rewrite.
  3. Read it, extract the schema and semantics, reimplement in Eloquent — the only available leverage, and it is genuinely cheap.
• What is worth extracting: the relation table shape (source type/id, target type/id, relation type, symmetric vs. directional, status/acceptance state), the bidirectional-consistency rules, and the query patterns for traversal.

Technical risk

• Explicit abandonment is stated in the package description. Symfony 2.8 reached EOL in November 2018; PHP lineage is 5.x. No security patching, no PHP 8 work, no framework bumps.
• Zero dependents, 10 stars, quality score 0.23. No production validation, no community-reported edge cases, no downstream forks keeping it alive. We would be the only operator of this code in the wild.
• Porting drift risk is the subtle one: Doctrine idioms (unit-of-work, annotation mapping, lazy collection proxies, cascade persist) do not map one-to-one onto Eloquent's active-record model. Engineers reading the reference may import assumptions that silently break on bidirectional writes.
• Licensing: verify before copying code verbatim; a clean-room reimplementation from the documented behavior sidesteps the question.

Key questions to resolve before committing budget

1. What relation semantics do we actually need — symmetric (friends), directional (follower), or typed-and-stateful (request → accepted → blocked)? Confirm before mining the reference.
2. Do relations cross entity types (User↔Team, User↔Document)? If yes, polymorphic pivot is mandatory, and Doctrine inheritance mapping is not a useful template.
3. Expected edge cardinality — thousands or hundreds of millions? This decides whether a plain pivot survives or needs closure-table/adjacency treatment.
4. Does existing in-house code or a maintained package (e.g. staudenmeir/eloquent-has-many-deep for traversal) already cover ~80%?
5. Who owns the spike, and is it sized as a spike or a feature?

Integration Approach

Stack fit

• Target is Laravel + Eloquent on MySQL/Postgres. Runtime compatibility with a Symfony 2 + Doctrine bundle is effectively zero; compatibility exists only at the conceptual layer. Set the expectation explicitly with stakeholders: we are reading an architecture document, not integrating a library.

Migration path

1. Spike (1–2 days): read the entity definitions and relation-manager service; document schema, symmetry rules, and query helpers into a one-page spec.
2. Schema design: single relations pivot — source_type, source_id, target_type, target_id, relation_type, status, created_by, timestamps — with a composite unique index on the five identifying columns and reverse-lookup indexes on the target side.
3. Eloquent implementation: morphToMany both directions, a Relation pivot model for state transitions, query scopes for traversal, and symmetry enforcement centralized in one service class.
4. Behavioral tests first: port the implied invariants into Pest/PHPUnit before writing the service — bidirectional dedupe, self-relation rejection, block precedence, idempotent accept.
5. Cutover: not applicable. Nothing is in production on this bundle, so there is no migration to schedule.

Compatibility

• If someone proposes "just install it," the blocking facts are: Symfony 2 kernel dependency, Doctrine persistence assumption, EOL PHP/framework floor, and explicit non-maintenance. Present this as a hard no with evidence, not as an engineering preference.

Sequencing

• Spike → schema review → invariant test suite → service implementation → feature integration. Keep it as one short cycle owned by a single engineer who has read the bundle. Do not slot it behind other work as a "quick win" — it is small and self-contained, and delaying it delays the roadmap item it unblocks.

Operational Impact

Maintenance

• If adopted: a permanently unmaintained dependency that implicitly freezes PHP and Laravel upgrades for as long as it is installed. Every future Laravel major becomes a manual patch against dead code — an open-ended tax with no owner upstream.
• If used as reference only: zero ongoing maintenance burden from the package. Ownership transfers to our own ~200-line Eloquent implementation, well within normal team capability.

Support

• No maintainer, no issue triage, no security advisories. Internal support would be "whoever read the code last" — unacceptable on any critical path.
• Zero dependents means no external knowledge base: no Stack Overflow answers, no fork lineage, no write-ups of production failure modes. Onboarding cost is entirely ours.

Scaling

• The bundle imposes nothing on scaling because it never runs. The pattern it encodes — a wide pivot table with polymorphic keys — scales adequately into the low tens of millions of edges with proper indexing. Beyond that, symmetric relations need either double-write discipline or a canonical-ordering trick (store each undirected edge once, ordered by id) to halve rows and eliminate duplicate-edge bugs.
• Traversal is the watch item: recursive "friends of friends" joins degrade quickly. If that query is on the roadmap, budget for a closure table or precomputed edge cache — neither of which the bundle provides.

Failure modes

• Silent data divergence: bidirectional relations written from one side only, leaving the graph inconsistent. Mitigate with a single write path plus a symmetry-reconciliation job.
• Polymorphic orphan rows: pivots pointing at deleted entities. morphToMany does not enforce FK integrity across types — mitigate with application-level cleanup and a periodic integrity sweep.
• Duplicate edges under concurrency: two simultaneous request writes. Mitigate with the composite unique index and idempotent upserts.
• Porting drift: Doctrine cascade/dirty-tracking assumptions imported by engineers expecting Eloquent to match. Mitigate by writing the invariant tests first.

Ramp-up

• Low for the reimplementation: a mid-level Laravel engineer can build and own this in under a week.
• Misleadingly low for the bundle itself — the small surface area invites underestimation, and the Symfony 2 bootstrap requirement surfaces only at integration time, after effort is already spent.

Recommendation: Reject as a dependency; archive the repository link in the design doc as prior art. Budget a short spike to extract the relation schema and invariants, then build the polymorphic pivot in Eloquent behind a tested single write path. The package's durable value is the problem framing, and that is worth roughly a day of reading.