Getting Started

Install with composer require laravel-interaction/interactions and pin ^1.0 now that 1.0.0 is the first stable release.
Publish and run the package migrations before using any interaction methods: php artisan vendor:publish --tag="interactions-migrations" then php artisan migrate. Publish config if the package exposes it.
Look first at the package README, config file, migrations, and tests. For a 1.0.0 release, the tests are the best source of truth for exact method names and supported interaction flows.
Add the package trait to models that can be interacted with, and the interactor trait to your user/actor model. Typical first use case: letting an authenticated user like, bookmark, or react to a Post.
Start with one interaction type end-to-end — create, toggle, count, and list — before adding multiple types or custom metadata.

Implementation Patterns

Use the package’s trait on interactable models and keep interaction types as stable string keys or enums so queries and reporting remain consistent.
For day-to-day UI, wrap toggles in controller actions or form requests and return the updated count/state so the frontend can update without a full reload.
Eager load interaction counts when listing models to avoid N+1 queries. Prefer package-provided count scopes/accessors over ad-hoc withCount unless you need custom filtering.
Use authorization policies or gates around interaction actions; the package records interactions, but your app should still decide who may interact with what.
For dashboards, query interaction summaries by type and date range. Keep aggregate queries in dedicated query objects or repository methods rather than scattering them across controllers.
Dispatch domain events or listeners after interactions if you need notifications, activity feeds, or analytics. Keep side effects queued where possible.
In APIs, expose interaction state as part of the resource: is_liked, likes_count, or a small interactions summary. Use API resources to keep response shape consistent.
For bulk or high-volume interactions, consider jobs or batched inserts, but preserve the package’s uniqueness rules and event semantics.

Watch for duplicate interactions. The package likely enforces uniqueness via migration indexes; confirm the index exists and handle duplicate-toggle races gracefully.
Configure morph maps before storing polymorphic interactions. Changing class names later can orphan records.
Be careful with soft deletes: decide whether deleted models’ interactions should remain, cascade, or be excluded from counts.
Run php artisan config:clear after changing package config, and remember that config:cache can hide new config keys.
Counts can drift if you write interactions outside the package API. Prefer package methods over manual inserts/updates.
Interaction toggles are not automatically safe under concurrent requests. Use transactions or unique constraints where double-submits are possible.
Test with factories for both the interactor and interactable models, and cover duplicate interaction, toggle-off, and count updates.
Use the package’s extension points — custom interaction types, model traits, events, or config — before forking. Since 1.0.0 is the first stable release, keep an eye on future minor releases for additive features rather than assuming undocumented behavior.