›
byrcsc/laravel-checklist · 1.x
Publish a vehicle inspection, answer it, attach evidence, submit it, and record a review.
This tutorial runs one vehicle inspection from authoring through review. It
assumes the package migrations are installed and Vehicle and User are
models in your application.
namespace App\Models;
use ByRcsc\LaravelChecklist\Concerns\HasChecklists;
use Illuminate\Database\Eloquent\Model;
final class Vehicle extends Model
{
use HasChecklists;
}The trait adds checklists() and latestChecklist() through the checklist's
polymorphic subject relation.
use ByRcsc\LaravelChecklist\Authoring\TemplateBuilder;
$version = TemplateBuilder::make('Vehicle pre-trip inspection')
->passThreshold(80)
->section('Exterior', function (TemplateBuilder $builder): void {
$builder->passFail('Tires are roadworthy')
->required()
->critical();
$builder->passFail('No fluid leaks')
->requireEvidenceWhen('fail', 'photo');
})
->text('Notes', maxLength: 500)
->publish();publish() writes the template, version, section, items, and rule in one
transaction. It returns a published TemplateVersion.
$checklist = $version->start(
subject: $vehicle,
assignedTo: $driver,
dueAt: now()->addDay(),
);
$tires = $version->items()
->where('label', 'Tires are roadworthy')
->firstOrFail();
$leaks = $version->items()
->where('label', 'No fluid leaks')
->firstOrFail();
$checklist->answer($tires, 'pass', $driver);
$leakResponse = $checklist->answer($leaks, 'fail', $driver);The first valid answer moves the checklist from pending to in_progress.
The pass/fail handler stores both answers as booleans.
The failing leak answer is accepted. Its rule needs a response row before a photo can be attached, so the missing evidence blocks submission rather than the answer.
In a controller, pass the validated upload to the checklist:
use ByRcsc\LaravelChecklist\Enums\EvidenceType;
use Illuminate\Http\Request;
$photo = $request->file('damage_photo');
if ($photo === null) {
abort(422, 'A damage photo is required.');
}
$checklist->addEvidence(
response: $leakResponse,
file: $photo,
type: EvidenceType::Photo,
capturedBy: $driver,
);The package writes the file to the configured disk and records its detected MIME type, size, SHA-256 hash, capture time, and capturer.
$checklist->submit();
$checklist->review(
reviewer: $inspector,
outcome: 'accepted with repair required',
);Submission checks required items and conditional requirements before storing scores. Review vocabulary belongs to your application; the package stores the outcome without interpreting it.
$checklist->status; // ChecklistStatus::Reviewed
$checklist->score; // ratio from 0.0 to 1.0, or null
$checklist->passed; // true, false, or null
$checklist->critical_failed; // boolean
$checklist->toExport()->toArray();The failed leak answer scores zero. Whether the checklist passes depends on the total weighted score and the critical tire item.