Recording views
Record a view in the controller method that shows the model:
public function show(Post $post){ views($post)->record();
return view('post.show', compact('post'));}record() returns true when the view was stored or queued and false when a guard refused it. The guards are listed
under recording.guards in the config. Out of the box they drop crawlers, requests without a user agent, HEAD
requests, browser prefetches, bursts of views from one visitor and the addresses in recording.ignored_ip_addresses,
and enforce cooldowns. See
the guards for the ones you can turn on, or add your own.
Recording from a route
Section titled “Recording from a route”Or leave the controller alone and add the views middleware to the route:
Route::get('/posts/{post}', ShowPost::class)->middleware('views');It records the last route parameter bound to a Viewable model, and only for a successful response to a GET
request, so a 404, a redirect or a form post records nothing. Name a parameter or a model class to pick another, and
pass options the same way:
use CyrildeWit\EloquentViewable\Http\Middleware\RecordViews;
->middleware('views:user') // the {user} parameter->middleware(RecordViews::using(Post::class)) // every parameter bound to a Post->middleware(RecordViews::using(['user', 'post'])) // both->middleware(RecordViews::using('post', collection: 'amp', cooldown: 30, queue: true))A parameter that does not resolve to a Viewable throws InvalidViewable on the first request. A failed write is
reported and the page is still sent. For a condition, a viewedBy() or a context(), call views() in the controller.
Recording from the browser
Section titled “Recording from the browser”A page served from a full-page cache, such as spatie/laravel-responsecache, Cloudflare or Varnish, never reaches your
controller, so neither record() nor the middleware runs. Turn on the beacon and let the browser record the view:
'recording' => [ 'beacon' => [ 'enabled' => true, ],],@viewsBeacon($post)@viewsBeacon($post, collection: 'amp', cooldown: 30, queue: true)Once the page has loaded, or a prerendered page is shown, its script posts to a signed URL and the view passes the same
guards as record(). The URL is the same for every visitor, never expires and is signed without the host, so it is safe
to cache with the page and behind a proxy.
- Same origin only. The route runs the
webgroup, so cooldowns, the visitor cookie and the signed-in viewer work as usual, and the cookie is set on the beacon’s response rather than the cached page. Laravel’s CSRF check accepts the beacon through the browser’sSec-Fetch-Siteheader and refuses posts from other sites. Browsers that do not send it, such as Safari before 16.4, are not counted. - A neutral path. The route lives under
/_ev, because privacy filter lists block paths such as/beaconor/track. Changeprefixif it collides with a route of your own, andmiddlewareto run other middleware. - Quiet answers. A changed URL gets a
403, a deleted model a404and everything else a204, also when a guard skips the view. - Live counts.
@viewsBeacon($post, live: true)also keeps the visitor active while the page is open, see who is looking right now. - Your own script. For a single-page app, build the URL with
app(\CyrildeWit\EloquentViewable\Http\Beacon::class)->url($post, collection: 'amp'). - Morph map. The URL names the model by its morph class. Call
Relation::enforceMorphMap()to showpostinstead ofApp\Models\Post.
Finding out why a view was not recorded
Section titled “Finding out why a view was not recorded”attempt() records like record() but returns a Recording\Data\RecordResult:
use CyrildeWit\EloquentViewable\Recording\Guards\EnforceCooldown;
$result = views($post)->attempt();
$result->recorded; // true when the view was stored or queued$result->queued; // true when the write was handed to the queue$result->skippedBy; // the guard that refused the view, or null
$result->wasSkippedBy(EnforceCooldown::class);Each refusal also dispatches Recording\Events\ViewSkipped with the attempt and the guard, so you can log skipped views
without touching the code that records them.
Every attempt, stored, queued or skipped, also dispatches Recording\Events\ViewAttempted with the attempt and its
RecordResult. It fires in the request that made the attempt, also when the write is queued. The package only builds
the event when something listens to it, so it costs nothing otherwise.
Seeing it in Debugbar and Telescope
Section titled “Seeing it in Debugbar and Telescope”With Laravel Debugbar 4.4 or newer installed, a Viewable tab lists
every view of the request: the ones stored, the ones queued and the ones skipped, with the guard that refused each,
the collection, the viewer and the context. Nothing to set up: the tab appears whenever Debugbar is collecting. To
leave it out, turn it off in config/debugbar.php:
'collectors' => [ // ... 'eloquent_viewable' => false,],Laravel Telescope needs nothing either. Its events watcher records
ViewAttempted and ViewSkipped like any other event of your application, with the guard named by its class.