jooservices/laravel-activities

Append-only MongoDB-backed activity timeline for Laravel applications.

v1.0.1 2026-06-26 14:40 UTC

Requires

• php: ^8.5
• illuminate/database: ^12.0|^13.0
• illuminate/support: ^12.0|^13.0
• jooservices/dto: ^1.0
• jooservices/laravel-repository: ^1.2
• mongodb/laravel-mongodb: ^4.0|^5.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.65
• laravel/pint: ^1.0
• orchestra/testbench: ^10.0|^11.0
• phpmd/phpmd: ^2.13
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^12.0
• squizlabs/php_codesniffer: ^3.0

MIT

• JOOservices

• mongodb
• timeline
• laravel
• activities
• audit-log

README

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

Features

• Record subject-scoped activities with optional actor, description, payload, and context
• Query activities by subject or context keys such as plugin_slug
• DTO-first API using jooservices/dto
• Repository layer using jooservices/laravel-repository
• Append-only storage (created_at only; no updated_at)
• MongoDB indexes via php artisan activities:ensure-indexes

Requirements

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

Installation

composer require jooservices/laravel-activities

Publish config:

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

Ensure indexes:

php artisan activities:ensure-indexes

Usage

Record an activity:

use JOOservices\LaravelActivities\Contracts\ActivityRecorderInterface;
use JOOservices\LaravelActivities\Dto\ActivityRecordDto;

final class CrawlTargetAdminService
{
    public function __construct(private readonly ActivityRecorderInterface $activities) {}

    public function createTarget(object $target, object $actor): void
    {
        $this->activities->recordFor(
            subject: $target,
            activity: 'crawl_target.created',
            actor: $actor,
            description: 'Created crawl target',
            data: ['url' => 'https://example.test/new'],
            context: ['plugin_slug' => 'onejav'],
        );
    }
}

Query activities:

use JOOservices\LaravelActivities\Contracts\ActivityQueryInterface;
use JOOservices\LaravelActivities\Dto\ActivityFilterDto;

$timeline = app(ActivityQueryInterface::class)->list(new ActivityFilterDto(
    contextKey: 'plugin_slug',
    contextValue: 'onejav',
    limit: 50,
));

Activity document shape

activities
  _id
  subject_id
  subject_type
  activity
  description
  data
  actor_id
  actor_type
  context
  created_at

Relationship to audit systems

This package stores product timeline activities only. Compliance or security audit logs should remain in their own dedicated tables or packages.

Documentation

• docs/README.md
• AGENTS.md

Quality

composer check

License

MIT