TimeFlow

TimeFlow is a Laravel package specifically designed to track time intervals between different steps in a process directly on your Eloquent models. It helps in analyzing bottlenecks by measuring how long each step takes in a defined sequence.

Features

• Sequential Tracking: Define ordered steps for a process.
• Duration Calculation: Automatically calculates the time difference between the current step and the previous one (or creation time).
• Group Support: Manage multiple different workflows on a single model.
• Polymorphic Relation: Easily attach TimeFlow to any Eloquent model.
• Reporting: Built-in method to generate status reports of the flow.

Installation

Install the package via Composer:

composer require obelaw/timeflow

Run the migrations to create the necessary database table:

php artisan migrate

Setup

To use TimeFlow, add the HasTimeFlow trait to your Eloquent model and define the $timeFlowSequence property.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Obelaw\TimeFlow\Traits\HasTimeFlow;

class Application extends Model
{
    use HasTimeFlow;

    public $timeFlowSequence = [
        'default' => [
            'submitted' => 'Application Submitted',
            'review_started' => 'Under Review',
            'interview_scheduled' => 'Interview Scheduled',
            'offer_sent' => 'Offer Sent',
            'hired' => 'Hired',
        ],
    ];
}

The $timeFlowSequence array keys represent the action_key stored in the database, and the values are the human-readable labels.

Usage

Recording Actions

Use the hitAction method to record that a step has occurred.

$application = Application::find(1);

// Record the 'submitted' step
$application->hitAction('submitted');

When an action is hit:

1. It checks if the action is the next expected step in the sequence.
2. If correct, it creates a log entry with the duration since the last step.
3. If the step is out of order, it will not persist the log (returns a dummy instance), enforcing the sequence integrity.

Calculating Duration

TimeFlow automatically calculates duration_seconds:

• For the first step, it calculates the time difference from the model’s created_at timestamp.
• For subsequent steps, it calculates the time difference from the occurred_at of the previous step.

Reporting

You can retrieve the current state of the flow using getTimeFlowReport. This returns a collection of all steps with their status and duration.

$report = $application->getTimeFlowReport();

// Output:
// [
//    [
//        'key' => 'submitted',
//        'label' => 'Application Submitted',
//        'status' => 'completed',
//        'duration_seconds' => 120,
//        'occurred_at' => ...,
//        'metadata' => null,
//    ],
//    [
//        'key' => 'review_started',
//        'label' => 'Under Review',
//        'status' => 'pending',
//        ...
//    ]
// ]

Advanced Usage

Multiple Groups

You can define multiple sequences (groups) for more complex models.

public $timeFlowSequence = [
    'onboarding' => ['step1', 'step2'],
    'training' => ['module1', 'module2'],
];

To record an action for a specific group:

$user->hitAction('step1', 'onboarding');

Adding Metadata

You can pass an array of metadata when recording an action. This is useful for storing context like user IDs, IP addresses, or related notes.

$application->hitAction('review_started', 'default', [
    'reviewer_id' => auth()->id(),
    'notes' => 'Review started manually'
]);