Fix: schema-driven type coercion on magic-table read paths

[rjzondervan]

Summary

Fixes the read-side type drift where API responses for OpenRegister and OpenConnector returned object-property values whose runtime PHP type didn't match the JSON-Schema-declared property type:

• A boolean-typed property came back as int 0/1 (MariaDB TINYINT(1) → mysqlnd).
• A string-typed property whose value looked like a JSON literal ("123", "true", "null", '"foo"') was silently re-decoded back into the original primitive — string-cast undone by an over-eager is_string && isJsonString decode block in MagicStatisticsHandler::convertRowToObjectEntity.

Both magic-table read paths now delegate to a single shared converter.

Closes #1366.

Endpoint coverage

Every endpoint that reconstructs an ObjectEntity from a magic-table row goes through the unified converter:

Endpoint	Reads ObjectEntity via	Affected
GET /api/objects/<uuid>	MagicStatisticsHandler::convertRowToObjectEntity	✓
GET /api/objects (list)	MagicStatisticsHandler::convertRowToObjectEntity	✓
GET /api/search	MagicSearchHandler::convertRowToObjectEntity	✓ (refactored to share converter)
POST /api/objects	re-fetch via MagicStatisticsHandler	✓
PUT /api/objects/<uuid>	re-fetch via MagicStatisticsHandler	✓

POST/PUT responses build their bodies by re-fetching through findInRegisterSchemaTable (see comment in MagicMapper::insertObjectEntity: "CRITICAL FIX: Re-fetch the inserted object from database to get complete metadata"). That re-fetch goes through the same converter, so create/update responses are now type-consistent with reads.

What changed

• New lib/Service/Object/SchemaTypeConverter.php — stateless service with a single public convertValue(value, schemaType). Zero deps, auto-wired.
• lib/Db/MagicMapper/MagicStatisticsHandler.php — replaces the partial coercion + over-eager JSON-decode block with one converter call. DateTimeNormalizer format handling stays where it is (per design D5). Unused isJsonString helper removed.
• lib/Db/MagicMapper/MagicSearchHandler.php — replaces the inline convertValueByType call with a delegated converter call. Six private converter methods deleted (single source of truth from day one — per design D8).
• lib/Db/MagicMapper.php — handler instantiation updated to inject the converter via the app container.
• New tests/Unit/Service/Object/SchemaTypeConverterTest.php — 55 cases across 8 test methods covering every JSON-Schema primitive type and the regression suite.
• tests/Unit/Db/MagicStatisticsHandlerTest.php and tests/Unit/Db/MagicSearchHandlerTest.php — constructors updated for the new dependency.

Out of scope (deferred to follow-up changes)

• Write-side coercion in SaveObject / SaveObjects / MagicBulkHandler.
• Requiring minimum/maximum on JSON Schema integer properties (require-integer-bounds).
• Schema editor UI changes.
• BIGINT migration of existing INTEGER columns.

Spec / design artifacts

Full OpenSpec change under openspec/changes/fix-magic-table-type-coercion/:

• proposal.md — Why + What + Capabilities + Endpoint coverage matrix
• design.md — 8 decisions (incl. D7: reject 'on', D8: delete inline methods immediately) + risks + migration plan
• specs/schema-driven-read-coercion/spec.md — 9 ADDED requirements with WHEN/THEN scenarios
• tasks.md — implementation checklist (33/42 done before opening this PR; remaining are manual verification + release notes + archive)
• plan.json — tracking issue [OpenSpec] [openregister] fix-magic-table-type-coercion #1366

Long-lived spec stub: openspec/specs/schema-driven-read-coercion/spec.md.

Test plan

• php -l clean on all touched files.
• PHPCS clean on lib/ files (sniff scope per phpcs.xml).
• PHPMD clean on touched lib/ files (pre-existing complexity warnings on applyObjectFilters / buildObjectFilterConditionsSql are out of scope — methods I didn't touch).
• SchemaTypeConverterTest — 55/55 unit tests pass.
• Existing MagicStatisticsHandlerTest + MagicSearchHandlerTest — 14/14 pass with the new converter wired in.
• Magic-mapper test suite (excluding the pre-existing-broken tests/Unit/Service/MagicMapperTest.php that fails with ConditionMatcher constructor mismatch unrelated to this PR) — 49/49 pass.
• Manual API verification: register/schema with one property of each primitive type; insert objects exercising the bug paths (numeric data in a string field, 0/1 in a boolean field, JSON-literal strings); call GET /api/objects/<uuid>, GET /api/objects, POST /api/objects, PUT /api/objects/<uuid>, GET /api/search?q=… and assert types in the JSON response.
• OpenConnector downstream spot-check: pull the same schema's data through OC's source proxy — confirm booleans now arrive as true/false.
• Release-notes entry.

Heads-up for OpenConnector reviewers

Sync flows that previously received 0/1 for booleans will now receive native bool. Mapping templates that explicitly checked === 1 would break — Conduction-internal mappings have been audited (zero hits).

Pre-existing issues NOT fixed by this PR

• tests/Unit/Service/MagicMapperTest.php:224 — constructor missing $conditionMatcher arg, all 29 tests in that file fail. Stack trace lands at line 365 of MagicMapper.php (MagicRbacHandler instantiation), which I did not modify. Last touched by commit 44894ed42. Worth a small follow-up fix.

[WilcoLouwerse]

No blockers. Three concerns worth addressing: convertArrayOrObject silently returns PHP null for the string 'null', handler-level delegation tests added nothing to enforce the single-source-of-truth guarantee, and dead code in convertString. Also a PHPCS spacing regression in the test helper signatures that will fail composer check:strict.

[github-actions]

Quality Report — ConductionNL/openregister @ db74a72

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 147/147
npm			✅	✅ 598/598
PHPUnit					❌
Newman					❌
Playwright					⏭️

---

Quality workflow — 2026-04-30 14:48 UTC

Download the full PDF report from the workflow artifacts.