Skip to content

Render every value of an In list through a custom specification - #240

Merged
simon-mundy merged 9 commits into
php-db:0.6.xfrom
simon-mundy:fix/in-custom-specification-values
Nov 4, 2026
Merged

simon-mundy merged 9 commits into
php-db:0.6.xfrom
simon-mundy:fix/in-custom-specification-values

Conversation

@simon-mundy

Copy link
Copy Markdown
Member

Problem

A custom specification on In/NotIn loses list values and leaves orphan parameters:

$in = (new Predicate\In('id', [1, 2]))->setSpecification('%1$s = ANY (ARRAY[%2$s])');
(new Select('t'))->where([$in]);
  • Unprepared: SELECT "t".* FROM "t" WHERE "id" = ANY (ARRAY['1']) (the 2 is gone)
  • Prepared: ... ARRAY[:where1], but the container holds where1 and where2, so PDO rejects the parameter count

Cause

In::getExpressionData() returned the custom specification unchanged with values [identifier, valueSet]. The default specification embeds the value set's own (%s, %s), which lines up with AbstractSql::flattenExpressionValues() expanding the Values argument into one value per item. A custom specification refers to the whole list with a single %2$s, so the expanded values shift: later ones are dropped from the SQL but still bound.

Fix

  • New internal Predicate\CustomSpecification::expand() rewrites a custom specification so each placeholder covers every value its argument renders. Placeholders can be plain (%s) or positional (%2$s). Output is all positional, so %2$s becomes %2$s, %3$s for a two-value list. An empty list becomes NULL. A sub-select stays a single placeholder. %% is left alone.
  • An argument that binds values (Values, Value, Select) must be referenced exactly once. If a specification repeats or omits one, or names a missing argument, it throws a Predicate\Exception\InvalidArgumentException (SPECIFICATION_ARGUMENT_NOT_REFERENCED_ONCE, SPECIFICATION_ARGUMENT_OUT_OF_RANGE) instead of producing mismatched parameters. Identifiers and literals can be repeated or omitted.
  • In::getExpressionData() applies this only when a custom specification is set. Default output is unchanged. NotIn inherits the fix.
  • docs/book/sql/where-having.md documents custom In specifications.

Other multi-value predicates were checked. Between/NotBetween take scalar Value arguments, which are never expanded, so they are not affected.

Tests

All new tests are #[Group('unit')] and use data providers.

  • CustomSpecificationTest: rewriting for 1, 2 and 3 values; plain and positional placeholders; list before the identifier; identifier repeated; escaped %%; empty list; sub-select; a Values identifier shifting the list. Also the rejection cases: list repeated, list omitted, bound identifier repeated, out-of-range positional argument, too many plain placeholders.
  • InTest: unprepared SQL and prepared SQL plus getNamedArray() for custom specifications, including a sub-select whose own parameter binds once.
  • NotInTest: unprepared SQL for 1, 2 and 3 values.
  • InvalidArgumentExceptionTest: the two new named constructors.

phpunit --testsuite "unit test", mago format --check, mago lint and mago analyze all pass. In, CustomSpecification and the predicate InvalidArgumentException have 100% line coverage.

A custom In/NotIn specification refers to the value set with one placeholder,
but the value set renders one value per list item. With more than one value
the extra values were dropped from the SQL while still being bound, leaving
orphan parameters in prepared statements.

Custom specifications are now rewritten so each placeholder covers every value
its argument renders (positional placeholders, an empty list as NULL), and a
specification that repeats or omits an argument that binds values, or names a
missing argument, throws a Predicate InvalidArgumentException.
@codecov

codecov Bot commented Oct 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

A custom specification may refer to its arguments only with %s or %N$s,
and must write a literal percent sign as %%. Any other conversion, such as
%d, a padded %05s or an unescaped %, previously reached vsprintf(), where
it could pad an argument, consume a bound value or raise a ValueError.
expand() now throws InvalidArgumentException naming the unsupported
placeholder.
simon-mundy and others added 5 commits November 4, 2026 13:56
Capture a positional placeholder's argument number in the placeholder
pattern rather than slicing it out with substr(), and require a
specification to use plain (%s) or positional (%N$s) placeholders
throughout. Mixing them now throws InvalidArgumentException with its own
message. Adopted from the review of php-db#247.
Merge offsets() and placeholders() into a single map of each argument's
positional placeholders, keyed by argument index. expand() looks the
placeholder up directly, which drops the unreachable offset fallback and
brings the class back under Mago's cyclomatic complexity threshold.
- Reject %0$s as an unsupported placeholder, since argument numbers
  start at 1.
- Report a missing argument before mixed placeholder styles, so a typo
  in an argument number gets the more actionable message.
- Include the offset of an unsupported placeholder in its message.
- Reword the out-of-range message so it no longer needs a plural.
- Document that the conversion pattern must keep a single capturing
  group, which the preg_split() parity relies on.
- Cover a specification with no placeholders.
@simon-mundy
simon-mundy merged commit 680459a into php-db:0.6.x Nov 4, 2026
15 checks passed
simon-mundy added a commit to simon-mundy/phpdb that referenced this pull request Nov 4, 2026
Resolve the conflicts with php-db#235 and php-db#240:

- Expression gains both setSpecification() and placeholderFor().
- 0.6.x's CustomSpecificationTest (from php-db#240) keeps its name. The
  predicate override tests from this branch move to
  SpecificationOverrideTest, and the In case now expects the expanded
  placeholders.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants