Retention

Introduction

Set retention per verb to control how long activities remain in the feed. storyfeed:prune permanently deletes expired activities and entity details no remaining activity uses.

Defining Retention

Per-Verb Retention

To keep order views for 30 days, call keepFor():

routes/feed.php

use App\Models\Order;
use Storyfeed\Facades\Story;

Story::for(Order::class)
    ->verb('view')
    ->headline(':actor viewed :object')
    ->keepFor('30 days');

keepFor() accepts a Carbon interval string, such as '30 days' or '6 months', or a DateInterval. Declare it on Story::verb('view') to apply it across object types.

Default Retention

Set prune.after_days for verbs without a retention declaration:

config/storyfeed.php

'prune' => [
    'after_days' => 365,
],

Keeping Activities Forever

Call keepForever() to exempt a verb from default retention:

routes/feed.php

use App\Models\Order;
use Storyfeed\Facades\Story;

Story::for(Order::class)->verb('refund')->keepForever();

The Verb Declares	Its Activities Are Pruned After
keepFor('30 days')	30 days, overriding prune.after_days
keepForever()	never
nothing	prune.after_days, or never when it is null

Use storyfeed:prune --days= to override prune.after_days for one run. Per-verb retention still takes precedence.

Pruning Activities

Previewing a Run

php artisan storyfeed:prune --pretend

+------+------------+
| Verb | Activities |
+------+------------+
| view | 3          |
+------+------------+
Would prune 3 activities, 2 snapshots and 0 tombstones. Nothing was deleted.

Preview changes after setting or shortening retention: the next pruning run permanently deletes all activities already past the limit.

Running and Scheduling Pruning

php artisan storyfeed:prune # Permanently deletes activities past their retention window.

routes/console.php

use Illuminate\Support\Facades\Schedule;

Schedule::command('storyfeed:prune')->daily();

Each run permanently deletes the view activities older than 30 days. Other verbs follow their own declarations or default retention.

Pruning Groups and Unused Entities

Pruning removes expired members from groups. Here, keepFor('1 hour') applies to five views in one daily group, three of which are over an hour old. Before pruning:

SH

Steve Harrington viewed 5 orders45m ago

After pruning the three expired views:

SH

Steve Harrington viewed 2 orders45m ago

Groups are deleted when all their members are pruned. Changing a group updates the sync_token, so clients using old cursors must fetch the feed from the start.

Pruning also deletes stored entity labels and data that no remaining activity uses. The command keeps no record of what it removed. See Storage Architecture for the rows each activity stores.

NOTE

Pruning and not recording

Avoid recording short-lived state such as typing indicators. See Choosing What Not to Record.