[kaskader201]

hygiene.__invokeCall: required, calling an invokable object through __invoke()

hygiene.__invokeCall takes only forbidden and keep. This PR adds the opposite state, required:

$handler($x);              // $handler->__invoke($x);
($this->handler)($x);      // $this->handler->__invoke($x);
(new Handler)($x);         // (new Handler)->__invoke($x);
$registry->find()($x);     // $registry->find()->__invoke($x);

Motivation. With an explicit __invoke(), go to definition and find usages in the IDE reach the __invoke() declaration, and a text search finds the calls of a handler. $handler($x) gives neither.

What changes

• hygiene.__invokeCall becomes Domain::state('forbidden', 'required'), in the same shape as ShortTernaryRule.
• Rename. The rule now has two states, so NoExplicitInvokeCallsRule is renamed to InvokeCallNotationRule (a …Notation rule writes one form of a family). Its fixtures move with it.
• forbidden is unchanged. Its output is byte for byte the same, and the existing fixtures pass without edits.
• required needs the types. A call is rewritten only where Analyses\Types shows the callee to be an object for sure, every class it may be has __invoke(), and none of them is Closure. Without typeAnalysis: phpstan the state reports nothing. The rule is not typesRequired, because forbidden does not need the types.
• What stays untouched, and why:
  • a callee of unknown or mixed type, callable, a string or an array: it may be any kind of callable, and ->__invoke() would fail on most of them
  • Closure, and a union containing it: the __invoke() of a Closure leads to no declaration in the project, so it gains nothing
  • a nullable object: the types do not show an object for sure
  • $f(...): it makes a Closure of the object, not a call
  • a function called by name, strlen($x)
  • a call where the rewrite would lose a comment between the callee, its parentheses and the arguments
• The parentheses of ($this->h) are dropped, and (new Handler) keeps its own. Multi-line arguments and their comments stay as written.
• Interop. Neither PHP_CodeSniffer (Slevomat) nor PHP CS Fixer has a sniff that requires an explicit __invoke(), so nothing new maps to required. SlevomatCodingStandard.PHP.DisallowDirectMagicInvokeCall still maps to forbidden.
• docs/dresscode.annotated.neon lists required. composer reference and composer api were regenerated.

Tests

• New fixture invokeCallNotation/required with stubs: a variable, a property in parentheses, new, the result of a method call and of a static one, a union of two invokables, a call nested in the arguments, multi-line arguments with a comment, and the comment guard. It also covers the untouched cases: Closure, callable, an unknown type, a string, a class without __invoke(), a nullable object, a union with Closure, $f(...) and an existing ->__invoke().
• composer phpstan is clean and bin/dresscode check is clean.
• composer tester: 5 tests fail locally, all because my local PHP lacks simplexml (Interop/FormatterConfig, Interop/Translator, Upgrade/PlanRunner, Console/init, Console/Application). In a php:8.4-cli container with SimpleXML, Interop and Console/init pass. The remaining two fail there for reasons of the container itself (a git hook refusing the commit, running as root) and have nothing to do with this rule.

🤖 Generated with Claude Code

[dg]

Thanks for this, David. The implementation is careful: the rewrite held up on every edge case I threw at it, and the IDE problem you describe is a fair one to want solved. Still, I've decided not to take required into the core.

• It can't keep the promise. Only what the types prove gets rewritten, so a callable, a mixed or a nullable handler stays $handler($x), and array_map($handler, $items) is no call at all. A search for __invoke() would then look complete without being so.
• The notation would stop following from the text. The same $x($a) would be right or wrong depending on what PHPStan infers, so changing Handler to callable in a signature would change the correct style of lines elsewhere.
• The cost is out of proportion. Without typeAnalysis, required does nothing and check still says OK. Refusing that properly means teaching the core about decisions whose values need the types, for one key that no standard would use.

It fits well as a rule of your own project, though, where typesRequired also settles the run without types. I tried this on the current master: take callThroughInvoke() from your PR into its own rule class, with

#[RuleInfo(Stage::Structure, typesRequired: true, analyses: [Types::class])]
final class InvokeCallRequiredRule extends NodeRule

declaring new Decision('project.invokeCall', Domain::state('required'), '...') and reading the types with $context->getAnalysis(Types::class). Then in dresscode.neon:

typeAnalysis: phpstan

rules:
	- Acme\Style\InvokeCallRequiredRule

hygiene:
	__invokeCall: keep

project:
	invokeCall: required

It produced the same output as your PR. The keep is needed wherever a preset such as dresscode/nette sets forbidden, otherwise the two rules undo each other and the fix never settles.

So I'm closing this one, with thanks for the work and for the clear description.