Quick start
From an empty install to a trending list in five steps. Each one links to the page that covers it in full.
1. Install
Section titled “1. Install”composer require cyrildewit/eloquent-viewable:^9php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"php artisan migrateSee Installation for publishing the config and for models keyed by a UUID or ULID.
2. Make a model viewable
Section titled “2. Make a model viewable”use Illuminate\Database\Eloquent\Model;use CyrildeWit\EloquentViewable\Concerns\InteractsWithViews;use CyrildeWit\EloquentViewable\Contracts\Viewable;
class Post extends Model implements Viewable{ use InteractsWithViews;}3. Record a view
Section titled “3. Record a view”Add the views middleware to the route that shows the model. It records a view for every successful GET, and the
cooldown keeps a reader who refreshes the page from counting twice:
use CyrildeWit\EloquentViewable\Http\Middleware\RecordViews;
Route::get('/posts/{post}', ShowPost::class) ->middleware(RecordViews::using('post', cooldown: 30));Or call views($post)->record() in the controller. Crawlers, prefetches and HEAD requests are dropped either way.
See Recording views and
Cooldowns.
4. Count and chart
Section titled “4. Count and chart”use CyrildeWit\EloquentViewable\Support\Granularity;use CyrildeWit\EloquentViewable\Support\Period;
views($post)->count(); // every viewviews($post)->unique()->period(Period::pastDays(7))->count(); // unique visitors this week
$trend = views($post)->period(Period::pastDays(7))->compare();$trend->percent; // 17.2, against the week before
$series = views($post) ->period(Period::pastDays(30)) ->remember(60) ->countByInterval(Granularity::Day);
$series->labels(); // ['2026-09-01', '2026-09-02', ...]$series->values(); // [14, 22, ...]See Retrieving counts and Caching.
5. Rank
Section titled “5. Rank”Post::orderByViews()->paginate(); // most viewed first
foreach (views(Post::class)->trending(10) as $entry) { $entry->viewable; // the post $entry->count; // its views lately}See Ordering and filtering and Trending.
- Run
php artisan views:doctorto check the setup. - Read Testing before you write the first test that records a view.
- Browse the recipes for complete features built from these pieces.