- How do I install cyrildewit/eloquent-viewable in a Laravel application?
- Install it with Composer using composer require cyrildewit/eloquent-viewable, then publish the package migrations and optionally the config file. Run php artisan migrate to create the polymorphic views table. There is no external service, API key, or queue requirement, so setup is a few commands and no infrastructure change.
- Which Laravel and PHP versions does eloquent-viewable support?
- The documented matrix has version 7 supporting Laravel 6 through 13 on PHP 7.4 and above, while version 8 targets Laravel 13 and PHP 8.5 and above. Check the matrix before upgrading your Laravel or PHP line, because the major version you can use depends on it. Lumen is not supported, so this package fits standard Laravel applications only.
- How do I add view tracking to an Eloquent model?
- Add the InteractsWithViews trait to the model and implement the Viewable contract. That is the only model-level change needed. You then record a view anywhere in your application with views($post)->record(), and read counts back through the same fluent helper.
- How do I get unique view counts instead of total views?
- Call unique() in the query chain, for example views($post)->unique()->count(). Unique views are derived by the package's visitor identification and duplicate suppression rather than by a separate visitors table. Validate that derivation against your session topology and any privacy or consent requirements before treating it as a legal unique-user metric.
- How does the cooldown feature work in eloquent-viewable?
- You can chain cooldown($minutes) before record() so repeat views from the same visitor within the window are not stored. Duplicate suppression is session-backed: the package stores a snapshot in the visitor's session. That works for classic browser sessions, but counts can inflate silently for stateless API clients, multi-device users, or load-balanced apps without a shared session store.
- Can I queue view recording, and what changes when I do?
- Yes, queueing is opt-in and can be enabled per call or globally. The important consequence is that the ViewRecorded event then fires from a queue worker with no request context, so session, cookies, request(), and auth()->user() are empty. Any listener that needs the user or IP must capture it during the request before the job runs.
- Why are my views not being recorded when I test with Postman?
- Crawler detection is aggressive by default and treats Postman and similar tooling as crawlers, so views are silently skipped. QA and acceptance tests will look broken unless this behavior is documented or the crawler detector is customized or disabled for those environments. The package exposes a custom crawler detector as an extension point.
- How do I count views for a specific period, such as the last 30 days?
- Use the Period helper with the fluent query, for example views($post)->period(Period::pastDays(30))->count(). The one-row-per-view design makes these time-window queries and unique counts possible without a separate aggregation job. You can combine period with unique() when you need unique views within that window.
- Is orderByViews safe to use on a large views table?
- It works, but orderByViews and orderByUniqueViews translate to correlated subqueries, which become a latency cliff on a mature views table. Use them on admin or editorial surfaces where possible, and add careful indexing and caching before putting sort-by-views on a user-facing listing. This is an operational query-performance concern rather than a package bug.
- What are the production and maintenance risks of adopting eloquent-viewable?
- The main risk is data growth: there is no documented first-class pruning or retention feature, so your team owns partitioning, archival, or a scheduled delete job for the polymorphic views table. The package also has a single maintainer and no listed dependents, so treat it as a dependency you may need to fork or vendor. Cooldown session semantics and queued event context are the two integration details most likely to cause defects.