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

141
api/app/Services/FormBuilder/FormFieldService.php
View File

@@ -29,6 +29,7 @@ final class FormFieldService
private readonly FormFieldBindingService $bindingService,
private readonly FormFieldValidationRuleService $validationRuleService,
private readonly FormFieldConfigService $configService,
private readonly FormFieldConditionalLogicService $conditionalLogicService,
) {}
public function create(FormSchema $schema, array $data): FormField
@@ -40,8 +41,7 @@ final class FormFieldService
$bindingSpec = $this->extractBindingSpec($data);
$validationRuleSpecs = $this->extractValidationRuleSpecs($data);
$this->assertNoConditionalCycle($schema, null, $data['conditional_logic'] ?? null, $data['slug'] ?? null);
[$conditionalTree, $conditionalProvided] = $this->extractConditionalLogicTree($data);
/** @var FormField $field */
$field = FormField::create($data);
@@ -54,6 +54,15 @@ final class FormFieldService
$this->validationRuleService->replaceRules($field, $validationRuleSpecs);
}
if ($conditionalProvided) {
// Cycle check runs inside the service — reads the schema's
// relational adjacency and throws on a back-edge.
if ($conditionalTree !== null) {
$this->conditionalLogicService->assertNoCycles($field, $conditionalTree);
}
$this->conditionalLogicService->replaceLogic($field, $conditionalTree);
}
$this->schemaService->bumpVersion($schema);
$field->logFieldChange('field.created');
@@ -76,18 +85,22 @@ final class FormFieldService
$validationRulesProvided = array_key_exists('validation_rules', $data);
$validationRuleSpecs = $validationRulesProvided ? $this->extractValidationRuleSpecs($data) : null;
[$conditionalTree, $conditionalProvided] = $this->extractConditionalLogicTree($data);
$currentBindingShape = $this->bindingService->toJsonShape($field->bindings()->first());
$currentConditionalShape = $this->conditionalLogicService->toJsonShape($field->rootConditionalLogicGroup());
if ($bindingProvided && $this->bindingChanged($currentBindingShape, $rawBinding)) {
$this->assertBindingChangeAllowed($field, $forceBindingChange);
}
if (array_key_exists('conditional_logic', $data)) {
$this->assertNoConditionalCycle($schema, $field, $data['conditional_logic'], $data['slug'] ?? $field->slug);
if ($conditionalProvided && $conditionalTree !== null) {
$this->conditionalLogicService->assertNoCycles($field, $conditionalTree);
}
$before = [
'binding' => $currentBindingShape,
'conditional_logic' => $currentConditionalShape,
'is_filterable' => $field->is_filterable,
'is_pii' => $field->is_pii,
'field_type' => $field->field_type,
@@ -104,12 +117,17 @@ final class FormFieldService
$this->validationRuleService->replaceRules($field, $validationRuleSpecs ?? []);
}
if ($conditionalProvided) {
$this->conditionalLogicService->replaceLogic($field, $conditionalTree);
}
$this->schemaService->bumpVersion($schema);
$field->logFieldChange('field.updated', [
'old' => $before,
'new' => [
'binding' => $this->bindingService->toJsonShape($field->bindings()->first()),
'conditional_logic' => $this->conditionalLogicService->toJsonShape($field->fresh()?->rootConditionalLogicGroup()),
'is_filterable' => $field->is_filterable,
'is_pii' => $field->is_pii,
'field_type' => $field->field_type,
@@ -305,89 +323,78 @@ final class FormFieldService
}
}
private function assertNoConditionalCycle(FormSchema $schema, ?FormField $subject, mixed $conditionalLogic, ?string $subjectSlug): void
/**
* Extract `conditional_logic` from incoming write-data. Returns a
* tuple `[tree, wasProvided]`: `tree` is the root-group spec (or
* null when the caller cleared logic); `wasProvided` is false when
* the key was absent from the request — we must distinguish "no
* change requested" from "cleared to null".
*
* Strips the `show_when` wrapper (controllers submit the outer JSON
* shape as-is) and rewrites nested `{"all"|"any": [...]}` nodes into
* the service's internal `{"operator", "children"}` form.
*
* @param array<string, mixed> $data
* @return array{0: array<string, mixed>|null, 1: bool}
*/
private function extractConditionalLogicTree(array &$data): array
{
if ($conditionalLogic === null || $subjectSlug === null) {
return;
if (! array_key_exists('conditional_logic', $data)) {
return [null, false];
}
$raw = $data['conditional_logic'];
unset($data['conditional_logic']);
if ($raw === null || $raw === [] || ! is_array($raw)) {
return [null, true];
}
$dependsOn = $this->extractConditionSlugs($conditionalLogic);
if ($dependsOn === []) {
return;
if (isset($raw['show_when']) && is_array($raw['show_when'])) {
/** @var array<string, mixed> $rootGroup */
$rootGroup = $raw['show_when'];
} else {
/** @var array<string, mixed> $rootGroup */
$rootGroup = $raw;
}
$adjacency = $this->buildConditionalAdjacency($schema, $subject, $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);
return [$this->normaliseLegacyGroupShape($rootGroup), true];
}
/**
* @return array<int, string>
* @param array<string, mixed> $node
* @return array<string, mixed>
*/
private function extractConditionSlugs(mixed $logic): array
private function normaliseLegacyGroupShape(array $node): array
{
if (! is_array($logic)) {
return [];
if (isset($node['field_slug'])) {
return $node;
}
$slugs = [];
$walk = function ($node) use (&$walk, &$slugs): void {
if (! is_array($node)) {
return;
}
if (isset($node['field_slug'])) {
$slugs[] = (string) $node['field_slug'];
}
foreach ($node as $child) {
if (isset($node['operator'], $node['children']) && is_array($node['children'])) {
$children = [];
foreach ($node['children'] as $child) {
if (is_array($child)) {
$walk($child);
$children[] = $this->normaliseLegacyGroupShape($child);
}
}
};
$walk($logic);
return array_values(array_unique($slugs));
}
return ['operator' => $node['operator'], 'children' => $children];
}
/**
* @param array<int, string> $seedDeps
* @return array<string, array<int, string>>
*/
private function buildConditionalAdjacency(FormSchema $schema, ?FormField $subject, string $subjectSlug, array $seedDeps): array
{
$fields = FormField::query()
->where('form_schema_id', $schema->id)
->get(['id', 'slug', 'conditional_logic']);
foreach (['all', 'any'] as $candidate) {
if (isset($node[$candidate]) && is_array($node[$candidate])) {
$children = [];
foreach ($node[$candidate] as $child) {
if (is_array($child)) {
$children[] = $this->normaliseLegacyGroupShape($child);
}
}
$adjacency = [];
foreach ($fields as $f) {
if ($subject !== null && $f->id === $subject->id) {
continue;
}
$deps = $this->extractConditionSlugs($f->conditional_logic);
if ($deps !== []) {
$adjacency[$f->slug] = $deps;
return ['operator' => $candidate, 'children' => $children];
}
}
$adjacency[$subjectSlug] = $seedDeps;
return $adjacency;
return $node;
}
/**