Eloquent Interactions Laravel Package

Getting Started

Start by confirming your application is on Laravel 7–10 and PHP version compatible with the package. v1.0.0 is primarily a compatibility/stabilization major release; the release notes do not advertise new features, so treat it as the first stable baseline for supported Laravel versions.

Minimal path:

1. Install with a v1 constraint: composer require zachflower/eloquent-interactions:^1.0.
2. Publish package assets/migrations via vendor:publish, then inspect the published config and migration before running php artisan migrate.
3. Read the package README first, then look at the interaction model, traits, and migration schema. These define the day-to-day API more than the release notes do.
4. Attach the package’s interaction trait(s) to the acting model, typically User, and to the target model, typically something like Post.
5. Build the smallest use case: a user likes/unlikes a post, then verify the interaction record, relationship access, and count query in tinker or a feature test.

If upgrading from 0.2.0, pin ^1.0, clear config/cache, run the full test suite, and check for breaking changes even though the changelog is sparse.

Implementation Patterns

Treat interactions as domain records rather than ad hoc controller logic. Put create/remove/toggle behavior behind a small action or service class, and authorize it with Laravel policies before writing.

Common patterns:

• Use the package traits on both sides of the relationship: the actor model and the interactable model.
• Keep allowed interaction types centralized in config, an enum, or a small registry so controllers do not hard-code strings like like, favorite, or bookmark.
• Enforce uniqueness at the database level for actor + target + interaction type, and handle duplicate attempts gracefully.
• For APIs, expose toggle/delete endpoints and return updated counts through an API resource rather than querying counts per item in the controller.
• Eager load interaction relationships or use withCount-style queries for lists to avoid N+1 queries.
• Fire domain events after successful interactions if you need notifications, activity feeds, or analytics.
• In tests, use RefreshDatabase and factories to create actors, targets, and interaction records explicitly.

A practical first implementation is a “like” feature on posts: trait on User, trait on Post, a policy check, a unique index, a toggle endpoint, and a feature test covering duplicate likes and count changes.

Gotchas and Tips

• v1.0.0 is a major version bump. Even with a short changelog, verify behavior when upgrading from 0.2.0 and run integration tests around interaction creation, deletion, and counting.
• Laravel 11+ is not advertised in this release. Do not assume support outside Laravel 7–10 without checking package constraints.
• Publish and review migrations before running them. Table names, morph columns, and indexes may conflict with existing application tables.
• If the package uses polymorphic relations, watch morph map configuration and column lengths. Inconsistent morph aliases can produce hard-to-debug relationship failures.
• Clear config cache after changing package config: php artisan config:clear and, in deployment, rebuild caches deliberately.
• Interaction counts can drift if records are deleted outside the package API or if soft deletes are involved. Use transactions for toggle operations and consider cached counters only with a rebuild strategy.
• Prefer package extension points such as custom models, type resolvers, or config overrides over editing vendor files.
• Add tests for duplicate interactions, authorization failures, deletion, and list/count queries; these are the areas most likely to break during a major upgrade.