repository·main·Indexed 21 days ago
https://github.com/cyrildewit/eloquent-viewableA minimalistic analytics package for Laravel that provides view tracking for Eloquent models by storing views as individual database records. It supports calculating total and unique views, filtering by custom time periods using the Period class, queueing view records for high-traffic pages, and ordering models by view count via query scopes.
The internal CacheKey class now uses a readable prefix followed by a hash of the count's full identity ({prefix}:{morph class}:{key}:{digest}). This ensures shorter, fixed-length keys that avoid backend limits (like Memcached's 250-byte cap) and prevent collisions across different models.
No action is required for standard usage. Existing cache entries under the old format will be ignored and recomputed on the next count() call. If you want to clear old entries immediately, run php artisan cache:clear.
In v8.0.0, Period is now a final, immutable (readonly) value object.
Key changes:
setStartDateTime() have been removed. You must build a new period instead of mutating an existing one.final and cannot be extended.getStartDateTimeString(), getEndDateTimeString(), getStartDateTimestamp(), getEndDateTimestamp() (Use DateTimeInterface getters instead).PAST_* and SUB_* constants.sub(), subToday(), subNow() static helpers.getSubType(), getSubValue(), hasFixedDateTimes().Usage Pattern: To get formatted strings or timestamps, use the DateTimeInterface returned by getStartDateTime() or getEndDateTime().
-$period->getStartDateTimeString();
+$period->getStartDateTime()?->format('Y-m-d H:i:s');
-$period->getStartDateTimestamp();
+$period->getStartDateTime()?->timestamp;After installing the package, you must publish and run the migrations to create the necessary tables for storing view records.
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"php artisan migratephp artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"
php artisan migrateOn high-traffic pages, you can defer the database write to a queued job using the queue() method. This keeps the request fast.
Use views($post)->queue()->record(); to queue a specific view.
You can enable queueing globally in the eloquent-viewable.php config file:
'queue' => [
'enabled' => true, // queue every recorded view
'connection' => null, // null uses the default queue connection
'queue' => null, // null uses the connection's default queue
],If global queueing is enabled, you can force a synchronous record using views($post)->queue(false)->record();.
When a view is queued, the ViewRecorded event is dispatched from the queue worker. Listeners will run without request context (session, cookies, request(), and auth()->user() will be unavailable). If your listener needs request-derived data, capture it during the request and pass it to the listener manually.
// Queue an individual view on the fly
views($post)->queue()->record();To associate views with a model, the model must implement the CyrildeWit\EloquentViewable\Contracts\Viewable interface and use the CyrildeWit\EloquentViewable\InteractsWithViews trait.
use Illuminate\Database\Eloquent\Model;
use CyrildeWit\EloquentViewable\InteractsWithViews;
use CyrildeWit\EloquentViewable\Contracts\Viewable;
class Post extends Model implements Viewable
{
use InteractsWithViews;
// ...
}To install the package, run the following Composer command. Ensure you are using a compatible version of Laravel and PHP as specified in the version compatibility guide.
composer require cyrildewit/eloquent-viewable:^8In v8.0.0, the create_views_table migration stub defines the visitor column as a string (VARCHAR(255)) instead of text to allow direct indexing.
If you have already run the migration and wish to adopt the new type on an existing table, you must create a new migration. Note that on large tables this will rewrite the table, and any visitor value longer than 255 characters will be truncated (though the built-in identifier is only 80 characters).
Schema::table('views', function (Blueprint $table) {
$table->string('visitor')->nullable()->change();
});When upgrading to v8.0.0, ensure your environment meets the following minimum requirements:
^8.5 (previously supported ^7.4 || ^8.0)13 only (support for Laravel 6 through 12 has been dropped)^3.0 only (support for Carbon 2 has been dropped)If you need to customize the package behavior, you can publish the configuration file using the following command:
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="config"The Views class acts as a fluent builder for managing view interactions with Eloquent models.
forViewable($model) to tell the service which model is being viewed.unique(), period(), or cooldown() to define the constraints of your query or recording action.count() to retrieve data or record() to persist a new view.This pattern allows you to use the same service for both high-frequency recording (often queued) and complex analytical querying (often cached).
The default configuration for models.view.connection and cache.store has changed to null. A null value defers to the application's default database connection and default cache store.
Important considerations:
CACHE_DRIVER to CACHE_STORE. If your published config still uses env('CACHE_DRIVER', 'file'), it may ignore your application's actual cache configuration. Set cache.store to null or env('CACHE_STORE') to fix this.file driver fallback, you should now set cache.store explicitly instead of using null.