jooservices / laravel-activities

v4.0.0 2026-09-06 13:45 UTC

Requires

• php: ^8.5
• jooservices/dto: ^3.2
• jooservices/exceptions: ^4.0
• jooservices/laravel-repository: ^4.0
• laravel/framework: ^12.0|^13.0
• mongodb/laravel-mongodb: ^5.10

Requires (Dev)

• captainhook/captainhook: ^5.29
• captainhook/plugin-composer: ^5.3
• fakerphp/faker: ^1.24
• friendsofphp/php-cs-fixer: ^3.95
• larastan/larastan: ^3.11
• laravel/pint: ^1.30
• orchestra/testbench: ^10.0|^11.0
• phpmd/phpmd: ^2.15
• phpstan/phpstan: ^2.2
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^12.0 || ^13.0
• squizlabs/php_codesniffer: ^4.0

MIT

• Viet Vu

• mongodb
• php
• timeline
• laravel
• activities
• composer-package
• audit-log
• JOOservices
• laravel12
• php85
• laravel13

Published on Packagist.org on 2026-09-06 14:32 UTC

README

Append-only MongoDB-backed activity timeline for Laravel 12 and 13 applications.

v4.0.0 requires jooservices/dto ^3.2, jooservices/laravel-repository ^4, and jooservices/exceptions ^4. See UPGRADE.md.

Features

• Record subject-scoped activities with optional actor, tenant, description, payload, and context
• Query by subject, actor, tenant, activity prefix, correlation, and date range
• Honest cursor pagination (hasMore / nextCursor) and explicit offset mode
• Sanitization plus payload limits for data and context
• Retention pruning via php artisan activities:prune (deleteMany)
• JSONL and CSV export via php artisan activities:export
• Official in-memory store for consumer tests (ACTIVITIES_STORE=array, not production)
• DTO-first API using jooservices/dto ^3
• Repository layer using jooservices/laravel-repository ^4

Requirements

• PHP 8.5+
• Laravel 12 or 13
• MongoDB 6+
• mongodb/laravel-mongodb ^5.10

Installation

composer require jooservices/laravel-activities

Publish config:

php artisan vendor:publish --tag=activities-config

Ensure indexes:

php artisan activities:ensure-indexes

Usage

use JOOservices\LaravelActivities\Contracts\ActivityRecorderInterface;

$activities->recordFor(
    subject: $target,
    activity: 'crawl_target.created',
    actor: $actor,
    description: 'Created crawl target',
    data: ['url' => $url],
    context: ['plugin_slug' => $slug],
    correlationId: $correlationId,
    tenantId: $tenantId,
);

Query:

use JOOservices\LaravelActivities\Dto\ActivityFilterDto;

$timeline = $query->list(new ActivityFilterDto(
    contextKey: 'plugin_slug',
    contextValue: $slug,
    tenantId: $tenantId,
    limit: 50,
));

$next = $timeline->nextCursor;
$hasMore = $timeline->hasMore;

Offset pagination (when a total is required):

$list = $query->list(new ActivityFilterDto(
    pagination: 'offset',
    page: 2,
    limit: 50,
));

Relationship to audit systems

This package stores product timeline activities only. Ops logs belong in jooservices/laravel-logging. Compliance events belong in jooservices/laravel-events.

Documentation

• docs/README.md
• UPGRADE.md
• AGENTS.md

Quality

composer ci

Coverage gate: 90% minimum (composer test:coverage).

License

MIT