byrcsc/laravel-checklist · 1.x

Author a template.

Build and publish a validated checklist template in one transaction or edit its next draft with Eloquent.

There are two ways to author a template. The fluent builder fits structures you know in code; the public models fit an admin interface that edits a draft across several requests.

1. Build the common structure

use ByRcsc\LaravelChecklist\Authoring\TemplateBuilder;

$version = TemplateBuilder::make('Warehouse close-down')
    ->passThreshold(90)
    ->section('Doors', function (TemplateBuilder $builder): void {
        $builder->checkbox('Loading doors locked')
            ->required()
            ->critical();

        $builder->checkbox('Office doors locked')
            ->required();
    })
    ->section('Utilities', function (TemplateBuilder $builder): void {
        $builder->yesNo('Any equipment left running?')
            ->showWhen(true, 'equipment-details');

        $builder->text('Describe the equipment', maxLength: 500)
            ->key('equipment-details')
            ->required();
    })
    ->publish();

Nothing reaches the database until publish(). The builder persists and validates everything inside one transaction.

2. Put modifiers beside their item

required(), critical(), weight(), key(), and each rule method apply to the item declared immediately before them.

$builder->rating('Cleanliness', min: 1, max: 5)
    ->required()
    ->weight(2);

Do not put an item modifier after a section callback. The builder clears its item cursor at every section boundary and throws instead of modifying an item from another scope.

3. Add conditional requirements

use ByRcsc\LaravelChecklist\Enums\RuleOperator;

$builder->passFail('Emergency exit is clear')
    ->requireEvidenceWhen('fail', 'photo')
    ->requireNoteWhen('fail');

$builder->number('Freezer temperature')
    ->requireNoteWhen(-18, operator: RuleOperator::Above);

Rule targets may appear before or after their source, because target resolution runs when the builder persists the complete version. Every target key must be unique.

4. Edit a new draft

$draft = $version->newDraft();

$draft->update(['pass_threshold' => 85]);

$draft->items()
    ->where('label', 'Office doors locked')
    ->firstOrFail()
    ->update(['label' => 'Office doors and windows locked']);

$published = $draft->publish();

Model events allow these writes while the version is a draft. Publishing runs the same full validation as the fluent builder.

5. Build drafts directly for an admin interface

Create a Template and a draft TemplateVersion, then create sections, items, and rules through their models. Item creates a lineage_ulid automatically when it is omitted.

Keep all edits on model instances. Query-builder updates bypass the published version guards because Laravel does not dispatch model events for them.

Author a template.

Build and publish a validated checklist template in one transaction or edit its next draft with Eloquent.

There are two ways to author a template. The fluent builder fits structures you know in code; the public models fit an admin interface that edits a draft across several requests.

1. Build the common structure

use ByRcsc\LaravelChecklist\Authoring\TemplateBuilder;

$version = TemplateBuilder::make('Warehouse close-down')
    ->passThreshold(90)
    ->section('Doors', function (TemplateBuilder $builder): void {
        $builder->checkbox('Loading doors locked')
            ->required()
            ->critical();

        $builder->checkbox('Office doors locked')
            ->required();
    })
    ->section('Utilities', function (TemplateBuilder $builder): void {
        $builder->yesNo('Any equipment left running?')
            ->showWhen(true, 'equipment-details');

        $builder->text('Describe the equipment', maxLength: 500)
            ->key('equipment-details')
            ->required();
    })
    ->publish();

Nothing reaches the database until publish(). The builder persists and validates everything inside one transaction.

2. Put modifiers beside their item

required(), critical(), weight(), key(), and each rule method apply to the item declared immediately before them.

$builder->rating('Cleanliness', min: 1, max: 5)
    ->required()
    ->weight(2);

Do not put an item modifier after a section callback. The builder clears its item cursor at every section boundary and throws instead of modifying an item from another scope.

3. Add conditional requirements

use ByRcsc\LaravelChecklist\Enums\RuleOperator;

$builder->passFail('Emergency exit is clear')
    ->requireEvidenceWhen('fail', 'photo')
    ->requireNoteWhen('fail');

$builder->number('Freezer temperature')
    ->requireNoteWhen(-18, operator: RuleOperator::Above);

Rule targets may appear before or after their source, because target resolution runs when the builder persists the complete version. Every target key must be unique.

4. Edit a new draft

$draft = $version->newDraft();

$draft->update(['pass_threshold' => 85]);

$draft->items()
    ->where('label', 'Office doors locked')
    ->firstOrFail()
    ->update(['label' => 'Office doors and windows locked']);

$published = $draft->publish();

Model events allow these writes while the version is a draft. Publishing runs the same full validation as the fluent builder.

5. Build drafts directly for an admin interface

Create a Template and a draft TemplateVersion, then create sections, items, and rules through their models. Item creates a lineage_ulid automatically when it is omitted.

Keep all edits on model instances. Query-builder updates bypass the published version guards because Laravel does not dispatch model events for them.

Author a template.

1. Build the common structure

2. Put modifiers beside their item

3. Add conditional requirements

4. Edit a new draft

5. Build drafts directly for an admin interface

What to read next

Author a template.

1. Build the common structure

2. Put modifiers beside their item

3. Add conditional requirements

4. Edit a new draft

5. Build drafts directly for an admin interface

What to read next