Answers and evidence.

Answering an item writes one response row and keeps it. Correcting the answer updates that same row. Attach a photo, file, or signature to it when the answer needs backing, and your application decides how to serve those files later.

One response holds the current answer

$response = $checklist->answer(
    item: $item,
    value: 'pass',
    answeredBy: $driver,
);

The item's type handler validates and casts the value before anything is written. An invalid value leaves both the checklist state and response table unchanged.

There is one response per checklist and item. Answering again updates the same row, replaces the answerer, and dispatches ItemAnswered with $previousValue and $wasAnsweredBefore.

The response copies the item's lineage_ulid when first answered. That lets reports group the same question across template versions without joining back through every historical item.

Notes belong to responses

$checklist->addNote($response, 'Leak appears below the radiator.');
$checklist->addNote($response, null); // clear the note

A non-blank note satisfies a triggered requireNoteWhen() rule. Recording or clearing a note dispatches NoteRecorded with both current and previous note values.

Evidence records a file pointer

use ByRcsc\LaravelChecklist\Enums\EvidenceType;

$evidence = $checklist->addEvidence(
    response: $response,
    file: $uploadedFile,
    type: EvidenceType::Photo,
    capturedBy: $inspector,
);

The row records:

• evidence type: photo, file, or signature;
• filesystem disk and generated path;
• MIME type detected from the file contents;
• byte size and SHA-256 content hash;
• optional capturer and capture time.

Files are stored below checklists/{checklist}/responses/{response}/ with a new ULID filename. Executable and active-content extensions, including PHP, HTML, JavaScript, SVG, shell, and executable formats, are removed from the stored filename.

Storage and the database are not one transaction

Evidence addition writes the file before its database row. If a surrounding database transaction later rolls back, the file can remain as an orphan. A retention task may sweep unreferenced files under the checklist prefix.

Evidence removal deletes the row first and schedules file deletion after the database commit. A rollback therefore retains both the row and file.

$checklist->removeEvidence($evidence);

Deleting a response or checklist also deletes its evidence files through model events. A raw database delete bypasses that cleanup.

Hidden answers stay in the record

When a visibility rule hides an answered item, the package sets is_applicable to false. It retains the answer, note, and evidence. If the branch becomes visible again, the same response returns to the calculation.

What it does not do

The package does not create download routes, signed URLs, thumbnails, malware scans, retention jobs, or per-file authorization. Use the recorded disk and path inside your policies and storage routes.

What to read next

• Conditional rules to require notes or evidence from specific answers.
• Configuration to select the evidence disk.
• Export and report to include file references while preserving the recorded checklist.