byrcsc/laravel-checklist · 1.x

Run a checklist.

Start, answer, complete, review, and reopen one checklist while handling unmet requirements.

A checklist run starts from a published version and ends with completion or review. The model methods fit inside your application services or controllers; they own their transactions and dispatch events after commit.

1. Start from the current version

$version = $template->currentVersion();

if ($version === null) {
    abort(409, 'The checklist template has no published version.');
}

$checklist = $version->start(
    subject: $vehicle,
    assignedTo: $driver,
    dueAt: now()->addDay(),
);

Starting creates a pending checklist. Passing an assignee also dispatches ChecklistAssigned after ChecklistCreated.

2. Read items from the pinned version

$items = $checklist->templateVersion
    ->items()
    ->with('section')
    ->get();

Use the checklist's version, not the template's latest version. A newer version may have been published after this run began.

3. Record answers and supporting data

$response = $checklist->answer($item, $request->input('answer'), $driver);

if ($request->filled('note')) {
    $checklist->addNote($response, $request->string('note')->toString());
}

if ($request->hasFile('evidence')) {
    $checklist->addEvidence(
        response: $response,
        file: $request->file('evidence'),
        capturedBy: $driver,
    );
}

An invalid answer throws InvalidAnswerException. An item or response from a different checklist or version throws a checklist or evidence exception.

4. Show every completion blocker

$unmet = $checklist->unmetRequirements();

foreach ($unmet as $requirement) {
    $requirement->itemId;
    $requirement->itemLabel;
    $requirement->reason;
    $requirement->describe();
}

This list includes unanswered required items and triggered requirements for a note or evidence. Hidden items do not appear.

You may also call submit() directly and catch the complete list:

use ByRcsc\LaravelChecklist\Exceptions\IncompleteChecklistException;

try {
    $checklist->submit();
} catch (IncompleteChecklistException $exception) {
    return back()->withErrors([
        'checklist' => array_map(
            fn ($item): string => $item->describe(),
            $exception->unmet,
        ),
    ]);
}

5. Review or return the work

$checklist->review($inspector, outcome: 'accepted');

To correct completed or reviewed work:

$checklist->reopen();
$checklist->answer($item, 'pass', $driver);
$checklist->submit();

Reopening retains responses and evidence but clears the previous review and all derived scoring fields.

Run a checklist.

Start, answer, complete, review, and reopen one checklist while handling unmet requirements.

1. Start from the current version

$version = $template->currentVersion();

if ($version === null) {
    abort(409, 'The checklist template has no published version.');
}

$checklist = $version->start(
    subject: $vehicle,
    assignedTo: $driver,
    dueAt: now()->addDay(),
);

Starting creates a pending checklist. Passing an assignee also dispatches ChecklistAssigned after ChecklistCreated.

2. Read items from the pinned version

$items = $checklist->templateVersion
    ->items()
    ->with('section')
    ->get();

Use the checklist's version, not the template's latest version. A newer version may have been published after this run began.

3. Record answers and supporting data

$response = $checklist->answer($item, $request->input('answer'), $driver);

if ($request->filled('note')) {
    $checklist->addNote($response, $request->string('note')->toString());
}

if ($request->hasFile('evidence')) {
    $checklist->addEvidence(
        response: $response,
        file: $request->file('evidence'),
        capturedBy: $driver,
    );
}

An invalid answer throws InvalidAnswerException. An item or response from a different checklist or version throws a checklist or evidence exception.

4. Show every completion blocker

$unmet = $checklist->unmetRequirements();

foreach ($unmet as $requirement) {
    $requirement->itemId;
    $requirement->itemLabel;
    $requirement->reason;
    $requirement->describe();
}

This list includes unanswered required items and triggered requirements for a note or evidence. Hidden items do not appear.

You may also call submit() directly and catch the complete list:

use ByRcsc\LaravelChecklist\Exceptions\IncompleteChecklistException;

try {
    $checklist->submit();
} catch (IncompleteChecklistException $exception) {
    return back()->withErrors([
        'checklist' => array_map(
            fn ($item): string => $item->describe(),
            $exception->unmet,
        ),
    ]);
}

5. Review or return the work

$checklist->review($inspector, outcome: 'accepted');

To correct completed or reviewed work:

$checklist->reopen();
$checklist->answer($item, 'pass', $driver);
$checklist->submit();

Reopening retains responses and evidence but clears the previous review and all derived scoring fields.

Run a checklist.

1. Start from the current version

2. Read items from the pinned version

3. Record answers and supporting data

4. Show every completion blocker

5. Review or return the work

What to read next

Run a checklist.

1. Start from the current version

2. Read items from the pinned version

3. Record answers and supporting data

4. Show every completion blocker

5. Review or return the work

What to read next