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

feat(form-builder): FormFieldBindingService + library-to-field row copy + snapshot writer

Browse Source 
WS-5a commit 2 of 4.

FormFieldBindingService owns all writes to the relational binding table.
Validation against config/form_binding.php entity-column registry lives here
(ARCH §6.2).

FormFieldService::insertFromLibrary now calls copyBindings instead of
hydrating JSON — the Q3 row-copy mandate. Library and field bindings share
the same table; insertion is a row-clone operation.

Snapshot writer (FormSubmissionService::buildSnapshot) serialises bindings
via toJsonShape so schema_snapshot JSON keeps its ARCH §4.6.1 / §6.3
contract. No snapshot format change.
API resources source binding output from the relational table via the same
serialiser — external shape preserved.

Tests: service transactional behaviour, copyBindings preservation,
snapshot parity, API resource parity.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-24 18:48:47 +02:00
parent af8a9da038
commit 6933e6d700
9 changed files with 712 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
api/tests/Feature/FormBuilder/Bindings/FormFieldBindingServiceTest.php Normal file
View File

@@ -0,0 +1,230 @@
<?php
declare(strict_types=1);
namespace Tests\Feature\FormBuilder\Bindings;
use App\Enums\FormBuilder\FormFieldBindingMergeStrategy;
use App\Enums\FormBuilder\FormFieldBindingMode;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormFieldLibrary;
use App\Models\FormBuilder\FormSchema;
use App\Models\Organisation;
use App\Services\FormBuilder\FormFieldBindingService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Spatie\Activitylog\Models\Activity;
use Tests\TestCase;
final class FormFieldBindingServiceTest extends TestCase
{
use RefreshDatabase;
private FormFieldBindingService $service;
private Organisation $org;
private FormSchema $schema;
protected function setUp(): void
{
parent::setUp();
$this->service = $this->app->make(FormFieldBindingService::class);
$this->org = Organisation::factory()->create();
$this->schema = FormSchema::factory()->create(['organisation_id' => $this->org->id]);
}
public function test_replace_bindings_is_transactional_and_swaps_old_for_new(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'email')->create();
$this->service->replaceBindings($field, [[
'target_entity' => 'person',
'target_attribute' => 'first_name',
'mode' => FormFieldBindingMode::EntityOwned->value,
]]);
$rows = FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->get();
$this->assertCount(1, $rows);
$this->assertSame('first_name', $rows->first()->target_attribute);
}
public function test_replace_bindings_with_empty_array_clears_all(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'email')->create();
$this->service->replaceBindings($field, []);
$this->assertSame(0, FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->count(),
);
}
public function test_replace_bindings_rejects_unregistered_target_entity(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->expectException(\InvalidArgumentException::class);
$this->expectExceptionMessage("target_entity 'unicorn' is not registered");
$this->service->replaceBindings($field, [[
'target_entity' => 'unicorn',
'target_attribute' => 'email',
'mode' => FormFieldBindingMode::EntityOwned->value,
]]);
}
public function test_replace_bindings_rejects_unregistered_target_attribute(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->expectException(\InvalidArgumentException::class);
$this->expectExceptionMessage("target_attribute 'person.made_up_column'");
$this->service->replaceBindings($field, [[
'target_entity' => 'person',
'target_attribute' => 'made_up_column',
'mode' => FormFieldBindingMode::EntityOwned->value,
]]);
}
public function test_replace_bindings_rejects_invalid_mode(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->expectException(\InvalidArgumentException::class);
$this->expectExceptionMessage("mode 'form_owned'");
$this->service->replaceBindings($field, [[
'target_entity' => 'person',
'target_attribute' => 'email',
'mode' => 'form_owned',
]]);
}
public function test_replace_bindings_logs_activity_on_change(): void
{
Activity::query()->delete();
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->service->replaceBindings($field, [[
'target_entity' => 'person',
'target_attribute' => 'email',
'mode' => FormFieldBindingMode::EntityOwned->value,
]]);
$entry = Activity::query()
->where('subject_type', $field->getMorphClass())
->where('subject_id', $field->id)
->where('description', 'field.bindings_replaced')
->first();
$this->assertNotNull($entry);
}
public function test_copy_bindings_preserves_every_column(): void
{
$library = FormFieldLibrary::factory()->create(['organisation_id' => $this->org->id]);
$source = FormFieldBinding::factory()->forLibrary($library)->create([
'target_entity' => 'user_profile',
'target_attribute' => 'bio',
'mode' => FormFieldBindingMode::Mirrored->value,
'sync_direction' => 'write_on_submit',
'merge_strategy' => FormFieldBindingMergeStrategy::Append->value,
'trust_level' => 80,
'is_identity_key' => true,
]);
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->service->copyBindings($library->fresh(), $field);
$copy = FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->first();
$this->assertNotNull($copy);
$this->assertSame($source->target_entity, $copy->target_entity);
$this->assertSame($source->target_attribute, $copy->target_attribute);
$this->assertSame(FormFieldBindingMode::Mirrored, $copy->mode);
$this->assertSame('write_on_submit', $copy->sync_direction);
$this->assertSame(FormFieldBindingMergeStrategy::Append, $copy->merge_strategy);
$this->assertSame(80, $copy->trust_level);
$this->assertTrue($copy->is_identity_key);
}
public function test_copy_bindings_is_noop_when_source_has_none(): void
{
$library = FormFieldLibrary::factory()->create(['organisation_id' => $this->org->id]);
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$this->service->copyBindings($library, $field);
$this->assertSame(0, FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->count(),
);
}
public function test_to_json_shape_matches_arch_6_3_for_entity_owned(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$binding = FormFieldBinding::factory()
->forField($field)
->entityOwned('person', 'email')
->create();
$this->assertSame([
'mode' => 'entity_owned',
'entity' => 'person',
'column' => 'email',
], $this->service->toJsonShape($binding));
}
public function test_to_json_shape_matches_arch_6_3_for_mirrored(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$binding = FormFieldBinding::factory()
->forField($field)
->mirrored('user_profile', 'emergency_contact_name')
->create();
$this->assertSame([
'mode' => 'mirrored',
'entity' => 'user_profile',
'column' => 'emergency_contact_name',
'sync_direction' => 'write_on_submit',
], $this->service->toJsonShape($binding));
}
public function test_to_json_shape_returns_null_for_no_binding(): void
{
$this->assertNull($this->service->toJsonShape(null));
}
public function test_bindings_for_returns_only_owner_bindings(): void
{
$field = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
$other = FormField::factory()->create(['form_schema_id' => $this->schema->id]);
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'email')->create();
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'phone')->create();
FormFieldBinding::factory()->forField($other)->entityOwned('person', 'first_name')->create();
$this->assertCount(2, $this->service->bindingsFor($field));
}
}

84
api/tests/Feature/FormBuilder/Bindings/FormFieldResourceBindingOutputTest.php Normal file
View File

@@ -0,0 +1,84 @@
<?php
declare(strict_types=1);
namespace Tests\Feature\FormBuilder\Bindings;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormFieldLibrary;
use App\Models\FormBuilder\FormSchema;
use App\Models\Organisation;
use App\Models\User;
use Database\Seeders\RoleSeeder;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Laravel\Sanctum\Sanctum;
use Tests\TestCase;
/**
* External API shape parity: `FormFieldResource::binding` and
* `FormFieldLibraryResource::default_binding` must match the pre-WS-5a
* JSON exactly, but source from the relational table via the service.
*/
final class FormFieldResourceBindingOutputTest extends TestCase
{
use RefreshDatabase;
private Organisation $org;
private User $admin;
protected function setUp(): void
{
parent::setUp();
$this->seed(RoleSeeder::class);
$this->org = Organisation::factory()->create();
$this->admin = User::factory()->create();
$this->org->users()->attach($this->admin, ['role' => 'org_admin']);
}
public function test_form_field_resource_serialises_entity_owned_binding(): void
{
Sanctum::actingAs($this->admin);
$schema = FormSchema::factory()->create(['organisation_id' => $this->org->id]);
$field = FormField::factory()->create(['form_schema_id' => $schema->id]);
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'email')->create();
$response = $this->getJson("/api/v1/organisations/{$this->org->id}/forms/schemas/{$schema->id}/fields");
$response->assertOk();
$payload = collect($response->json('data'))->firstWhere('id', $field->id);
$this->assertSame([
'mode' => 'entity_owned',
'entity' => 'person',
'column' => 'email',
], $payload['binding']);
}
public function test_form_field_resource_returns_null_binding_when_none(): void
{
Sanctum::actingAs($this->admin);
$schema = FormSchema::factory()->create(['organisation_id' => $this->org->id]);
$field = FormField::factory()->create(['form_schema_id' => $schema->id]);
$response = $this->getJson("/api/v1/organisations/{$this->org->id}/forms/schemas/{$schema->id}/fields");
$response->assertOk();
$payload = collect($response->json('data'))->firstWhere('id', $field->id);
$this->assertNull($payload['binding']);
}
public function test_form_field_library_resource_serialises_default_binding(): void
{
Sanctum::actingAs($this->admin);
$library = FormFieldLibrary::factory()->create(['organisation_id' => $this->org->id]);
FormFieldBinding::factory()->forLibrary($library)->mirrored('user_profile', 'bio')->create();
$response = $this->getJson("/api/v1/organisations/{$this->org->id}/forms/field-library/{$library->id}");
$response->assertOk();
$response->assertJsonPath('data.default_binding', [
'mode' => 'mirrored',
'entity' => 'user_profile',
'column' => 'bio',
'sync_direction' => 'write_on_submit',
]);
}
}

66
api/tests/Feature/FormBuilder/Bindings/InsertFromLibraryCopiesBindingsTest.php Normal file
View File

@@ -0,0 +1,66 @@
<?php
declare(strict_types=1);
namespace Tests\Feature\FormBuilder\Bindings;
use App\Enums\FormBuilder\FormFieldBindingMode;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormFieldLibrary;
use App\Models\FormBuilder\FormSchema;
use App\Models\Organisation;
use App\Services\FormBuilder\FormFieldService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
final class InsertFromLibraryCopiesBindingsTest extends TestCase
{
use RefreshDatabase;
public function test_insert_from_library_copies_all_bindings_and_increments_usage(): void
{
$org = Organisation::factory()->create();
$schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
$library = FormFieldLibrary::factory()->create([
'organisation_id' => $org->id,
'usage_count' => 0,
]);
FormFieldBinding::factory()->forLibrary($library)->entityOwned('person', 'email')->create();
FormFieldBinding::factory()->forLibrary($library)->mirrored('user_profile', 'bio')->create();
$service = $this->app->make(FormFieldService::class);
$field = $service->insertFromLibrary($schema, $library);
$copied = FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->orderBy('target_attribute')
->get();
$this->assertCount(2, $copied);
$this->assertSame(['bio', 'email'], $copied->pluck('target_attribute')->all());
$this->assertSame(FormFieldBindingMode::Mirrored, $copied->firstWhere('target_attribute', 'bio')->mode);
$this->assertSame(FormFieldBindingMode::EntityOwned, $copied->firstWhere('target_attribute', 'email')->mode);
$this->assertSame(1, (int) $library->fresh()->usage_count);
}
public function test_insert_from_library_without_bindings_creates_field_without_bindings(): void
{
$org = Organisation::factory()->create();
$schema = FormSchema::factory()->create(['organisation_id' => $org->id]);
$library = FormFieldLibrary::factory()->create(['organisation_id' => $org->id]);
$service = $this->app->make(FormFieldService::class);
$field = $service->insertFromLibrary($schema, $library);
$this->assertSame(0, FormFieldBinding::query()
->withoutGlobalScopes()
->where('owner_type', 'form_field')
->where('owner_id', $field->id)
->count(),
);
}
}

119
api/tests/Feature/FormBuilder/Bindings/SchemaSnapshotEmbedsBindingFromRelationalTableTest.php Normal file
View File

@@ -0,0 +1,119 @@
<?php
declare(strict_types=1);
namespace Tests\Feature\FormBuilder\Bindings;
use App\Enums\FormBuilder\FormFieldBindingMode;
use App\Enums\FormBuilder\FormFieldType;
use App\Enums\FormBuilder\FormPurpose;
use App\Enums\FormBuilder\FormSchemaSnapshotMode;
use App\Models\FormBuilder\FormField;
use App\Models\FormBuilder\FormFieldBinding;
use App\Models\FormBuilder\FormSchema;
use App\Models\FormBuilder\FormSubmission;
use App\Models\Organisation;
use App\Models\User;
use App\Services\FormBuilder\FormSubmissionService;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
/**
* Asserts the `schema_snapshot` JSON keeps its ARCH §4.6.1 / §6.3 shape
* after WS-5a: the snapshot writer now serialises bindings from the
* relational table via FormFieldBindingService::toJsonShape, but the
* per-field JSON embedded in the snapshot is byte-for-byte the pre-WS-5a
* shape for entity-owned and mirrored patterns.
*/
final class SchemaSnapshotEmbedsBindingFromRelationalTableTest extends TestCase
{
use RefreshDatabase;
public function test_snapshot_embeds_entity_owned_binding_in_arch_shape(): void
{
$schema = $this->schemaWithSnapshot();
$field = FormField::factory()->create([
'form_schema_id' => $schema->id,
'field_type' => FormFieldType::EMAIL->value,
'slug' => 'email',
'label' => 'E-mail',
]);
FormFieldBinding::factory()->forField($field)->entityOwned('person', 'email')->create();
$submission = $this->submitFor($schema);
$snapshot = $submission->fresh()->schema_snapshot;
$this->assertIsArray($snapshot);
$embedded = collect($snapshot['fields'])->firstWhere('id', $field->id);
$this->assertNotNull($embedded);
$this->assertSame([
'mode' => 'entity_owned',
'entity' => 'person',
'column' => 'email',
], $embedded['binding']);
}
public function test_snapshot_embeds_mirrored_binding_with_sync_direction(): void
{
$schema = $this->schemaWithSnapshot();
$field = FormField::factory()->create([
'form_schema_id' => $schema->id,
'field_type' => FormFieldType::TEXT->value,
'slug' => 'noodcontact',
'label' => 'Noodcontact',
]);
FormFieldBinding::factory()->forField($field)->mirrored('user_profile', 'emergency_contact_name')->create();
$submission = $this->submitFor($schema);
$snapshot = $submission->fresh()->schema_snapshot;
$embedded = collect($snapshot['fields'])->firstWhere('id', $field->id);
$this->assertSame([
'mode' => 'mirrored',
'entity' => 'user_profile',
'column' => 'emergency_contact_name',
'sync_direction' => 'write_on_submit',
], $embedded['binding']);
}
public function test_snapshot_embeds_null_binding_for_form_owned_field(): void
{
$schema = $this->schemaWithSnapshot();
$field = FormField::factory()->create([
'form_schema_id' => $schema->id,
'field_type' => FormFieldType::TEXT->value,
'slug' => 'motivatie',
'label' => 'Motivatie',
]);
$submission = $this->submitFor($schema);
$snapshot = $submission->fresh()->schema_snapshot;
$embedded = collect($snapshot['fields'])->firstWhere('id', $field->id);
$this->assertNull($embedded['binding']);
}
private function schemaWithSnapshot(): FormSchema
{
$org = Organisation::factory()->create();
return FormSchema::factory()->create([
'organisation_id' => $org->id,
'purpose' => FormPurpose::USER_PROFILE->value,
'snapshot_mode' => FormSchemaSnapshotMode::ALWAYS->value,
]);
}
private function submitFor(FormSchema $schema): FormSubmission
{
$user = User::factory()->create();
$service = $this->app->make(FormSubmissionService::class);
$submission = $service->createDraft($schema, $user, $user);
return $service->submit($submission, $user);
}
}