bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(form-builder): FormFieldConditionalLogicService + cycle detection + legacy backfill + snapshot

Browse Source 
WS-5c commit 2 of 4 — the service layer, backfill migration, and
read-path switch. Per addendum Q3, conditional_logic applies to
FormField only — no library mirror and no copyLogic on
FormFieldService::insertFromLibrary.

FormFieldConditionalLogicService owns every write:
  - logicFor(field): depth-limited eager-load of the tree
  - replaceLogic(field, tree): transactional structure + operator +
    field_slug validation + cycle check + activity-log emit
    (field.conditional_logic_replaced)
  - toJsonShape(root): reconstructs the canonical ARCH §8
    `{show_when: {...}}` shape — single source of truth for the
    snapshot writer + API resources
  - assertSpecsValid(tree): public boundary guard for the FormRequest
    strict validator (WS-5c commit 3 wires this up)
  - assertNoCycles(field, tree): contract preserved from
    FormFieldService::assertNoConditionalCycle, implementation now
    reads the relational adjacency.

Backfill migration translates pre-WS-5c conditional_logic JSON to
rows. Strict dispatch: unknown operators / unknown top-level keys /
malformed groups FAIL the migration — Phase A seed-scan confirmed
the catalogue parity, so any drift is a data bug to fix at source,
not silently absorb. Rollback rebuilds canonical JSON and clears
the relational tree.

FormFieldService.create/update route `conditional_logic` through
the new service (matching the extract-and-delegate pattern from
WS-5a bindings and WS-5b validation rules). Snapshot writer + both
resources (FormFieldResource, PublicFormSchemaResource) read via
`toJsonShape(rootConditionalLogicGroup())` — byte-for-byte parity
with the pre-WS-5c JSON contract.

InvalidConditionalLogicSpecException handled in FormFieldController
as 422, same as FrozenSchemaException / CyclicDependencyException.

Tests: 20 new under tests/Feature/FormBuilder/ConditionalLogic/
(service, cycle detection, backfill forward+rollback+failure cases,
snapshot + resource parity). FormFieldApiTest cyclic rejection test
rewritten to use the new factory state. Rollback step counts in
WS-5a/b migration tests bumped +1 for the new backfill migration.
Baseline 1122 → 1142 green (3032 → 3085 assertions).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-24 23:56:39 +02:00
parent 2064b9901e
commit d06ea01b09
16 changed files with 1514 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

467
api/app/Services/FormBuilder/FormFieldConditionalLogicService.php Normal file
View File

@@ -0,0 +1,467 @@
<?php
declare(strict_types=1);
namespace App\Services\FormBuilder;
use App\Enums\FormBuilder\FormFieldConditionalLogicConditionOperator;
use App\Enums\FormBuilder\FormFieldConditionalLogicGroupOperator;
use App\Exceptions\FormBuilder\CyclicDependencyException;
use App\Exceptions\FormBuilder\InvalidConditionalLogicSpecException;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldConditionalLogicCondition;
use App\Models\FormBuilder\FormFieldConditionalLogicGroup;
use Illuminate\Support\Facades\DB;
/**
* Owns all writes to `form_field_conditional_logic_groups` and
* `form_field_conditional_logic_conditions`. Single source of truth for:
*
* - tree-shape validation (root must be a group; conditions are leaves)
* - operator enum enforcement (group + comparison)
* - field_slug existence check against the owning schema
* - cross-field cycle detection (ARCH §8 — contract unchanged from
* FormFieldService::assertNoConditionalCycle, implementation moved here)
* - serialisation back to the canonical ARCH §8 `{show_when: {...}}` JSON
* shape consumed by the snapshot writer and API resources
*
* Per addendum Q3, conditional_logic applies to FormField only — there is
* no library mirror and no `copyLogic` method on `FormFieldService::insert
* FromLibrary`.
*
* Activity log convention — matches WS-5a/b: emit
* `field.conditional_logic_replaced` on the FormField subject.
*/
final class FormFieldConditionalLogicService
{
/**
* Eager-load the tree (root + all descendants + all leaf conditions).
* Bounded to 5 recursion levels — matches the OrganisationScope cap
* raise (WS-5c infrastructure) and the observed production ceiling.
*/
public function logicFor(FormField $field): ?FormFieldConditionalLogicGroup
{
$root = $field->conditionalLogicGroups()
->whereNull('parent_group_id')
->with($this->nestedEagerLoad(5))
->first();
return $root;
}
/**
* Replace the full conditional-logic tree on a field transactionally.
* Validates structure, operators, field_slug references, and cross-
* field cycles before any write lands. Emits the semantic activity-log
* entry on the owning FormField.
*
* Passing `null` clears the logic entirely (matches the legacy
* `conditional_logic = null` JSON state).
*
* @param array<string, mixed>|null $tree root group shape (no
* `show_when` wrapper — callers unwrap the wrapper before calling)
*/
public function replaceLogic(FormField $field, ?array $tree): void
{
if ($tree === null || $tree === []) {
DB::transaction(function () use ($field): void {
$this->deleteExistingTree($field);
$field->logFieldChange('field.conditional_logic_replaced', [
'count' => 0,
]);
});
return;
}
$this->assertSpecsValid($tree);
$this->assertFieldSlugsResolve($field, $tree);
$this->assertNoCycles($field, $tree);
DB::transaction(function () use ($field, $tree): void {
$this->deleteExistingTree($field);
$this->insertNode($field->id, null, $tree, 0);
$field->logFieldChange('field.conditional_logic_replaced', [
'count' => $this->countNodes($tree),
]);
});
}
/**
* Serialise a root group (plus its subtree) back to the ARCH §8
* `{show_when: {...}}` JSON shape. Returns null when the field has no
* logic — matches the pre-WS-5c `conditional_logic = null` state.
*/
public function toJsonShape(?FormFieldConditionalLogicGroup $root): ?array
{
if ($root === null) {
return null;
}
return [
'show_when' => $this->renderGroup($root),
];
}
/**
* Public guard the FormRequests invoke in their `after()` hook (WS-5c
* commit 3 strict validator on save). Rejects bad tree structure at
* the HTTP boundary before any write lands.
*
* @param array<string, mixed> $tree root group shape
*/
public function assertSpecsValid(array $tree): void
{
$this->assertNodeValid($tree, isRoot: true);
}
/**
* Cross-field cycle detection (ARCH §8; contract preserved from the
* pre-WS-5c `FormFieldService::assertNoConditionalCycle`). Builds a
* dependency graph over every field in the owning schema — this field's
* proposed tree plus the persisted trees of every sibling — and runs
* DFS from this field's slug. A back-edge raises.
*
* @param array<string, mixed> $tree proposed root group shape
*/
public function assertNoCycles(FormField $field, array $tree): void
{
$subjectSlug = (string) $field->slug;
$dependsOn = $this->extractDependencySlugs($tree);
if ($dependsOn === []) {
return;
}
$adjacency = $this->buildSchemaAdjacency($field);
$adjacency[$subjectSlug] = $dependsOn;
$visiting = [];
$visited = [];
$walk = function (string $node) use (&$walk, &$adjacency, &$visiting, &$visited, $subjectSlug): void {
if (isset($visited[$node])) {
return;
}
if (isset($visiting[$node])) {
throw CyclicDependencyException::forField($subjectSlug);
}
$visiting[$node] = true;
foreach ($adjacency[$node] ?? [] as $next) {
$walk($next);
}
unset($visiting[$node]);
$visited[$node] = true;
};
$walk($subjectSlug);
}
// --- internals ----------------------------------------------------
private function deleteExistingTree(FormField $field): void
{
// Cascade: deleting the root groups deletes all descendants and
// all conditions via the DB-level ON DELETE CASCADE chain.
FormFieldConditionalLogicGroup::query()
->withoutGlobalScopes()
->where('form_field_id', $field->id)
->whereNull('parent_group_id')
->get()
->each(fn (FormFieldConditionalLogicGroup $g) => $g->delete());
// Defensive: clear any orphaned descendants (should never exist
// after the root delete, but we guard against partial failures).
FormFieldConditionalLogicGroup::query()
->withoutGlobalScopes()
->where('form_field_id', $field->id)
->delete();
}
/**
* @param array<string, mixed> $node
*/
private function insertNode(string $fieldId, ?string $parentGroupId, array $node, int $sortOrder): void
{
if (isset($node['field_slug'])) {
$operator = FormFieldConditionalLogicConditionOperator::from((string) $node['operator']);
FormFieldConditionalLogicCondition::query()->withoutGlobalScopes()->create([
'group_id' => $parentGroupId,
'field_slug' => (string) $node['field_slug'],
'comparison_operator' => $operator->value,
'value' => $operator->isValueless() ? null : ($node['value'] ?? null),
'sort_order' => $sortOrder,
]);
return;
}
$groupOperator = FormFieldConditionalLogicGroupOperator::from((string) $node['operator']);
$group = FormFieldConditionalLogicGroup::query()->withoutGlobalScopes()->create([
'form_field_id' => $fieldId,
'parent_group_id' => $parentGroupId,
'operator' => $groupOperator->value,
'sort_order' => $sortOrder,
]);
/** @var array<int, array<string, mixed>> $children */
$children = $node['children'] ?? [];
foreach ($children as $childSortOrder => $child) {
$this->insertNode($fieldId, $group->id, $child, (int) $childSortOrder);
}
}
/**
* @param array<string, mixed> $node
*/
private function assertNodeValid(array $node, bool $isRoot): void
{
if (isset($node['field_slug'])) {
if ($isRoot) {
throw new InvalidConditionalLogicSpecException(
'Conditional logic tree root must be a group (with an "all" or "any" operator), not a bare condition.',
);
}
$rawOperator = (string) ($node['operator'] ?? '');
if (FormFieldConditionalLogicConditionOperator::tryFrom($rawOperator) === null) {
throw new InvalidConditionalLogicSpecException(
"Unknown comparison operator '{$rawOperator}'. Valid operators: "
.implode(', ', array_map(
fn (FormFieldConditionalLogicConditionOperator $op) => $op->value,
FormFieldConditionalLogicConditionOperator::cases(),
))
.'.',
);
}
$slug = (string) ($node['field_slug'] ?? '');
if ($slug === '') {
throw new InvalidConditionalLogicSpecException(
'Condition requires a non-empty field_slug.',
);
}
return;
}
$rawOperator = (string) ($node['operator'] ?? '');
if (FormFieldConditionalLogicGroupOperator::tryFrom($rawOperator) === null) {
throw new InvalidConditionalLogicSpecException(
"Unknown group operator '{$rawOperator}'. Valid operators: all, any.",
);
}
$children = $node['children'] ?? null;
if (! is_array($children) || $children === []) {
throw new InvalidConditionalLogicSpecException(
'Conditional logic groups must have at least one child (group or condition).',
);
}
foreach ($children as $child) {
if (! is_array($child)) {
throw new InvalidConditionalLogicSpecException(
'Group children must be arrays (group or condition nodes).',
);
}
$this->assertNodeValid($child, isRoot: false);
}
}
/**
* @param array<string, mixed> $tree
*/
private function assertFieldSlugsResolve(FormField $field, array $tree): void
{
$slugs = $this->extractDependencySlugs($tree);
if ($slugs === []) {
return;
}
$known = FormField::query()
->withoutGlobalScopes()
->where('form_schema_id', $field->form_schema_id)
->pluck('slug')
->all();
$missing = array_values(array_diff($slugs, $known));
if ($missing !== []) {
throw new InvalidConditionalLogicSpecException(
'Conditional logic references unknown field_slug(s): '.implode(', ', $missing).'.',
);
}
}
/**
* @param array<string, mixed> $tree
* @return list<string>
*/
private function extractDependencySlugs(array $tree): array
{
$out = [];
$walk = function (array $node) use (&$walk, &$out): void {
if (isset($node['field_slug'])) {
$out[] = (string) $node['field_slug'];
return;
}
foreach ($node['children'] ?? [] as $child) {
if (is_array($child)) {
$walk($child);
}
}
};
$walk($tree);
return array_values(array_unique($out));
}
/**
* @param array<string, mixed> $tree
*/
private function countNodes(array $tree): int
{
$count = 0;
$walk = function (array $node) use (&$walk, &$count): void {
$count++;
foreach ($node['children'] ?? [] as $child) {
if (is_array($child)) {
$walk($child);
}
}
};
$walk($tree);
return $count;
}
/**
* Build a slug → list-of-dependent-slugs map for every OTHER field in
* the owning schema. Subject slug is excluded; caller merges its
* proposed deps in separately. Reads from the relational tables — the
* post-WS-5c source of truth.
*
* @return array<string, list<string>>
*/
private function buildSchemaAdjacency(FormField $subject): array
{
$siblings = FormField::query()
->withoutGlobalScopes()
->where('form_schema_id', $subject->form_schema_id)
->where('id', '!=', $subject->id)
->get(['id', 'slug']);
if ($siblings->isEmpty()) {
return [];
}
$adjacency = [];
foreach ($siblings as $sibling) {
$root = $sibling->rootConditionalLogicGroup();
if ($root === null) {
continue;
}
$deps = $this->collectConditionSlugsFromPersistedTree($root);
if ($deps !== []) {
$adjacency[(string) $sibling->slug] = $deps;
}
}
return $adjacency;
}
/**
* @return list<string>
*/
private function collectConditionSlugsFromPersistedTree(FormFieldConditionalLogicGroup $root): array
{
$slugs = [];
$walk = function (FormFieldConditionalLogicGroup $group) use (&$walk, &$slugs): void {
foreach ($group->conditions as $condition) {
$slugs[] = (string) $condition->field_slug;
}
foreach ($group->childGroups as $child) {
$walk($child);
}
};
$walk($root);
return array_values(array_unique($slugs));
}
/**
* @return array<string, mixed>
*/
private function renderGroup(FormFieldConditionalLogicGroup $group): array
{
$conditions = $group->conditions->map(fn (FormFieldConditionalLogicCondition $c) => [
'node' => $this->renderCondition($c),
'sort_order' => (int) $c->sort_order,
'id' => (string) $c->id,
]);
$children = $group->childGroups->map(fn (FormFieldConditionalLogicGroup $g) => [
'node' => $this->renderGroup($g),
'sort_order' => (int) $g->sort_order,
'id' => (string) $g->id,
]);
// Interleave by sort_order, stable secondary by id.
$merged = $conditions->concat($children)
->sortBy([
['sort_order', 'asc'],
['id', 'asc'],
])
->values()
->map(fn (array $entry): array => $entry['node'])
->all();
$operatorValue = $group->operator instanceof FormFieldConditionalLogicGroupOperator
? $group->operator->value
: (string) $group->operator;
return [$operatorValue => $merged];
}
/**
* @return array<string, mixed>
*/
private function renderCondition(FormFieldConditionalLogicCondition $condition): array
{
$operator = $condition->comparison_operator instanceof FormFieldConditionalLogicConditionOperator
? $condition->comparison_operator
: FormFieldConditionalLogicConditionOperator::from((string) $condition->comparison_operator);
$row = [
'field_slug' => (string) $condition->field_slug,
'operator' => $operator->value,
];
if (! $operator->isValueless()) {
$row['value'] = $condition->value;
}
return $row;
}
/**
* Depth-bounded eager-load spec for logicFor. Builds nested
* `childGroups.childGroups...` strings up to the given depth, with
* `conditions` on each level.
*
* @return list<string>
*/
private function nestedEagerLoad(int $depth): array
{
$loads = ['conditions'];
$prefix = '';
for ($i = 0; $i < $depth; $i++) {
$prefix = $prefix === '' ? 'childGroups' : $prefix.'.childGroups';
$loads[] = $prefix;
$loads[] = $prefix.'.conditions';
}
return $loads;
}
}