Eloquent Viewable

https://github.com/cyrildewit/eloquent-viewable
Admin
A Laravel package that allows you to associate views with Eloquent models and track page views with...
Tokens:52,241
Snippets:411
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Build and Install Dependencies

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/CONTRIBUTING.md

Commands to build the Docker images and install dependencies for local development. Run these before doing anything else.

```bash
make build
make install
```

--------------------------------

### Queueing usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Two examples showing how to queue a view: on-the-fly per-call override with queue(), and forcing sync when global queueing is enabled via config.

```php
// On-the-fly queueing (per-call override)
views($post)->queue()->record();
```

```php
// Global queueing via config (see configuration.md) then force sync:
views($post)->queue(false)->record();
```

--------------------------------

### Install Eloquent Viewable via Composer

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Command to install the package version 8.x using Composer.

```bash
composer require cyrildewit/eloquent-viewable:^8
```

--------------------------------

### useVisitor() usage example

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Replaces the default visitor with a custom VisitorContract implementation for the current call chain. The example uses a custom App\Services\Views\Visitor class.

```php
use App\Services\Views\Visitor;

views($post)->useVisitor(new Visitor())->record();
```

--------------------------------

### Period::create() examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Creates a period with explicit start and end dates, accepting strings or Carbon instances.

```php
Period::create('2024-01-01', '2024-06-30');
Period::create(Carbon::createFromDate(2024, 1, 1), '2024-06-30');
```

--------------------------------

### Example Usage

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Demonstrates how to use the Period class with the views() helper and Eloquent scopes.

```APIDOC
## Example Usage

### Description
Shows practical usage of the Period class for defining time ranges in view queries.

### Code Example
```php
use CyrildeWit\EloquentViewable\Support\Period;

// Concrete range
views($post)->period(Period::create('2024-01-01', '2024-03-31'))->count();

// Open-ended ranges
views($post)->period(Period::since('2024-01-01'))->count();
views($post)->period(Period::upto('2024-12-31'))->count();

// Relative ranges (stable cache signatures)
views($post)->period(Period::pastWeeks(1))->unique()->count();
views($post)->period(Period::subHours(6))->remember(30)->count();

// With Eloquent scopes
Post::orderByViews('desc', Period::pastDays(7))->get();
```
```

--------------------------------

### Period::upto() example

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Creates an end-only period (open-ended start).

```php
Period::upto(Carbon::createFromDate(2024, 6, 1));
```

--------------------------------

### Visitor usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/visitor.md

Shows default usage, per-call visitor replacement for environments without request context, and global binding replacement.

```php
// Default: recorded from the request
views($post)->record();

// Replace the visitor per-call for environments without request context
use App\Services\Views\Visitor;

views($post)->useVisitor(new Visitor())->record();

// Global replacement
$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\Visitor::class,
    \App\Services\Views\Visitor::class
);
```

--------------------------------

### views() helper usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Examples of using the views() helper with count(). Shows total views, unique visitors, period-limited views, and counting all views for a model type via a new instance or class name.

```php
use App\Models\Post;
use CyrildeWit\EloquentViewable\Support\Period;

$post = Post::find(1);

views($post)->count();                                   // total views
views($post)->unique()->count();                         // unique visitors
views($post)->period(Period::pastDays(3))->count();      // views in last 3 days
views(new Post())->count();                              // all views for the Post type
views(Post::class)->count();                             // same, class name resolved from container
```

--------------------------------

### Prepare a model with Viewable interface and InteractsWithViews trait

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Required setup for any model that will have views tracked. The model must implement the Viewable contract and use the InteractsWithViews trait.

```php
use Illuminate\Database\Eloquent\Model;
use CyrildeWit\EloquentViewable\InteractsWithViews;
use CyrildeWit\EloquentViewable\Contracts\Viewable;

class Post extends Model implements Viewable
{
    use InteractsWithViews;

    // ...
}
```

--------------------------------

### Listening to ViewRecorded

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/events.md

Examples of how to register a listener for the ViewRecorded event, either with a closure or a listener class.

```APIDOC
## Listening to ViewRecorded

### Description
Shows how to listen to the ViewRecorded event using Event::listen or a dedicated listener class.

### Event Class
`CyrildeWit\EloquentViewable\Events\ViewRecorded`

### Example: Closure Listener
```php
use CyrildeWit\EloquentViewable\Events\ViewRecorded;
use Illuminate\Support\Facades\Event;

Event::listen(ViewRecorded::class, function (ViewRecorded $event): void {
    // $event->view->viewable_type, $event->view->viewable_id, $event->view->visitor
    // e.g. update a denormalized counter
    $event->view->viewable?->update(['view_count' => ...]);
});
```

### Example: Listener Class
```php
namespace App\Listeners;

use CyrildeWit\EloquentViewable\Events\ViewRecorded;

class TrackViewInExternalService
{
    public function handle(ViewRecorded $event): void
    {
        // $event->view ...
    }
}
```

### Payload Schema (fields on $view)
- **viewable_type** (string) - The morph class of the viewed model.
- **viewable_id** (int|string) - The key of the viewed model.
- **visitor** (?string) - The visitor identifier.
- **collection** (?string) - The collection name.
- **viewed_at** (Carbon timestamp) - The timestamp when the view was recorded.

### Queue-Execution Caveat
When views are recorded through the queued StoreView job, the ViewRecorded dispatch runs on the queue worker, not in the original request. Listeners therefore execute without request context: session, cookies, request(), and auth()->user() are unavailable. Capture any request-derived data inside the request if a listener needs it.
```

--------------------------------

### Usage examples for ViewsFacade

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/service-provider.md

Shows how to use the ViewsFacade to interact with the views builder. Each static call resolves a fresh builder instance, so chain state does not persist between calls.

```php
use CyrildeWit\EloquentViewable\ViewsFacade;

ViewsFacade::forViewable($post)->count();
ViewsFacade::forViewable($post)->unique()->period($period)->count();
ViewsFacade::forViewable($post)->record();
```

--------------------------------

### Example Commit with Breaking Change

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/CONTRIBUTING.md

An example commit message that signals a breaking change by appending '!' after the type/scope and including a 'BREAKING CHANGE:' footer. The footer describes what breaks and what users must do to adapt.

```text
feat(views)!: drop support for Laravel 10

BREAKING CHANGE: the minimum supported Laravel version is now 11. Upgrade your application before updating.
```

--------------------------------

### Caching view counts - Examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Caches view counts using the remember() method. The default lifetime is forever. Examples show caching with periods and unique views.

```php
views($post)->remember()->count();
views($post)->period(Period::create('2018-01-24', '2018-05-22'))->remember()->count();
views($post)->period(Period::upto('2018-11-10'))->unique()->remember()->count();
views($post)->period(Period::pastMonths(2))->remember()->count();
views($post)->period(Period::subHours(6))->remember()->count();
```

--------------------------------

### Using the views() relation

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Usage examples for the views() relation: lazy-load the collection, get a raw count via query, and insert a view row for the model.

```php
$post->views;                 // Eloquent collection of View models (lazy)
$post->views()->count();      // raw count via query
$post->views()->create([...]);// insert a view row for this model
```

--------------------------------

### Customizing view creation - custom CreateView implementation

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Example custom implementation of the CreateView contract. The handle method can add extra attributes, write elsewhere, or skip the event.

```php
use CyrildeWit\EloquentViewable\Contracts\CreateView as CreateViewContract;
use CyrildeWit\EloquentViewable\Contracts\View as ViewContract;
use CyrildeWit\EloquentViewable\PendingView;

final class CreateView implements CreateViewContract
{
    public function handle(PendingView $pending): ViewContract
    {
        // e.g. add extra attributes, write elsewhere, or skip the event
    }
}
```

--------------------------------

### Usage example with cooldown and collections

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/cooldown-manager.md

Shows how to use the Views builder with a 30-minute cooldown. The second record() call within the window returns false. Collections are de-duplicated independently.

```php
// 30-minute cooldown: second record() within the window returns false
$first = views($post)->cooldown(30)->record();   // true, cooldown stored in session
$second = views($post)->cooldown(30)->record();  // false, within cooldown window

// Collections are de-duplicated independently
views($post)->collection('a')->cooldown(30)->record(); // true
views($post)->collection('b')->cooldown(30)->record(); // true
```

--------------------------------

### Past-anchored factory examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Creates periods anchored to today() with open ends.

```php
Period::pastDays(3);  // start = today()->subDays(3), open end
Period::pastMonths(2);
```

--------------------------------

### getStartDateTime(): ?CarbonInterface

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Returns the parsed start bound of the period, or null if not set.

```APIDOC
## getStartDateTime(): ?CarbonInterface

### Description
Returns the parsed start bound of the period, or null if the period is open-ended.

### Method
Instance method

### Signature
`getStartDateTime(): ?CarbonInterface`

### Returns
- **?CarbonInterface** - The parsed start bound, or `null` if not set.

### Source
`src/Support/Period.php:120`
```

--------------------------------

### Period::since() example

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Creates a start-only period (open-ended end).

```php
Period::since('2024-01-01'); // everything from 2024-01-01 onward
```

--------------------------------

### record() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Shows the basic usage of record() and its variants: with a cooldown, with queueing on the fly, and forcing synchronous recording. The method returns a boolean; it returns false when any filter rejects the view (e.g., bot detection, DNT, ignored IP, or active cooldown).

```php
// Basic
views($post)->record();                 // returns bool

// Cooldown of 30 minutes between records
views($post)->cooldown(30)->record();

// Queue on the fly (overrides config), but keep sync filtering during the request
views($post)->queue()->record();

// Force synchronous even when queueing is globally enabled
views($post)->queue(false)->record();
```

--------------------------------

### Build with Custom PHP Version

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/CONTRIBUTING.md

Command to build the Docker images against a different PHP version by passing it through the ARGS variable. The example uses PHP 8.4.

```bash
make build ARGS="--build-arg PHP=8.4"
```

--------------------------------

### queue() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Overrides the eloquent-viewable.queue.enabled config for this call chain. queue() defers the database write to the StoreView job; queue(false) forces synchronous recording.

```php
views($post)->queue()->record();   // queued
views($post)->queue(false)->record(); // synchronous, regardless of config
```

--------------------------------

### Period::create

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Static factory to create a Period with explicit start and end dates.

```APIDOC
## Period::create

### Description
Creates a new Period instance with the given start and end dates.

### Signature
```php
public static function create(DateTimeInterface|string|null $startDateTime = null, DateTimeInterface|string|null $endDateTime = null): self
```

### Parameters
- **$startDateTime** (DateTimeInterface|string|null) - Optional - Period start.
- **$endDateTime** (DateTimeInterface|string|null) - Optional - Period end.

### Throws
- **CyrildeWit\EloquentViewable\Exceptions\InvalidPeriod** - When both bounds are set and startDateTime > endDateTime.

### Example
```php
Period::create('2024-01-01', '2024-06-30');
Period::create(Carbon::createFromDate(2024, 1, 1), '2024-06-30');
```
```

--------------------------------

### Using viewable() relation

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/view-model.md

Example usage of the viewable() relation: records a view for $post, fetches the latest view, and checks that its viewable is a Post instance.

```php
$view = views($post)->record() ? View::latest('viewed_at')->first() : null;
// $view?->viewable instanceof Post (true)
```

--------------------------------

### remember() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Shows how to cache view counts with remember(). Passing an integer caches for that many minutes (e.g., 60 minutes), passing a DateTimeInterface caches until that absolute time, and passing null (default) does not cache because cacheLifetime remains null. The third example combines period and unique filters with a 30-minute cache.

```php
views($post)->remember(60)->count();                    // cache 60 minutes
views($post)->remember(now()->addWeeks(2))->count();    // cache until a DateTime
views($post)->period(Period::pastDays(3))->unique()->remember(30)->count();
```

--------------------------------

### Period usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Demonstrates common usage of Period with the views() helper: concrete ranges, open-ended ranges (since/upto), relative ranges with cache signatures, and the orderByViews Eloquent scope.

```php
use CyrildeWit\EloquentViewable\Support\Period;

// Concrete range
views($post)->period(Period::create('2024-01-01', '2024-03-31'))->count();

// Open-ended ranges
views($post)->period(Period::since('2024-01-01'))->count();
views($post)->period(Period::upto('2024-12-31'))->count();

// Relative ranges (stable cache signatures)
views($post)->period(Period::pastWeeks(1))->unique()->count();
views($post)->period(Period::subHours(6))->remember(30)->count();

// With Eloquent scopes
Post::orderByViews('desc', Period::pastDays(7))->get();
```

--------------------------------

### Using orderByUniqueViews scope

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Usage examples for the orderByUniqueViews scope: default descending and with an ascending direction plus a period filter.

```php
Post::orderByUniqueViews()->get();                    // most unique visitors first
Post::orderByUniqueViews('asc', Period::pastMonths(1))->get();
```

--------------------------------

### Using withinPeriod scope

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/view-model.md

Example usage of the withinPeriod scope: counts views from the past 7 days.

```php
View::withinPeriod(Period::pastDays(7))->count();
```

--------------------------------

### Period::since

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Static factory to create a period starting from a given date with no end bound.

```APIDOC
## Period::since

### Description
Creates a start-only period with an open-ended end.

### Signature
```php
public static function since(DateTimeInterface|string|null $startDateTime = null): self
```

### Parameters
- **$startDateTime** (DateTimeInterface|string|null) - Optional - Period start.

### Throws
- **CyrildeWit\EloquentViewable\Exceptions\InvalidPeriod** - When both bounds are set and startDateTime > endDateTime.

### Example
```php
Period::since('2024-01-01'); // everything from 2024-01-01 onward
```
```

--------------------------------

### Macro support examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Shows how to define and use macros on the Views class. The first macro 'countAndRemember' chains remember() and count(), and is called via views() and Views::forViewable(). The second macro 'recordOncePerHour' uses cooldown(60) before record().

```php
use CyrildeWit\EloquentViewable\Views;

Views::macro('countAndRemember', function () {
    return $this->remember()->count();
});

// Usage
views($post)->countAndRemember();
Views::forViewable($post)->countAndRemember();

// Macros can also swap the visitor or change other state built into the builder:
Views::macro('recordOncePerHour', function () {
    return $this->cooldown(60)->record();
});
```

--------------------------------

### cacheSignature() examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Shows the output of cacheSignature() for a relative period (pastDays) and an absolute period (create). The relative signature is stable across time, while the absolute one is a timestamp range.

```php
Period::pastDays(3)->cacheSignature();     // e.g. "past3days" (stable across time)
Period::create('2024-01-01', '2024-01-31')->cacheSignature(); // "1704067200-1706659200"
```

--------------------------------

### Visitor interface

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/types.md

Defines the contract for a visitor, providing methods to get the visitor ID, IP address, and check for DNT headers or crawler status.

```php
interface Visitor
{
    public function id(): string;

    public function ip(): ?string;

    public function hasDoNotTrackHeader(): bool;

    public function isCrawler(): bool;
}
```

--------------------------------

### unique() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

When true, counts distinct visitor values instead of all rows. unique(false) reverts to the total count.

```php
views($post)->unique()->count();
views($post)->unique(false)->count(); // back to total count
```

--------------------------------

### Using orderByViews scope

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Usage examples for the orderByViews scope: default descending, ascending, with a period filter, and with a collection plus unique variant.

```php
Post::orderByViews()->get();                 // most viewed first
Post::orderByViews('asc')->get();            // least viewed first
Post::orderByViews('asc', Period::pastDays(3))->get();
Post::orderByViews('desc', null, 'weekly')->unique()->get(); // per-collection, unique variant via $unique
```

--------------------------------

### cooldown() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Shows cooldown() with an integer (minutes) and with a DateTimeInterface (specific expiry time). The cooldown is enforced by CooldownManager::push() inside shouldRecord().

```php
views($post)->cooldown(30)->record();                 // no duplicate within 30 minutes
views($post)->cooldown(now()->addHours(3))->record(); // cooldown until a specific time
```

--------------------------------

### period() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Restricts counting to a given period using Period::create() or Period::upto(). The period() method affects counting, not recording.

```php
use CyrildeWit\EloquentViewable\Support\Period;

views($post)->period(Period::create('2024-01-01', '2024-12-31'))->count();
views($post)->period(Period::upto(now()))->count();
```

--------------------------------

### boot() method of EloquentViewableServiceProvider

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/service-provider.md

Publishes the config file and migration stub when running in console. The migration is only published if the CreateViewsTable class does not exist, preventing duplicate migrations.

```php
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../config/eloquent-viewable.php' => $this->app->configPath('eloquent-viewable.php'),
        ], 'config');

        if (! class_exists('CreateViewsTable')) {
            $timestamp = date('Y_m_d_His', time());

            $this->publishes([
                __DIR__.'/../migrations/create_views_table.php.stub' => database_path("/migrations/{$timestamp}_create_views_table.php"),
            ], 'migrations');
        }
    }
}
```

--------------------------------

### CacheKey usage example

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/cache-key.md

Example usage of CacheKey to generate a cache key for a viewable model with a period, unique flag, and collection. The resulting key can be used with cache()->get() to retrieve the cached count.

```php
use CyrildeWit\EloquentViewable\CacheKey;
use CyrildeWit\EloquentViewable\Support\Period;

$key = (new CacheKey($post, config('eloquent-viewable.cache.key')))
    ->make(Period::pastDays(3), true, 'weekly');

// e.g. "cyrildewit.eloquent-viewable.cache:App\Models\Post:1:8f3a2b…"
cache()->get($key); // the cached count (int), or null
```

--------------------------------

### boot(): void

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/service-provider.md

Publishes configuration and migration files when running in console. The config tag publishes the eloquent-viewable config file, and the migrations tag publishes the create_views_table migration stub if the migration class does not already exist.

```APIDOC
## boot(): void

### Description
Publishes configuration and migration files when running in console. The config tag publishes the eloquent-viewable config file, and the migrations tag publishes the create_views_table migration stub if the migration class does not already exist.

### Method
boot

### Signature
public function boot(): void

### Parameters
None

### Returns
void

### Behavior
- If running in console, publishes the config file to `configPath('eloquent-viewable.php')` with tag `config`.
- If running in console and the `CreateViewsTable` class does not exist, publishes the migration stub to `database/migrations/{timestamp}_create_views_table.php` with tag `migrations`.

### Publish Commands
- `php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="config"`
- `php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"`
```

--------------------------------

### Get view count for a specific period

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Retrieves the view count for a model within a specified period using the Period class. The example shows a period from 2017 to 2018.

```php
use CyrildeWit\EloquentViewable\Support\Period;

// Example: get view count from 2017 up to 2018
views($post)
    ->period(Period::create('2017', '2018'))
    ->count();
```

--------------------------------

### Period constructor with validation

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Constructor accepts optional start and end dates, parses them with Carbon::make(), and throws InvalidPeriod if start is after end.

```php
/**
 * @throws InvalidPeriod
 */
public function __construct(
    DateTimeInterface|string|null $startDateTime = null,
    DateTimeInterface|string|null $endDateTime = null,
    /**
     * A stable signature for relative periods that keeps the cache key from
     * drifting as wall-clock time moves. Null for absolute periods, which
     * are identified by their timestamps instead.
     *
     * @internal
     */
    private ?string $relativeSignature = null,
) {
    $this->startDateTime = Carbon::make($startDateTime);
    $this->endDateTime = Carbon::make($endDateTime);

    $this->guardChronologicalOrder();
}
```

--------------------------------

### Full config file (v8, as shipped)

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/configuration.md

The complete configuration file for eloquent-viewable v8. Use this as a reference for all available configuration keys and their default values. Note that comments from the shipped file are removed here; the actual file documents each key inline.

```php
<?php

return [

    'models' => [

        'view' => [

            'table_name' => 'views',

            'connection' => null,

        ],

    ],

    'cache' => [

        'key' => 'cyrildewit.eloquent-viewable.cache',

        'store' => null,

    ],

    'queue' => [

        'enabled' => false,

        'connection' => null,

        'queue' => null,

    ],

    'cooldown' => [

        'key' => 'cyrildewit.eloquent-viewable.cooldowns',

    ],

    'ignore_bots' => true,

    'honor_dnt' => false,

    'visitor_cookie_key' => 'eloquent_viewable',

    'ignored_ip_addresses' => [

        // '127.0.0.1',

    ],

];
```

--------------------------------

### Visitor::__construct()

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/visitor.md

The constructor initializes a Visitor from the request, crawler detector, and configuration repository.

```APIDOC
## `Visitor::__construct()`

### Description
Creates a new Visitor instance with the given current request. The request provides the IP address and Do-Not-Track header; the crawler detector determines if the visitor is a bot. The config repository is used to read the visitor cookie key.

### Method
Constructor

### Signature
```php
public function __construct(
    protected Request $request,
    protected CrawlerDetector $crawlerDetector,
    ConfigRepository $config
)
```

### Parameters
- `$request` (Illuminate\Http\Request) - Required - Current request (source of IP, DNT header)
- `$crawlerDetector` (CyrildeWit\EloquentViewable\Contracts\CrawlerDetector) - Required - Crawler detection service
- `$config` (Illuminate\Contracts\Config\Repository) - Required - Used to read `eloquent-viewable.visitor_cookie_key`

### Notes
The visitor cookie key is read once from `config('eloquent-viewable.visitor_cookie_key')` (default `'eloquent_viewable'`).
```

--------------------------------

### InvalidPeriod exception handling

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Shows error handling when creating a period with a start date after the end date. The InvalidPeriod exception is thrown with the message "Start date `2024-12-31` cannot be after end date `2024-01-01`."

```php
use CyrildeWit\EloquentViewable\Support\Period;
use CyrildeWit\EloquentViewable\Exceptions\InvalidPeriod;

try {
    Period::create('2024-12-31', '2024-01-01'); // start after end
} catch (InvalidPeriod $e) {
    // "Start date `2024-12-31` cannot be after end date `2024-01-01`."
}
```

--------------------------------

### Enable queueing globally in config

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Configuration to queue every recorded view. Set 'enabled' to true, and optionally specify connection and queue names.

```php
'queue' => [
    'enabled' => true,      // queue every recorded view
    'connection' => null,   // null uses the default queue connection
    'queue' => null,        // null uses the connection's default queue
],
```

--------------------------------

### InvalidPeriod exception class with factory method

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/errors.md

Defines the final exception class InvalidPeriod with a static factory method that builds the exception message using formatted start and end dates. The method returns a new instance of the class with the message 'Start date `{Y-m-d}` cannot be after end date `{Y-m-d}`.'

```php
final class InvalidPeriod extends Exception
{
    public static function startDateTimeCannotBeAfterEndDateTime(DateTimeInterface $startDateTime, DateTimeInterface $endDateTime): static
    {
        return new self("Start date `{$startDateTime->format('Y-m-d')}` cannot be after end date `{$endDateTime->format('Y-m-d')}`.");
    }
}
```

--------------------------------

### Run database migrations

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Artisan command to run the database migrations and create the necessary tables.

```bash
php artisan migrate
```

--------------------------------

### Visitor constructor

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/visitor.md

Initializes the Visitor with the current request, crawler detector, and config repository. Reads the visitor cookie key from config('eloquent-viewable.visitor_cookie_key') with default 'eloquent_viewable'.

```php
public function __construct(
    protected Request $request,
    protected CrawlerDetector $crawlerDetector,
    ConfigRepository $config
) {
    $this->visitorCookieKey = $config['eloquent-viewable']['visitor_cookie_key'];
}
```

--------------------------------

### Period::since - Since a specific date

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Creates a Period starting from a given date.

```php
Period::since(Carbon::create(2017));
```

--------------------------------

### bootInteractsWithViews method

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Eloquent boot hook that registers the ViewableObserver on the model once it is booted, enabling the delete cascade. No parameters and no return value.

```php
public static function bootInteractsWithViews(): void
{
    static::whenBooted(fn () => static::observe(ViewableObserver::class));
}
```

--------------------------------

### Views Builder and views() Helper

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Documentation for the `views()` helper and the `Views` builder methods `forViewable()` and `count()`.

```APIDOC
## views() helper

### Description
Global helper function that resolves the `Views` contract from the container and returns a `Views` instance for the given viewable model or class name.

### Method
N/A (global function)

### Signature
```php
function views(Viewable|string $viewable): Views
```

### Parameters
- **$viewable** (Viewable|string) - Required - A model instance implementing `Contracts\Viewable`, or a class name/string resolved from the container.

### Behavior
Resolves the `Views` contract from the container and returns `forViewable($viewable)`. If a string is passed, it is resolved via `Container::make($viewable)`; the resolved instance is only used if it `instanceof Viewable` — otherwise the raw string is passed on, and `forViewable()` will fail with a `TypeError`.

### Example
```php
use App\Models\Post;

$post = Post::find(1);
views($post)->count();
```
```

```APIDOC
## Views::forViewable

### Description
Sets the target viewable model for the builder.

### Method
N/A (chainable method)

### Signature
```php
public function forViewable(Viewable $viewable): self
```

### Parameters
- **$viewable** (Viewable) - Required - The Eloquent model to count/record views for. A model with a `null` key selects the whole viewable type.

### Example
```php
use App\Models\Post;

$post = Post::find(1);
views($post)->forViewable($post);
```
```

```APIDOC
## Views::count

### Description
Returns the number of views matching the current builder state.

### Method
N/A (terminal method)

### Signature
```php
public function count(): int
```

### Behavior
- Resolves a query on the `View` model: per-viewable rows via `$viewable->views()->getQuery()`, or — when the viewable's key is `null` — all rows with `viewable_type = $viewable->getMorphClass()`.
- Applies `scopeWithinPeriod` when a `Period` was set via `period()`; applies `scopeCollection` when a collection name was set.
- With `unique()`, executes `distinct()->count('visitor')`; otherwise `count()`.
- When `remember()` configured a lifetime, reads/writes the cache under a `CacheKey`; a cached `0` is a valid stored value, while a cache miss (`null`) recomputes.

### Examples
```php
use App\Models\Post;
use CyrildeWit\EloquentViewable\Support\Period;

$post = Post::find(1);

views($post)->count();                                   // total views
views($post)->unique()->count();                         // unique visitors
views($post)->period(Period::pastDays(3))->count();      // views in last 3 days
views(new Post())->count();                              // all views for the Post type
views(Post::class)->count();                             // same, class name resolved from container
```
```

--------------------------------

### Period::upto

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/period.md

Static factory to create a period ending at a given date with no start bound.

```APIDOC
## Period::upto

### Description
Creates an end-only period with an open-ended start.

### Signature
```php
public static function upto(DateTimeInterface|string|null $endDateTime = null): self
```

### Parameters
- **$endDateTime** (DateTimeInterface|string|null) - Optional - Period end.

### Throws
- **CyrildeWit\EloquentViewable\Exceptions\InvalidPeriod** - When both bounds are set and startDateTime > endDateTime.

### Example
```php
Period::upto(Carbon::createFromDate(2024, 6, 1));
```
```

--------------------------------

### Track and retrieve views with views() helper

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Shows how to use the views() helper to count total views, count unique views since a specific date using the Period class, and record a new view.

```php
// Return total view count
views($post)->count();

// Return total unique view count since 20 February 2017
views($post)->unique()->period(Period::since('2017-02-20'))->count();

// Record a view
views($post)->record();
```

--------------------------------

### register() method of EloquentViewableServiceProvider

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/service-provider.md

Merges the package config, sets up a contextual binding for the cache store, binds contracts to implementations, and registers a factory for CrawlerDetectAdapter. The CrawlerDetectorContract is bound as a singleton.

```php
#[\Override]
public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/eloquent-viewable.php',
        'eloquent-viewable'
    );

    $this->app->when(Views::class)
        ->needs(CacheRepository::class)
        ->give(fn (): CacheRepository => $this->app['cache']->store(
            $this->app['config']['eloquent-viewable']['cache']['store']
        ));

    $this->app->bind(ViewsContract::class, Views::class);

    $this->app->bind(ViewContract::class, View::class);

    $this->app->bind(CreateViewContract::class, CreateView::class);

    $this->app->bind(VisitorContract::class, Visitor::class);

    $this->app->bind(CrawlerDetectAdapter::class, function (Application $app): CrawlerDetectAdapter {
        $detector = new CrawlerDetect(
            $app['request']->headers->all(),
            $app['request']->server('HTTP_USER_AGENT')
        );

        return new CrawlerDetectAdapter($detector);
    });

    $this->app->singleton(CrawlerDetectorContract::class, CrawlerDetectAdapter::class);
}
```

--------------------------------

### Get view count in a collection

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Retrieves the view count for a specific collection using the collection() method.

```php
views($post)
    ->collection('customCollection')
    ->count();
```

--------------------------------

### StoreView::handle(CreateView $action): void

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Handles the queued job by delegating to the CreateView action. Executes the same flow as the synchronous path, including inserting the view and dispatching the ViewRecorded event.

```APIDOC
## StoreView::handle(CreateView $action): void

### Description
Handles the queued job by delegating to the CreateView action. Executes the same flow as the synchronous path, including inserting the view and dispatching the ViewRecorded event.

### Method
handle

### Parameters
- **$action** (CyrildeWit\EloquentViewable\Contracts\CreateView) - Required - The CreateView contract, resolved from the container by the queue worker

### Returns
- **void** - Executes the same CreateView flow (insert + ViewRecorded event) on the worker.

### Request Example
```php
$job->handle($action);
```

### Response
#### Success Response
No return value (void).
```

--------------------------------

### Get unique view count

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Retrieves the unique view count by adding the unique() method to the chain.

```php
views($post)
    ->unique()
    ->count();
```

--------------------------------

### CreateView interface

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/types.md

Defines the contract for persisting views. The handle() method accepts a PendingView and must return a View instance. Consumed by the Views constructor for synchronous recording and by StoreView::handle() for queued recording.

```php
interface CreateView
{
    public function handle(PendingView $pending): View;
}
```

--------------------------------

### Get total view count

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Retrieves the total number of views for a model using the views() helper.

```php
views($post)->count();
```

--------------------------------

### Force synchronous recording with queue(false)

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

When queueing is enabled globally, this forces an individual view to be recorded synchronously.

```php
views($post)->queue(false)->record();
```

--------------------------------

### Queue an individual view with queue()

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Defers the database write to a queued job for high-traffic pages. The view is queued on the fly.

```php
views($post)->queue()->record();
```

--------------------------------

### Publish config file

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Optional Artisan command to publish the package's configuration file.

```bash
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="config"
```

--------------------------------

### Period::pastDays/Weeks/Months/Years - For past period

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Creates a Period for a past duration, using Carbon::today() as the start datetime minus the given unit.

```php
Period::pastDays(int $days);
Period::pastWeeks(int $weeks);
Period::pastMonths(int $months);
Period::pastYears(int $years);
```

--------------------------------

### Model with removeViewsOnDelete false

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Example model that opts out of automatic view deletion by setting removeViewsOnDelete to false, preserving view history after deletion.

```php
class Post extends Model implements Viewable
{
    use InteractsWithViews;

    protected $removeViewsOnDelete = false; // keep view history after model deletion
}
```

--------------------------------

### Constructor

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/visitor.md

Creates a new CrawlerDetectAdapter instance with the provided CrawlerDetect detector.

```APIDOC
## Constructor

### Description
Creates a new CrawlerDetectAdapter instance with the provided CrawlerDetect detector.

### Method
__construct

### Signature
```php
public function __construct(private readonly CrawlerDetect $detector) {}
```

### Parameters
- **$detector** (Jaybizzle\CrawlerDetect\CrawlerDetect) - Required - The underlying detector instance

### Example
```php
$detector = new CrawlerDetect(
    $app['request']->headers->all(),
    $app['request']->server('HTTP_USER_AGENT')
);
$adapter = new CrawlerDetectAdapter($detector);
```
```

--------------------------------

### Using collection scope

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/view-model.md

Example usage of the collection scope: counts views inside a named collection and uncategorized views (null collection).

```php
View::collection('weekly-digest')->count();       // inside a named collection
View::collection()->count();                      // uncategorized views (null collection)
```

--------------------------------

### Customizing view creation - service provider binding

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Bind your own implementation to the CreateView contract in a service provider. Your handle() receives the PendingView and must return a View instance.

```php
$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\CreateView::class,
    \App\Actions\Views\CreateView::class
);
```

--------------------------------

### Publish database migrations

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Artisan command to publish the package's database migrations for review.

```bash
php artisan vendor:publish --provider="CyrildeWit\EloquentViewable\EloquentViewableServiceProvider" --tag="migrations"
```

--------------------------------

### StoreView handle method

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Handle method that resolves the CreateView contract from the container and executes the same flow as the synchronous record path, including insert and ViewRecorded event.

```php
public function handle(CreateView $action): void
{
    $action->handle($this->pending);
}
```

--------------------------------

### Record view in controller's show method

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Recommended placement: inside the controller method that displays the model, ensuring views are recorded only when the page is rendered.

```php
// PostController.php
public function show(Post $post)
{
    views($post)->record();

    return view('post.show', compact('post'));
}
```

--------------------------------

### StoreView::__construct(PendingView $pending)

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Constructor for the StoreView job. Accepts a PendingView instance that will be serialized with the job.

```APIDOC
## StoreView::__construct(PendingView $pending)

### Description
Constructor for the StoreView job. Accepts a PendingView instance that will be serialized with the job.

### Method
Constructor

### Parameters
- **$pending** (PendingView) - Required - Serialized payload; public property, so it is serialized with the job

### Request Example
```php
new StoreView($pending)
```

### Response
#### Success Response
No return value (constructor).
```

--------------------------------

### Period::subSeconds/Minutes/Hours/Days/Weeks/Months/Years - For custom time subtraction

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Creates a Period for a custom time subtraction, using Carbon::now() as the start datetime minus the given unit.

```php
Period::subSeconds(int $seconds);
Period::subMinutes(int $minutes);
Period::subHours(int $hours);
Period::subDays(int $days);
Period::subWeeks(int $weeks);
Period::subMonths(int $months);
Period::subYears(int $years);
```

--------------------------------

### collection() usage examples

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/views.md

Namespaces views and counts into a named collection. The collection name is stored in the 'collection' column on record and filters on count via scopeCollection.

```php
views($post)->collection('weekly-digest')->record();
views($post)->collection('weekly-digest')->count();
```

--------------------------------

### register(): void

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/service-provider.md

Registers the service provider by merging configuration, setting up a contextual binding for the cache repository, and binding contracts to their implementations. It also registers a factory for the CrawlerDetectAdapter and a singleton for the CrawlerDetectorContract.

```APIDOC
## register(): void

### Description
Registers the service provider by merging configuration, setting up a contextual binding for the cache repository, and binding contracts to their implementations. It also registers a factory for the CrawlerDetectAdapter and a singleton for the CrawlerDetectorContract.

### Method
register

### Signature
public function register(): void

### Parameters
None

### Returns
void

### Behavior
- Merges `config/eloquent-viewable.php` under the `eloquent-viewable` config key.
- Contextual binding: when `Views` needs a `CacheRepository`, give it `cache()->store(config('eloquent-viewable.cache.store'))`.
- Binds contracts to implementations:
  - `CyrildeWit\EloquentViewable\Contracts\Views` → `CyrildeWit\EloquentViewable\Views`
  - `CyrildeWit\EloquentViewable\Contracts\View` → `CyrildeWit\EloquentViewable\View`
  - `CyrildeWit\EloquentViewable\Contracts\CreateView` → `CyrildeWit\EloquentViewable\Actions\CreateView`
  - `CyrildeWit\EloquentViewable\Contracts\Visitor` → `CyrildeWit\EloquentViewable\Visitor`
  - `CyrildeWit\EloquentViewable\Contracts\CrawlerDetector` → singleton `CrawlerDetectAdapter::class`
- Registers a factory for `CrawlerDetectAdapter` that builds a `Jaybizzle\CrawlerDetect\CrawlerDetect` from the current request's headers and `HTTP_USER_AGENT` server value.

### Extension Points
Rebind any contract in your own service provider's `register()` method. Example:

```php
$this->app->bind(
    \CyrildeWit\EloquentViewable\Contracts\Views::class,
    \App\Services\Views\Views::class
);
```
```

--------------------------------

### bootInteractsWithViews(): void

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/interacts-with-views.md

Eloquent boot hook that registers the ViewableObserver on the model when it is booted. This enables the delete cascade behavior.

```APIDOC
## bootInteractsWithViews(): void

### Description
Eloquent boot hook that registers the ViewableObserver on the model once it is booted, enabling the delete cascade.

### Method
bootInteractsWithViews

### Signature
```php
public static function bootInteractsWithViews(): void
```

### Parameters
None.

### Returns
void

### Example
```php
// Called automatically by Eloquent when the model is booted.
```
```

--------------------------------

### Get view count of viewable type

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Retrieves the total view count for a viewable type by passing an empty model instance or a class name to the views() helper.

```php
views(new Post())->count();
```

```php
views(Post::class)->count();
views('App\Post')->count();
```

--------------------------------

### CacheKey::make() method

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/cache-key.md

Builds the cache key string by combining the head and digest. Accepts optional period, unique flag, and collection name. Returns a string in the format '{head}:{digest}'.

```php
public function make(?Period $period = null, bool $unique = false, ?string $collection = null): string
{
    return $this->head().':'.$this->digest($period, $unique, $collection);
}
```

--------------------------------

### Record a view with views($post)->record()

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/README.md

Tracks a view for the given model. By default, crawlers are ignored, so tools like Postman may not record views.

```php
views($post)->record();
```

--------------------------------

### StoreView constructor

Source: https://github.com/cyrildewit/eloquent-viewable/blob/main/_autodocs/api-reference/pending-view.md

Constructor for the StoreView job, accepting a PendingView instance as a public property so it is serialized with the job.

```php
public function __construct(public PendingView $pending) {}
```
Tokens:
Raw