Skip to content

Add @no-named-arguments to QueryBuilder select and group helpers - #12513

Merged
greg0ire merged 2 commits into
doctrine:3.8.xfrom
savinmikhail:codex/querybuilder-no-named-arguments-select-groupby
Oct 26, 2026
Merged

greg0ire merged 2 commits into
doctrine:3.8.xfrom
savinmikhail:codex/querybuilder-no-named-arguments-select-groupby

Conversation

@savinmikhail

@savinmikhail savinmikhail commented Jun 18, 2026 •

Copy link
Copy Markdown
Contributor

Add @no-named-arguments to the variadic QueryBuilder helpers used for projections and grouping:

  • select()
  • addSelect()
  • groupBy()
  • addGroupBy()

Why this is separate from #12512

I split this out from the where() / having() condition helpers on purpose.

The first PR focused on the most obvious condition-building methods, where named arguments are especially misleading for the variadic predicate-style API and where there is already a related bug signal in #11253.

This PR covers a second group of variadic helpers where the main concern is API contract clarity and tooling guidance: the parameter names are still implementation details rather than something that should be treated as a stable named-argument contract.

Related

Validation

  • vendor/bin/phpunit tests/Tests/ORM/QueryBuilderTest.php
  • vendor/bin/phpcs --standard=phpcs.xml.dist src/QueryBuilder.php

@savinmikhail
savinmikhail marked this pull request as ready for review June 20, 2026 04:20
@greg0ire
greg0ire changed the base branch from 3.7.x to 3.8.x September 7, 2026 19:43
@GromNaN GromNaN added this to the 3.8.0 milestone Oct 23, 2026
GromNaN
GromNaN previously approved these changes Oct 23, 2026

@GromNaN GromNaN left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PHPStan errors on groupBy and addGroupBy only are incorrect. The function validateVariadicParameter return void, not a bool.

Declare the parameter as list<mixed> instead of asserting it. Add
@no-named-arguments to the methods that rely on the runtime validation,
so that static analysis knows their variadic parameter is a list.
@GromNaN
GromNaN force-pushed the codex/querybuilder-no-named-arguments-select-groupby branch from 7bb66a8 to 7bd3965 Compare October 24, 2026 19:48
@GromNaN

GromNaN commented Oct 24, 2026

Copy link
Copy Markdown
Member

I rebased on 3.8.x and pushed a follow-up commit to fix the PHPStan failure.

The error was staticMethod.alreadyNarrowedType on groupBy() and addGroupBy(). With @no-named-arguments, $groupBy is already a list<string>, so the @phpstan-assert list<TItem> on validateVariadicParameter() was redundant for static analysis. The error is legitimate, it comes from a runtime check of a constraint that PHPStan already enforces. It is tracked in phpstan/phpstan-src#6823.

I first considered ignoring it or changing the helper to @param-out or @return list<TItem>. Both options work, but they either add an ignore or a small runtime cost (negligible, a few nanoseconds per call). I went another way:

  • validateVariadicParameter() now declares @param list<mixed> $parameter and no longer uses @phpstan-assert. The runtime behavior is unchanged.
  • The methods that call it now have @no-named-arguments, so static analysis knows their variadic parameter is a list: Expr::andX(), orX(), countDistinct(), concat() and the ChainTypedFieldMapper constructor.

This removes the error without any ignore or baseline entry, and PHPStan now reports a missing @no-named-arguments on any new caller.

The runtime check still works because the project sets treatPhpDocTypesAsCertain: false.

Comment on lines -28 to -33
/**
* @param TItem[] $parameter
*
* @template TItem
* @phpstan-assert list<TItem> $parameter
*/

@GromNaN GromNaN Oct 24, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might have to revert this change once phpstan/phpstan-src#6824 is released.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe yes, or maybe not: I think it might have been written that way because at the time, we did not set treatPhpdocAsCertain to false.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cc @derrabus , who is the author of that trait.

@greg0ire
greg0ire merged commit 69484da into doctrine:3.8.x Oct 26, 2026
132 checks passed
@greg0ire

Copy link
Copy Markdown
Member

Thanks @savinmikhail !

@savinmikhail

Copy link
Copy Markdown
Contributor Author

@greg0ire happy to help! I found these cases while working on AddNamedArgumentsRector, a rule I maintain that converts positional arguments to named arguments and respects @no-named-arguments. Applying it to the test suite and running the tests might uncover more cases like these than I found. Could be useful as a one-off experiment, even without adopting the rule in the project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants