Define the real wpdb query contract

[alexstandiford]

Contract

The WordPress query adapter must preserve scalar, null, range, list, tuple, and grouped predicate meaning through real WordPress wpdb preparation. Invalid fields, operators, arity, and group logic must raise QueryBuilderException without changing builder state.

QueryStrategy must translate builder failures and wpdb SQL failures to DatastoreErrorException. It must preserve the builder exception as the cause when one exists. A genuine empty result remains RecordNotFoundException.

Compound insert, update, and delete must preserve full identities. Placeholder-like and subquery-marker text must remain data.

Architecture

This PR adds a separate integration bootstrap that loads official WordPress core from WORDPRESS_ROOT and connects to real MySQL through wpdb. The fixture uses connection-local TEMPORARY tables. It does not install WordPress, mock wpdb, or touch a persistent table.

The public surface already exists, so this packet adds no production signatures. The implementation keeps protected generatePlaceholder as the per-condition right-hand-side template seam. Every non-null value uses %s, null values render as SQL NULL, and each complete condition is prepared exactly once before it is stored. Build only concatenates prepared fragments.

Protected addCondition normalizes non-null logic to AND or OR before changing builder state. Invalid logic, invalid operators, invalid tuple widths, and preparation failures leave existing state unchanged.

Implementation

The implementation restores the condition placeholder seam without marker substitution or a printf parser. It flattens non-null scalar and tuple values in placeholder order, prepares one condition once through wpdb, and stores the prepared condition. The implementation also removes the old PHP-type placeholder selection that rounded floats and coerced values used against VARCHAR columns.

The existing CanGetDataFormats trait remains attached so subclasses retain inherited protected getFieldSprintfType and getFormats methods. Assertions introduced in the architecture commits are unchanged. Existing implementation-added unit expectations were updated only to reflect quoted non-null values returned by real wpdb preparation.

Verification

Unit suite:

vendor/bin/phpunit -c phpunit.xml --colors=never

Result: 74 tests, 124 assertions, no failures or errors.

Required real wpdb suite:

WORDPRESS_ROOT=/tmp/phpnomad-round2.SyhuHL/wordpress MYSQL_HOST=127.0.0.1 MYSQL_PORT=32777 MYSQL_USER=root MYSQL_PASSWORD=[task fixture] MYSQL_DATABASE=round2_wordpress_impl vendor/bin/phpunit -c phpunit-integration.xml --colors=never --fail-on-skipped

Result: 59 tests, 106 assertions, no failures, errors, or skips.

Full dependency comparison matrix:

php /tmp/phpnomad-round2.SyhuHL/wpdb-contract.php

Result: 439 of 439 cases passed with WordPress 6.8.3, MySQL 8.0.45, the merged database and MySQL repair trees, and this branch.

Separate-process reflection comparison against released main bce8152 found identical public and protected ClauseBuilder method sets, including trait-provided methods. The focused ClauseBuilder unit suite remains green at 4 tests and 6 assertions, and the required real wpdb suite remains green after the compatibility correction.

Target-file PHP CS Fixer dry runs report no changes for ClauseBuilder.php and ClauseBuilderTest.php. GitHub CI runs the PHP 8.3 unit suite on push.

The defect evidence is recorded in Retrospective audit: PHPNomad database consumer compatibility (Source 9959).