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

feat(form-builder): add PublishGuard framework + 9 concrete guards (WS-6)

Browse Source 
Per-purpose schema validation composes a PurposeGuardProvider returning
a list of guards. Errors collected (not first-fail) so the builder UI
surfaces every issue per save. ConditionalRequirement composes higher-
order without proliferating one-off classes.

RequiresIdentityKeyBinding checks the is_identity_key flag specifically;
the binding-existence check is handled additively by the existing
assertRequiredBindingsPresent in FormSchemaService.

SchemaHasLinkedEvent checks owner_type='event' + owner_id (FormSchema
uses polymorphic owner; there is no direct event_id column).

i18n messages live in lang/nl/form_builder_publish_guards.php.

Refs: RFC-WS-6.md §3 (Q13), §4 (V1, V3)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-25 22:55:42 +02:00
parent c5b0210ae7
commit 81a8120f98
21 changed files with 1156 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
api/app/FormBuilder/Publishing/AppendStrategyRequiresCollectionTarget.php Normal file
View File

@@ -0,0 +1,75 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Enums\FormBuilder\BindingTargetType;
use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
use App\Exceptions\FormBuilder\UnknownBindingTargetException;
use App\FormBuilder\Bindings\BindingTypeRegistry;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §4 (V1) — Append is collection-only. Targets unknown to
* BindingTypeRegistry fail with a distinct context payload so admins
* see the actionable distinction.
*/
final readonly class AppendStrategyRequiresCollectionTarget implements PublishGuard
{
public function __construct(private BindingTypeRegistry $registry) {}
public function code(): string
{
return 'append_strategy_requires_collection_target';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
/** @var FormField $field */
foreach ($schema->fields as $field) {
/** @var FormFieldBinding $binding */
foreach ($field->bindings as $binding) {
if ($binding->merge_strategy !== FormFieldBindingMergeStrategy::Append) {
continue;
}
$entity = (string) $binding->target_entity;
$attribute = (string) $binding->target_attribute;
try {
$meta = $this->registry->resolve($entity, $attribute);
} catch (UnknownBindingTargetException) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.append_strategy_requires_collection_target',
offendingFormFieldId: (string) $field->id,
context: [
'reason' => 'unknown_target',
'entity' => $entity,
'attribute' => $attribute,
],
);
}
if ($meta->type !== BindingTargetType::COLLECTION) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.append_strategy_requires_collection_target',
offendingFormFieldId: (string) $field->id,
context: [
'reason' => 'scalar_target',
'entity' => $entity,
'attribute' => $attribute,
'target_type' => $meta->type->value,
],
);
}
}
}
return PublishGuardResult::passed($this->code());
}
}

52
api/app/FormBuilder/Publishing/ConditionalRequirement.php Normal file
View File

@@ -0,0 +1,52 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormSchema;
use Closure;
/**
* RFC-WS-6 §3 (Q13) — higher-order composer. Runs the predicate first;
* delegates to the sub-guard only if the predicate returns true.
* Otherwise returns passed().
*/
final readonly class ConditionalRequirement implements PublishGuard
{
/**
* @param Closure(FormSchema): bool $predicate
*/
public function __construct(
private Closure $predicate,
private PublishGuard $subGuard,
private string $code,
) {}
public function code(): string
{
return "conditional:{$this->code}";
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
if (! ($this->predicate)($schema)) {
return PublishGuardResult::passed($this->code());
}
$subResult = $this->subGuard->evaluate($schema);
if ($subResult->passed) {
return PublishGuardResult::passed($this->code());
}
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: $subResult->messageKey ?? 'form_builder_publish_guards.conditional',
offendingFormFieldId: $subResult->offendingFormFieldId,
context: array_merge(
$subResult->context,
['delegated_to' => $this->subGuard->code()],
),
);
}
}

67
api/app/FormBuilder/Publishing/IdentityKeyBindingsOnlyInFirstSection.php Normal file
View File

@@ -0,0 +1,67 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
use App\Models\FormBuilder\FormSchemaSection;
/**
* RFC-WS-6 §3 (Q10) — when section_level_submit is active, identity-key
* bindings must live in the first section (lowest sort_order).
*
* No-op when section_level_submit is false. Universal: wires into every
* PurposeGuardProvider.
*/
final class IdentityKeyBindingsOnlyInFirstSection implements PublishGuard
{
public function code(): string
{
return 'identity_key_bindings_only_in_first_section';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
if (! (bool) $schema->section_level_submit) {
return PublishGuardResult::passed($this->code());
}
$sections = $schema->sections;
if ($sections->isEmpty()) {
return PublishGuardResult::passed($this->code());
}
/** @var FormSchemaSection $first */
$first = $sections->sortBy('sort_order')->first();
$firstSectionId = (string) $first->id;
/** @var FormField $field */
foreach ($schema->fields as $field) {
$hasIdentityKey = false;
/** @var FormFieldBinding $binding */
foreach ($field->bindings as $binding) {
if ((bool) $binding->is_identity_key) {
$hasIdentityKey = true;
break;
}
}
if (! $hasIdentityKey) {
continue;
}
if ((string) $field->form_schema_section_id !== $firstSectionId) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.identity_key_bindings_only_in_first_section',
offendingFormFieldId: (string) $field->id,
);
}
}
return PublishGuardResult::passed($this->code());
}
}

50
api/app/FormBuilder/Publishing/MaxOneIdentityKeyPerTargetEntity.php Normal file
View File

@@ -0,0 +1,50 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q8) — composite identity-key resolution is out of scope
* for v1; this guard enforces single-key per target_entity at publish
* time. Universal: wires into every PurposeGuardProvider.
*/
final class MaxOneIdentityKeyPerTargetEntity implements PublishGuard
{
public function code(): string
{
return 'max_one_identity_key_per_target_entity';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
$countsByEntity = [];
/** @var FormField $field */
foreach ($schema->fields as $field) {
/** @var FormFieldBinding $binding */
foreach ($field->bindings as $binding) {
if (! (bool) $binding->is_identity_key) {
continue;
}
$entity = (string) $binding->target_entity;
$countsByEntity[$entity] = ($countsByEntity[$entity] ?? 0) + 1;
}
}
foreach ($countsByEntity as $entity => $count) {
if ($count > 1) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.max_one_identity_key_per_target_entity',
context: ['entity' => $entity, 'count' => $count],
);
}
}
return PublishGuardResult::passed($this->code());
}
}

57
api/app/FormBuilder/Publishing/NoAmbiguousTrustLevels.php Normal file
View File

@@ -0,0 +1,57 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q7) — within any (target_entity, target_attribute) group,
* no two bindings may share the same trust_level. Tie-breaker exists
* (sort_order) but ambiguity at config time is rejected.
*/
final class NoAmbiguousTrustLevels implements PublishGuard
{
public function code(): string
{
return 'no_ambiguous_trust_levels';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
/** @var array<string, array<int, array<int, string>>> $byTargetTrust */
$byTargetTrust = [];
/** @var FormField $field */
foreach ($schema->fields as $field) {
/** @var FormFieldBinding $binding */
foreach ($field->bindings as $binding) {
$key = $binding->target_entity . '.' . $binding->target_attribute;
$trust = (int) $binding->trust_level;
$byTargetTrust[$key][$trust][] = (string) $field->id;
}
}
foreach ($byTargetTrust as $target => $trustGroups) {
foreach ($trustGroups as $trust => $fieldIds) {
if (count($fieldIds) > 1) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.no_ambiguous_trust_levels',
offendingFormFieldId: $fieldIds[0],
context: [
'target' => $target,
'trust_level' => $trust,
'form_field_ids' => $fieldIds,
],
);
}
}
}
return PublishGuardResult::passed($this->code());
}
}

29
api/app/FormBuilder/Publishing/PublishGuard.php Normal file
View File

@@ -0,0 +1,29 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q13) — pre-publish constraint contract.
*
* `FormSchemaService::publish()` walks every guard returned by the
* purpose's `PurposeGuardProvider`, collecting all violations (not
* first-fail) before throwing `PublishGuardViolationException`.
*
* Guards must NOT issue N+1 queries; the service eager-loads
* `fields.bindings` and `sections` before evaluation.
*/
interface PublishGuard
{
public function evaluate(FormSchema $schema): PublishGuardResult;
/**
* Stable identifier used in error responses and tests.
* Examples: 'requires_identity_key_binding:person:email',
* 'append_strategy_requires_collection_target'.
*/
public function code(): string;
}

47
api/app/FormBuilder/Publishing/PublishGuardResult.php Normal file
View File

@@ -0,0 +1,47 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
/**
* RFC-WS-6 §3 (Q13) — outcome of evaluating a single {@see PublishGuard}.
* Sealed via two named constructors: callers cannot construct
* inconsistent states (passed-with-message, etc.).
*/
final readonly class PublishGuardResult
{
/**
* @param array<string, mixed> $context
*/
private function __construct(
public string $guardCode,
public bool $passed,
public ?string $messageKey = null,
public ?string $offendingFormFieldId = null,
public array $context = [],
) {}
public static function passed(string $guardCode): self
{
return new self(guardCode: $guardCode, passed: true);
}
/**
* @param array<string, mixed> $context
*/
public static function failed(
string $guardCode,
string $messageKey,
?string $offendingFormFieldId = null,
array $context = [],
): self {
return new self(
guardCode: $guardCode,
passed: false,
messageKey: $messageKey,
offendingFormFieldId: $offendingFormFieldId,
context: $context,
);
}
}

52
api/app/FormBuilder/Publishing/RequiresFieldType.php Normal file
View File

@@ -0,0 +1,52 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Enums\FormBuilder\FormFieldType;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q13) — at least N fields of the given FormFieldType
* must be present.
*/
final readonly class RequiresFieldType implements PublishGuard
{
public function __construct(
private FormFieldType $type,
private int $minCount = 1,
) {}
public function code(): string
{
return "requires_field_type:{$this->type->value}";
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
$expected = $this->type->value;
$count = 0;
/** @var FormField $field */
foreach ($schema->fields as $field) {
if ($field->field_type === $expected) {
$count++;
}
}
if ($count >= $this->minCount) {
return PublishGuardResult::passed($this->code());
}
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.requires_field_type',
context: [
'type' => $this->type->value,
'min_count' => $this->minCount,
'actual_count' => $count,
],
);
}
}

49
api/app/FormBuilder/Publishing/RequiresIdentityKeyBinding.php Normal file
View File

@@ -0,0 +1,49 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q13) — given that the binding's existence is enforced
* upstream by FormSchemaService::assertRequiredBindingsPresent(), this
* guard adds the `is_identity_key=true` flag check.
*/
final readonly class RequiresIdentityKeyBinding implements PublishGuard
{
public function __construct(
private string $entity,
private string $attribute,
) {}
public function code(): string
{
return "requires_identity_key_binding:{$this->entity}:{$this->attribute}";
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
/** @var FormField $field */
foreach ($schema->fields as $field) {
/** @var FormFieldBinding $binding */
foreach ($field->bindings as $binding) {
if ($binding->target_entity === $this->entity
&& $binding->target_attribute === $this->attribute
&& (bool) $binding->is_identity_key
) {
return PublishGuardResult::passed($this->code());
}
}
}
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.requires_identity_key_binding',
context: ['entity' => $this->entity, 'attribute' => $this->attribute],
);
}
}

33
api/app/FormBuilder/Publishing/SchemaHasLinkedEvent.php Normal file
View File

@@ -0,0 +1,33 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q13) — schema is bound to an event. FormSchema uses a
* polymorphic owner (owner_type/owner_id); this guard accepts only
* `owner_type === 'event'` with a non-null owner_id. Used as the
* sub-guard of ConditionalRequirement when AVAILABILITY_PICKER is present.
*/
final class SchemaHasLinkedEvent implements PublishGuard
{
public function code(): string
{
return 'schema_has_linked_event';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
if ($schema->owner_type === 'event' && $schema->owner_id !== null) {
return PublishGuardResult::passed($this->code());
}
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.schema_has_linked_event',
);
}
}

62
api/app/FormBuilder/Publishing/TagCategoriesConfiguredOnAllPickers.php Normal file
View File

@@ -0,0 +1,62 @@
<?php
declare(strict_types=1);
namespace App\FormBuilder\Publishing;
use App\Enums\FormBuilder\FormFieldConfigType;
use App\Enums\FormBuilder\FormFieldType;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldConfig;
use App\Models\FormBuilder\FormSchema;
/**
* RFC-WS-6 §3 (Q13) — every TAG_PICKER field must have a
* form_field_configs row with config_type=tag_categories and a
* non-empty parameters payload.
*/
final class TagCategoriesConfiguredOnAllPickers implements PublishGuard
{
public function code(): string
{
return 'tag_categories_configured_on_all_pickers';
}
public function evaluate(FormSchema $schema): PublishGuardResult
{
$tagPickerValue = FormFieldType::TAG_PICKER->value;
/** @var FormField $field */
foreach ($schema->fields as $field) {
if ($field->field_type !== $tagPickerValue) {
continue;
}
$hasCategories = false;
/** @var FormFieldConfig $config */
foreach ($field->configs as $config) {
if ($config->config_type !== FormFieldConfigType::TagCategories) {
continue;
}
$params = $config->parameters;
if ($params === []) {
continue;
}
$categories = $params['categories'] ?? null;
if (is_array($categories) && $categories !== []) {
$hasCategories = true;
break;
}
}
if (! $hasCategories) {
return PublishGuardResult::failed(
guardCode: $this->code(),
messageKey: 'form_builder_publish_guards.tag_categories_configured_on_all_pickers',
offendingFormFieldId: (string) $field->id,
);
}
}
return PublishGuardResult::passed($this->code());
}
}