alex-kassel/laravel-worklog-manager

Multichannel session, activity, and time-tracking pipeline engine with pluggable processor chains and user identification for PHP 8.2+ and Laravel.

dev-main 2026-08-18 19:33 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/events: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/http: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/pipeline: ^10.0 || ^11.0 || ^12.0 || ^13.0
• illuminate/support: ^10.0 || ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• orchestra/testbench: ^8.0 || ^9.0 || ^10.0
• phpunit/phpunit: ^10.5 || ^11.0

MIT

• Alexander Macenko

• laravel
• pipeline
• webhooks
• time-tracking
• rfc3339
• worklog
• session-tracking
• docs-as-code

Published on Packagist.org on 2026-08-18 19:35 UTC

README

Laravel Worklog Manager (alex-kassel/laravel-worklog-manager) is a multichannel session, activity, and time-tracking pipeline engine for PHP 8.2+ and Laravel applications.

It ingests work session bounds, pause intervals, and execution metrics from multiple channels (Artisan CLI, Laravel Domain Events, Direct Facade API, and HMAC-signed HTTP Webhooks), routes payloads through a pluggable processor pipeline (WorklogPipeline), and outputs structured session logs to Markdown Docs-as-Code files (worklog.md), Eloquent SQL databases, CSV audit logs, and external webhooks simultaneously.

Key Features

• Multichannel Ingestion Equivalence: Ingest signals identically via Artisan CLI (php artisan worklog:*), Laravel Domain Events, Direct Facade API, or HTTP Webhooks.
• Pluggable Processor Pipeline (WorklogPipeline): Chain-of-responsibility pipeline allowing developers to attach custom processors (WorklogProcessorInterface).
• Fault Isolation (mustSucceed): Critical processors (e.g. Markdown or DB persistence) halt execution on failure, while non-critical processors (e.g. Slack/Telegram notifications) are caught and logged without aborting active runs.
• RFC 3339 & Timezone Engine: Precise wall-clock duration math ($D_{\text{active}} = D_{\text{wall}} - D_{\text{pause}}$) with deterministic overlapping pause interval merging and explicit timezone offset output (Europe/Berlin).
• Multi-Tenant Context Isolation: Session stacks isolated per user_id / client_slug.
• HMAC SHA-256 Webhook Security: Secured HTTP endpoint with signature verification (X-Worklog-Signature) and timestamp freshness replay protection.

High-Level Architecture

Incoming Signal (CLI / Events / Facade API / Webhook)
                       │
                       ▼
            SignalNormalizer (DTO Mapping)
                       │
                       ▼
          WorklogPipeline (Processor Chain)
                       │
     ┌─────────────────┼─────────────────┬─────────────────┐
     ▼                 ▼                 ▼                 ▼
MarkdownWorklog    DatabaseWorklog    CsvWriterProcessor EventDispatcher
Processor          Processor                            Processor
(docs/worklog.md)  (Eloquent DB)      (Audit CSV)       (Domain Events)

Installation

Install the package via Composer:

composer require alex-kassel/laravel-worklog-manager

Configuration Publishing

Publish the package configuration file to config/worklog-manager.php:

php artisan vendor:publish --tag="worklog-manager-config"

Quick Start & Usage

1. Artisan CLI Commands

Manage worklog sessions directly from the terminal or automated scripts:

# Start a new session
php artisan worklog:start --user=alex --scope=scraper-core --boundary="Phase 7 Diagnostics"

# Pause active session
php artisan worklog:pause --user=alex --reason="Break"

# Resume session
php artisan worklog:resume --user=alex

# Close session
php artisan worklog:close --user=alex --outcome="Diagnostics completed" --next="Initiate Phase 8"

Pass --json flag to receive structured JSON output:

php artisan worklog:start --user=alex --scope=scraper-core --json

2. Direct PHP Facade API (WorklogManager)

Use the WorklogManager facade inside your Laravel controllers, services, or jobs:

use AlexKassel\LaravelWorklogManager\Facades\WorklogManager;

// Start session
$context = WorklogManager::startSession(
    userId: 'alex',
    scope: 'scraper-core',
    boundary: 'Database Schema Migration',
    clientSlug: 'tenant-alpha'
);

// Pause session
WorklogManager::pauseSession(userId: 'alex', reason: 'Lunch break');

// Resume session
WorklogManager::resumeSession(userId: 'alex');

// Close session with metrics
$finalContext = WorklogManager::closeSession(
    userId: 'alex',
    outcome: 'Migration successfully completed',
    nextAction: 'Run seeders',
    metrics: ['items_processed' => 1500]
);

3. HTTP Webhook Ingestion Channel

Post remote session signals to POST /api/v1/worklog/webhook.

Request Headers:

Content-Type: application/json
X-Worklog-Signature: <HMAC-SHA256-SIGNATURE>

Sample JSON Payload:

{
  "event": "session.closed",
  "timestamp": "2026-08-18T21:10:00+02:00",
  "user_id": "alex",
  "client_slug": "tenant-alpha",
  "scope": "scraper-core",
  "payload": {
    "outcome": "Spider run complete",
    "next_action": "Process normalization",
    "metrics": {
      "items_discovered": 150
    }
  }
}

Custom Processor Creation

Implement WorklogProcessorInterface to add custom logging destinations (e.g. Telegram, S3, Elasticsearch):

namespace App\WorklogProcessors;

use Closure;
use AlexKassel\LaravelWorklogManager\Contracts\WorklogProcessorInterface;
use AlexKassel\LaravelWorklogManager\DTOs\WorklogContext;

class TelegramNotificationProcessor implements WorklogProcessorInterface
{
    public function mustSucceed(): bool
    {
        return false; // Non-critical processor
    }

    public function handle(WorklogContext $context, Closure $next): WorklogContext
    {
        if ($context->status === 'CLOSED') {
            // Send notification to Telegram channel
        }

        return $next($context);
    }
}

Add your custom processor to config/worklog-manager.php:

'pipeline' => [
    AlexKassel\LaravelWorklogManager\Processors\MarkdownWorklogProcessor::class,
    App\WorklogProcessors\TelegramNotificationProcessor::class,
],

Testing

Run the package test suite:

composer test

License

The MIT License (MIT). Please see LICENSE for more information.