Upgrade guide
The version upgrade guides for versions below v7.0.3 are still accessible in the major version branches like 7.x.
Upgrading from v8.0.0 to v9.0.0
Section titled “Upgrading from v8.0.0 to v9.0.0”The requirements are PHP 8.5 and Laravel 13, as before, and Carbon 3.11 or newer. Run composer update nesbot/carbon if
your lock file holds an older Carbon 3. On MySQL, version 9 needs MySQL 8.0 or newer, because the rollups of a dimension
rank its values with a window function. MariaDB, Postgres and SQLite have one on every version Laravel supports. Most
applications only need the five steps below. The sections after them cover behaviour changes to be aware of and what to
change if you extended the package.
What’s new in 9.0
Section titled “What’s new in 9.0”- Record from a route with the
viewsmiddleware, without touching the controller. - Dashboards out of the box: counts per hour, day, week, month or year with
countByInterval(), a comparison with the previous period withcompare(), and periods read from a URL withPeriod::parse(). - Rankings of the most viewed content across every model with
Views::top(), andwhereViewsCount()to filter by views. - Who is looking right now: live visitor counts and a ranking of what is being read, kept in Redis and refreshed by a heartbeat from the page.
- Who viewed what: link views to the signed-in user and ask what they have or have not seen.
- Where views came from: count views by source, medium, campaign, device, country or a value of your own with
countBy(), and narrow any count withwhereDimension(). - Scale when you need to: buffer views in Redis and land them in batches, count a page of models in one query, and forget cached counts on demand.
- Privacy: count unique visitors without a cookie, honour Global Privacy Control, let a signed-in user opt out of recording and skip prefetched pages.
- Bots: refuse bursts of views from one visitor, and delete the bot views already in your table with
views:purge-bots. - Testing:
Views::fake()with assertions, and a factory for theViewmodel. - Extension points: your own recording guards, stores, count sources and cooldown stores.
See the documentation for each of them.
1. Update the package
Section titled “1. Update the package”composer require cyrildewit/eloquent-viewable:^9If you queue views, with queue.enabled in your v8 config or ->queue() on a call, let the queue empty before you
deploy, for example with php artisan queue:work --stop-when-empty. Jobs queued by v8 cannot run on v9: they fail and
their views are lost.
2. Update your imports
Section titled “2. Update your imports”Most classes moved into a namespace per module. Search your code for CyrildeWit\EloquentViewable\ and update each
import:
| v8 | v9 |
|---|---|
InteractsWithViews |
Concerns\InteractsWithViews |
View |
Models\View |
ViewsFacade |
Facades\Views |
Visitor |
Visitors\Visitor |
Contracts\Visitor |
Visitors\Contracts\Visitor |
Contracts\CrawlerDetector |
Crawlers\Contracts\CrawlerDetector |
CrawlerDetectAdapter |
Crawlers\Detectors\CrawlerDetectAdapter |
CooldownManager |
Cooldowns\CooldownManager |
CacheKey |
Querying\Cache\CacheKey |
PendingView |
Data\ViewRecord |
Events\ViewRecorded |
Recording\Events\ViewRecorded |
ViewableObserver |
Recording\Observers\ViewableObserver |
Actions\CreateView |
Recording\Actions\RecordView |
Contracts\CreateView |
Recording\Contracts\RecordsViews |
Jobs\StoreView |
Recording\Jobs\RecordViewJob |
Exceptions\ViewRecordException |
Recording\Exceptions\RecordingFailed |
Views, Contracts\Viewable, Support\Period and Exceptions\InvalidPeriod did not move. Contracts\View and
Contracts\Views are gone, see Custom View model and Custom Views class.
In your tests, Bus::assertDispatched(StoreView::class) becomes Bus::assertDispatched(RecordViewJob::class).
3. Publish the config again
Section titled “3. Publish the config again”The config is now grouped by module, and a v8 config does not work with v9. Publish the new file over your old one, keeping a copy of the old one, or relying on git, so you can carry your values over:
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="config" --forceThen copy each value you changed in v8 to its new place:
| v8 | v9 |
|---|---|
models |
models, unchanged |
cache |
querying.cache |
queue |
recording.queue |
ignored_ip_addresses |
recording.ignored_ip_addresses |
visitor_cookie_key |
visitor.cookie.name |
cooldown.key |
cooldown.key |
ignore_bots => false |
remove IgnoreCrawlers from recording.guards |
honor_dnt => true |
add IgnoreDoNotTrack to recording.guards |
Start from the published file rather than adding the new keys to your v8 one. Each top-level block is read as a
whole, so a block that is missing keys throws InvalidConfiguration naming the first one.
Run php artisan views:doctor once the config is in place. It fails on any v8 key still in the file, and on a
cooldown block without a store, and names where each value goes.
Config values are now validated when they are read, so a connection, table, queue or cache store given as anything
other than a string or null throws InvalidConfiguration naming the key.
4. Add the new columns, indexes and tables
Section titled “4. Add the new columns, indexes and tables”The views table needs three new nullable columns, viewer_type, viewer_id and context, because every view
writes them. A composite index on viewable_type, viewable_id and viewed_at lets period counts read only the rows
inside the period, and an index on viewed_at serves retention and rollups, which scan by date across every viewable.
Your published migration has already run, so add them in a migration of your own:
<?php
use Illuminate\Database\Migrations\Migration;use Illuminate\Database\Schema\Blueprint;use Illuminate\Support\Facades\Schema;
return new class extends Migration{ public function up(): void { $table = config('eloquent-viewable.models.view.table_name');
Schema::connection(config('eloquent-viewable.models.view.connection')) ->table($table, function (Blueprint $blueprint) use ($table) { $blueprint->nullableMorphs('viewer'); // nullableUuidMorphs or nullableUlidMorphs to match your user model $blueprint->json('context')->nullable(); $blueprint->index(['viewable_type', 'viewable_id', 'viewed_at'], "{$table}_viewable_viewed_at_index"); $blueprint->index('viewed_at', "{$table}_viewed_at_index"); }); }
public function down(): void { $table = config('eloquent-viewable.models.view.table_name');
Schema::connection(config('eloquent-viewable.models.view.connection')) ->table($table, function (Blueprint $blueprint) use ($table) { $blueprint->dropIndex("{$table}_viewable_viewed_at_index"); $blueprint->dropIndex("{$table}_viewed_at_index"); $blueprint->dropMorphs('viewer'); $blueprint->dropColumn('context'); }); }};On a large table, building an index locks writes while it runs. MySQL 8 and MariaDB 10.5 build it online. On
Postgres, use CREATE INDEX CONCURRENTLY with public $withinTransaction = false; on the migration.
If your table dates from version 7, its visitor column may still be text. Counting works on it, but MySQL and
MariaDB cannot index a text column, so change it to a string before you add an index that includes visitor, such
as the ones views:doctor recommends:
$blueprint->string('visitor')->nullable()->change();Nothing is recorded in the new columns until you opt in to recording the viewer or pass a context.
Version 9 also adds the tables of retention, rollups, pairs, milestones and spikes. Publish the migrations again and run them:
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"php artisan migrateYour views migration is skipped when its file is still in database/migrations, and the five new ones are published.
If you squashed your migrations with schema:dump --prune, or moved or renamed that file, a new create_views_table
migration is published too. Delete it before you migrate, since your table already exists. The features stay off until
you configure them, so you can delete the migration of one you will not use before running it.
Dimensions add no column until you list one. After listing one under
dimensions.definitions, run php artisan views:dimensions, which writes the migration that adds its column, and
migrate. If you publish the config by hand, add dimensions to retention.anonymise.columns, so anonymising clears
the dimensions marked personal.
5. Replace $removeViewsOnDelete with a method
Section titled “5. Replace $removeViewsOnDelete with a method”// Beforeprotected $removeViewsOnDelete = false;
// Afterpublic function shouldRemoveViewsOnDelete(): bool{ return false;}A model that implements Viewable without the InteractsWithViews trait has to add the method.
Behaviour changes to check
Section titled “Behaviour changes to check”Periods are half-open
Section titled “Periods are half-open”A Period now includes its start and excludes its end, so Period::create('2018-01-01', '2018-02-01') is January and
Period::upto($date) means before $date. A count whose period ends exactly on a stored viewed_at drops by one.
Bounds built in another timezone are converted to app.timezone before they are compared, and getStartDateTime()
and getEndDateTime() return the converted values.
Prefetches, HEAD requests and requests without a user agent are not counted
Section titled “Prefetches, HEAD requests and requests without a user agent are not counted”Three new guards are on by default. IgnorePrefetch drops pages the browser only fetched in advance, so sites that use
prefetching or speculation rules see lower counts. IgnoreHeadRequests drops HEAD requests, such as uptime monitors.
IgnoreMissingUserAgent drops requests without a user agent, such as scripts and health checks; if you record views
from a client that sends none, remove it from recording.guards.
Bursts of views are not counted
Section titled “Bursts of views are not counted”IgnoreBursts is on by default. A visitor that opens more than 8 different models within 2 seconds is refused, and so
is every view of theirs for the next 2 minutes. Scrapers that pass for a browser stop counting, so sites with a lot of
bot traffic see lower counts. The count is also kept per network and user agent, which people behind one office or
carrier address share. If your readers come from such a network, set recording.bursts.by to ['visitor']; to turn
the guard off, remove it from recording.guards. If you record views in bulk from your own code, such as an import,
remove the guard for that run or use View::factory(). Run views:purge-bots --dry-run to see how many bot views your
table already holds.
Every facade call starts a fresh builder
Section titled “Every facade call starts a fresh builder”The Views facade used to reuse one builder for the whole request, so options leaked from one call into the next.
Keep a chain on one line, or hold the builder in a variable:
// Before: counted $post through the leaked viewable. Now: throws InvalidViewable.Views::forViewable($post)->record();Views::count();
// After$views = Views::forViewable($post);$views->record();$views->count();Views::shouldReceive() and Views::swap() work as before.
View model events no longer fire when a view is recorded
Section titled “View model events no longer fire when a view is recorded”Views are written through the query builder, so creating and created observers on the View model stop running.
Listen for Recording\Events\ViewRecorded instead, see below.
Caches and cooldowns reset once
Section titled “Caches and cooldowns reset once”Counts cached with remember() are recalculated once after upgrading, because the cache key changed. Cooldowns
running at deploy time end early, once, because the session format changed.
If you extended the package
Section titled “If you extended the package”ViewRecorded listeners
Section titled “ViewRecorded listeners”The event carries a Data\ViewRecord as $record instead of the model as $view, and no longer uses
SerializesModels:
// Before$event->view->viewable_id;
// After$event->record->viewableId;$event->record->viewableType::find($event->record->viewableId);With the Redis buffer the row does not exist yet when the event fires, so read what you need from the record.
Custom recording action
Section titled “Custom recording action”Bind it to Recording\Contracts\RecordsViews. handle() receives a ViewRecord and returns void:
// Beforepublic function handle(PendingView $pending): View
// Afterpublic function handle(ViewRecord $record): voidTo only change where views are written, register a store instead.
Custom View model
Section titled “Custom View model”Contracts\View is gone. Extend Models\View, name the class in the config and remove the container binding:
'models' => [ 'view' => [ 'class' => \App\Models\View::class, ],],A $table or $connection property on your model now wins over table_name and connection in the config.
Custom Views class
Section titled “Custom Views class”Contracts\Views is gone and Views can no longer be replaced through the container. Type-hint Views instead, and
move your changes into a macro, a recording guard, a
store or a source. A
subclass that overrides the constructor needs the new arguments: the visitor, Recording\Recorder, Querying\Reader,
Recording\Actions\DestroyViews, Querying\Cache\CacheVersions, Dimensions\DimensionRegistry, Presence\LiveViews and
the container.
Viewable without InteractsWithViews
Section titled “Viewable without InteractsWithViews”scopeOrderByViews() and scopeOrderByUniqueViews() on Contracts\Viewable take a last argument,
array $dimensions = []. A model that implements Viewable without the trait adds it to both signatures.
Custom Visitor
Section titled “Custom Visitor”The contract changed:
isCrawler()is gone. AdduserAgent(): ?stringand returnnullwhen there is none.- Add
viewer(): ?Model, the signed-in model ornull. - Add
hasGlobalPrivacyControl(): boolandisPrefetch(): bool. Returnfalsewhen the request has no such header. - Add
isHeadRequest(): bool, which istruefor aHEADrequest.
A subclass of the shipped Visitor that overrides its constructor drops the CrawlerDetector argument and passes
Request, Support\Config, Illuminate\Contracts\Cookie\QueueingFactory and Illuminate\Contracts\Auth\Factory, in
that order.
The Visitor::DNT constant is now Visitor::DoNotTrackHeader.
Custom CrawlerDetector
Section titled “Custom CrawlerDetector”The detector now receives the user agent instead of reading the request:
// Beforepublic function isCrawler(): bool
// Afterpublic function isCrawler(?string $userAgent): boolCooldownManager
Section titled “CooldownManager”Cooldowns\CooldownManager now resolves the cooldown store named in cooldown.store, and is final. push() is gone:
start a cooldown with views($viewable)->cooldown($expiresAt)->record(), and to keep cooldowns somewhere else,
add a store.
CacheKey and RecordViewJob
Section titled “CacheKey and RecordViewJob”CacheKey::make(?Period $period, bool $unique, ?string $collection) is now
CacheKey::make(ViewsQuery $query, ?Granularity $granularity = null, ?string $grouping = null, ?int $limit = null).
The constructor takes the morph class and key of the viewable, the cache-key prefix and the identity of the source.
The entry under a key no longer holds the bare count. It holds the count together with the versions forgetCache() and
flushCache() replace, so read counts through views() rather than from the cache store.
RecordViewJob::dispatch() is gone. Use dispatch(new RecordViewJob($record)).
Upgrading from v7.0.3 to v8.0.0
Section titled “Upgrading from v7.0.3 to v8.0.0”Check requirements
Section titled “Check requirements”This release raises the minimum requirements. Make sure your application meets all of them before upgrading:
- PHP
^8.5(was^7.4 || ^8.0) - Laravel 13 only — the
illuminate/*dependencies are now constrained to^13.0. Support for Laravel 6 through 12 has been dropped. - Carbon
^3.0only. Support for Carbon 2 has been dropped.
visitor column type
Section titled “visitor column type”The create_views_table migration stub now defines the visitor column as a string (VARCHAR(255)) instead of text, so it can be indexed directly (for example to speed up ->unique() counts).
This only affects newly published migrations. If you have already run the migration, no change is required — everything keeps working on the existing text column. If you want to adopt the new type on an existing table, add a migration:
Schema::table('views', function (Blueprint $table) { $table->string('visitor')->nullable()->change();});Note that on large tables this rewrites the table, and any visitor value longer than 255 characters would be truncated (the built-in visitor identifier is 80 characters).
Config defaults for connection and cache store
Section titled “Config defaults for connection and cache store”The default config now uses null for models.view.connection and cache.store instead of reading env('DB_CONNECTION') and env('CACHE_DRIVER'). A null value defers to the application’s default database connection and default cache store.
This only affects newly published config. If you have already published config/eloquent-viewable.php, your copy still contains the old env() calls and keeps working. Two things to be aware of when adopting the new defaults:
CACHE_DRIVERwas renamed toCACHE_STOREin Laravel 11. If your published config still readsenv('CACHE_DRIVER', 'file')while your app only setsCACHE_STORE, view counts are cached to thefilestore regardless of your configured cache. Settingcache.storetonull(orenv('CACHE_STORE')) resolves this.- Switching
cache.storetonullmeans view counts are cached in your application’s default cache store. If you relied on the previousfilefallback, setcache.storeexplicitly instead.
Cache key format
Section titled “Cache key format”The internal CacheKey class now builds cache keys as a readable prefix followed by a hash of the count’s full identity ({prefix}:{morph class}:{key}:{digest}), instead of the previous concatenated string of slugs. This produces shorter, fixed-length keys that stay well under backend limits (such as Memcached’s 250-byte cap) and cannot collide across different models.
No action is required. This only affects view counts cached via remember(). Existing entries under the old key format are simply never read again. The first count() after upgrading recomputes the value from the views table and re-caches it under the new key. Nothing is lost, since the database remains the source of truth. Old entries expire on their own; run php artisan cache:clear (or clear the eloquent-viewable store) after deploying if you would rather remove them immediately.
The cache key string is an internal implementation detail. If you constructed CacheKey directly (it is not part of the public API), note that it now requires the cache-key prefix as a second constructor argument and no longer exposes the fromViewable() factory:
CacheKey::fromViewable($viewable)->make($period, $unique, $collection);(new CacheKey($viewable, config('eloquent-viewable.cache.key')))->make($period, $unique, $collection);The following getters were removed from CyrildeWit\EloquentViewable\Support\Period:
$period->getStartDateTimeString();$period->getEndDateTimeString();$period->getStartDateTimestamp();$period->getEndDateTimestamp();Derive these values from the DateTimeInterface getters instead:
$period->getStartDateTime()?->format('Y-m-d H:i:s');$period->getEndDateTime()?->format('Y-m-d H:i:s');$period->getStartDateTime()?->timestamp;$period->getEndDateTime()?->timestamp;Changes to the View contract
Section titled “Changes to the View contract”The scopeWithinPeriod method now declares a void return type. The contract also uses @mixin \Illuminate\Database\Eloquent\Model (so every Eloquent method resolves on it) and now declares the scopeCollection() method that already existed on the View model. This only affects you if you implement CyrildeWit\EloquentViewable\Contracts\View directly — update your signature and add the scopeCollection() declaration:
public function scopeWithinPeriod(Builder $query, Period $period);public function scopeWithinPeriod(Builder $query, Period $period): void;
public function scopeCollection(Builder $query, ?string $collection = null): void;Changes to the Views contract
Section titled “Changes to the Views contract”Parameters are now natively typed, and the contract now declares the useVisitor() method that already existed on the Views class. This only affects you if you implement CyrildeWit\EloquentViewable\Contracts\Views directly — update your parameter types and add the useVisitor() declaration:
public function cooldown($cooldown): self;public function cooldown(DateTimeInterface|int|null $cooldown): self;
public function remember($lifetime = null): self;public function remember(DateTimeInterface|int|null $lifetime = null): self;
public function useVisitor(Visitor $visitor): self;Changes to Period
Section titled “Changes to Period”Period is now a final, immutable (readonly) value object. The way you create and read periods is unchanged — the factory methods (create(), since(), upto(), pastDays(), subDays(), …) and getStartDateTime()/getEndDateTime() all work exactly as before. getStartDateTime()/getEndDateTime() return ?CarbonInterface.
The following were removed and have no replacement, as they only existed to support the internal cache key:
- The
Period::PAST_*andPeriod::SUB_*constants. - The
sub(),subToday()andsubNow()static helpers. - The
getSubType(),getSubValue()andhasFixedDateTimes()methods.
Because Period is now immutable, its setters were also removed. Build a new period instead of mutating one:
setStartDateTime(),setEndDateTime(),setFixedDateTimes(),setSubType(),setSubValue().
If you extended Period, note it is now final and can no longer be subclassed.
Changes to the views() helper
Section titled “Changes to the views() helper”The views() helper now type-hints its argument as Viewable|string. Passing anything else will throw a TypeError instead of failing later:
function views($viewable): Views;function views(Viewable|string $viewable): Views;Final exceptions
Section titled “Final exceptions”The InvalidPeriod and ViewRecordException exceptions are now final. If you extended either of them, catch them or wrap your own exception around them instead of subclassing.