Interactions Laravel Package

Technical Evaluation

Architecture fit laravel-interaction/interactions is a lightweight polymorphic relationship package: it adds trait-based behavior to Eloquent models so any model can "interact" with any other model (like, bookmark, subscribe, vote, or custom types), backed by a single interactions table and a corresponding Interaction model. It is a domain-adjacent convenience layer, not infrastructure. For a product with social or engagement features (reactions, follows, favorites, saved items), it removes roughly a sprint of bespoke schema, trait, and query-scope work. For products without such features, or where interactions are a first-class domain (feed ranking weights, moderation states, audit trails, event-sourced engagement), the package's abstraction is likely too thin and we would end up extending or forking it — a signal to build in-house instead.

Integration feasibility Low effort. Standard Composer install, publish and run the migration, add the trait to participating models, and optionally configure the interaction type set. No service provider configuration of consequence, no external services, no credentials, no queue or scheduler dependencies. The realistic scope is a few hours of implementation plus test coverage, dominated by deciding which models participate and enforcing uniqueness semantics on the pivot rather than by the package itself.

Technical risk This release (3.5.0) is additive and low-risk. The substantive changes are forward-compatibility widening:

• Laravel 13 support (PR #226)
• PHP 8.5 support (PR #216)
• PHPUnit 12 support (PR #206)
• orchestra/testbench constraint update (PR #223)

Approximately twenty of the twenty-four listed PRs are Dependabot bumps to GitHub Actions and the license year — CI-only, zero runtime footprint. There are no documented breaking changes, deprecations, or API modifications; on semver grounds 3.5.0 should be a drop-in for 3.4.x. The risk that matters is not this diff but the surrounding context:

• Ecosystem-timing risk. Laravel 13 and PHP 8.5 support were added proactively. That is a strong maintenance signal, but it also means our own platform (framework, CI image, static analysis, test tooling) may be the constraint, not the package.
• Single-maintainer concentration. Bus factor of one (@zingimmick). Acceptable for a leaf utility package; not acceptable if it becomes load-bearing infrastructure.
• Abstraction ceiling. Custom interaction types are string-keyed; complex engagement rules (weighting, expiry, rate limits, moderation) live outside the package and must be built by us regardless.

Key questions

1. Do our target Laravel and PHP versions actually fall inside the newly widened constraints, and does the maintainer's tested matrix match our production runtime (not just the CI matrix)?
2. Does 3.5.0's diff contain any schema or migration changes? If none, the upgrade is composer-constraint-only and can be treated as a lockfile bump.
3. What is the expected write volume on the interactions table, and does the package ship (or do we need to add) a unique constraint to prevent duplicate interactions from a single actor?
4. Are interactions ever deleted, and does the package handle cascade cleanup on parent model deletion, or do we need an explicit purge job?
5. Is our product's engagement model simple enough to sit inside this package, or is it a candidate for a first-party implementation once moderation, notifications, and analytics enter scope?

Integration Approach

Stack fit Native fit for a conventional Laravel monolith or modular monolith on Eloquent. It composes cleanly with policies, gates, API resources, and broadcasting — interactions map naturally to events we may want to fire for notifications or feed invalidation. Poor fit for multi-database or sharded setups, for teams using raw query builders or a non-Eloquent data layer, or for architectures where engagement is written through an event bus rather than synchronous model writes.

Migration path

1. Pin the current known-good version and record it in the dependency decision log.
2. Treat 3.5.0 as a constraint widening: bump laravel-interaction/interactions to ^3.5 in an isolated PR, with no application code changes.
3. Run the migration on a scratch environment and diff the resulting schema against production to confirm no new columns or tables.
4. Only after that, and only if we are moving to Laravel 13 or PHP 8.5, treat those as separate platform upgrades with their own assessment.

Compatibility Backward compatible with the 3.x line per semver; no deprecations announced. Downstream compatibility is the real variable: PHPUnit 12 support implies a test-suite upgrade path, and PHP 8.5 support implies runtime adoption — each should be gated independently so a failing test suite cannot be mistaken for a package defect. Verify that our PHPStan/Psalm and Rector baselines understand the widened constraints before merging.

Sequencing Dependency bump first (safe, reversible, one-line) → verify green CI on the existing runtime → schema-drift check → platform upgrades (PHP, then Laravel, then PHPUnit) in separate changes → feature adoption only after the package is proven stable in a non-critical path. Do not bundle the platform upgrade with the feature that motivated the package; those are two different risk profiles and should have two different rollback stories.

Operational Impact

Maintenance Minimal. No migrations to manage beyond the initial publish, no configuration surface to keep in sync, no runtime services to babysit. The cost is upgrade hygiene rather than operations: expect a steady cadence of releases that are 80–90% bot noise, so triage should be "read the non-Dependabot PRs, skim the rest." Budget roughly one dependency-review cycle per quarter, plus a short verification whenever Laravel, PHP, or PHPUnit has a major release.

Support Upstream is a single active maintainer with responsive turnaround on ecosystem releases — evidenced here by same-cycle support for Laravel 13, PHP 8.5, and PHPUnit 12. That is better than many two-person projects. The trade-off is no vendor SLA and no commercial escalation path: if the maintainer steps away, we own the code. Mitigation is cheap for a package this size — keep the trait surface we depend on thin, avoid forking internals, and be prepared to vendor it.

Scaling The package itself does not scale; the table does. Interactions are inherently high-write and high-growth: rows ≈ actors × targets × types, which for even moderate traffic reaches tens of millions quickly. Operational prerequisites, all outside the package's control:

• Composite index on (interactionable_type, interactionable_id) and a separate index on the actor column.
• A unique constraint on (actor, interactionable, type) to make the write path idempotent and prevent duplicate rows under retry.
• Cached or denormalized counters for anything rendered in a list; do not COUNT(*) per row on read.
• A retention/archival policy for historical interactions if we ever surface them as an audit log.

If those are not in place, the package will look fine in staging and become a slow query in production.

Failure modes

• Duplicate interactions from concurrent or retried writes without a unique constraint — surfaces as inflated counts, not errors, so it degrades silently.
• Orphaned rows when a parent model is deleted without cascade cleanup or a purge job.
• Counter contention under high write concurrency if counts are maintained in a single hot row.
• N+1 queries when loading interaction state for a collection of models without eager loading the relationship.
• Upgrade misattribution — a red CI run after a platform bump read as a package regression, when it is the test suite or PHPStan that needs updating.
• Abstraction overrun — team extends the package with custom types and business logic until it is a de facto forked dependency with none of the fork's control.

Ramp-up Very low: an engineer unfamiliar with the package is productive within a day using the published docs and the shipped migration. The real ramp-up cost is reviewer-level: someone must own the decision of which models participate, what the interaction type vocabulary is, and what the uniqueness and retention guarantees are, then encode those as tests. That owner should be named before adoption, not after the first duplicate-count incident.