Models and scopes.

The package exposes its Eloquent models for admin interfaces, checklist runs, dashboards, and reports. Every concrete model is final and resolves its table through checklist.table_names.

Template and version

Models\Template:

versions(): HasMany
currentVersion(): ?TemplateVersion
draftVersion(): ?TemplateVersion
hasPublishedVersions(): bool

Models\TemplateVersion:

template(): BelongsTo
sections(): HasMany
rootSections(): HasMany
items(): HasMany
rootItems(): HasMany
rules(): HasMany
checklists(): HasMany
isDraft(): bool
isPublished(): bool
publish(): self
newDraft(): self
start(
    ?Model $subject = null,
    ?Model $assignedTo = null,
    ?Carbon $dueAt = null,
): Checklist

Sections and items are ordered by position. Root relations filter out parent section or section identifiers.

Structure models

Models\Section exposes templateVersion(), parent(), children(), and items(). Child sections and items are ordered by position.

Models\Item exposes templateVersion(), section(), and rules(). Its casts include ItemType, float weight, booleans, and array configuration.

Models\Rule exposes templateVersion(), item(), target(), isVisibility(), isRequirement(), and targetsSection().

Checklist execution

Models\Checklist:

responseFor(Item $item): ?Response
answer(Item $item, mixed $value, ?Model $answeredBy = null): Response
addNote(Response $response, ?string $note): Response
unmetRequirements(): array
addEvidence(
    Response $response,
    UploadedFile $file,
    EvidenceType|string $type = EvidenceType::File,
    ?Model $capturedBy = null,
): Evidence
removeEvidence(Evidence $evidence): void
assign(Model $assignee): self
submit(): self
review(Model $reviewer, ?string $outcome = null): self
reopen(): self
sectionScore(Section|int $section): ?float
criticalFailures(): array
toExport(): ChecklistExport

State predicates are isPending(), isInProgress(), isCompleted(), isReviewed(), and isClosed().

Relations are templateVersion(), schedule(), actions(), responses(), subject(), assignedTo(), and reviewedBy().

Response, evidence, action, and schedule

Models\Response exposes checklist(), item(), evidence(), answeredBy(), and isAnswered().

Models\Evidence exposes response() and capturedBy().

Models\Action exposes checklist(), item(), response(), and actor(). Updates and deletes throw AppendOnlyException.

Models\Schedule exposes template(), checklists(), assignee(), subject(), and hasOpenChecklist().

Checklist query scopes

withExportRelations()
withStatus(ChecklistStatus ...$statuses)
overdue()
completedBetween(mixed $from, mixed $to)
forTemplate(Template|int $template)
forAssignee(Model $assignee)
forSubject(Model $subject)
assignedTo(Model $assignee)
pending()
inProgress()
completed()
reviewed()

forAssignee() delegates to assignedTo(). forTemplate() includes every version of the template.

Application model trait

Concerns\HasChecklists adds:

checklists(): MorphMany
latestChecklist(): ?Checklist

latestChecklist() orders by checklist identifier, not started_at, because an untouched new checklist has no start time.

Export and report entry points

ChecklistExport::for(Checklist $checklist): self
$export->toArray(): array
$export->jsonSerialize(): array
$export->signatures(): array

Reports::completionRate(?Template $template = null): array
Reports::averageScore(?Template $template = null): array
Reports::mostFailedItems(int $limit = 20): array
Reports::overdueByAssignee(): array
Reports::criticalFailures(?Template $template = null): array

Report arrays contain CompletionRate, AverageScore, FailedItem, OverdueAssignee, or CriticalFailure data objects. Each exposes public readonly constructor properties and toArray().

What to read next

• Checklist lifecycle for transition semantics.
• Export and report for query and rendering examples.
• Enums and contracts for cast values and extension points.