WordPress / WordPress/WordPress-Coding-Standards

Handbook: discourage multi-line parameters in function calls (assign to a variable then pass the var)

Open
#1,330 27 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Component: Core Type: Enhancement
Dominant language
PHP
Stars
2.8k
Forks
521
Avg merge
5d 20h
Merged PRs (30d)
1

Description

This is a follow-up from #1323.

It seems that the parser has introduced unwanted changes in single function and filter/action parameters: associative arrays were formatted to be multi-line. This was never intended in the original "Associative arrays should be multi-line" rule.

Please note: this is about a single parameter being on multiple lines. Example 1:

do_action(
	'upgrader_process_complete', $this, array(
		'action' => 'update',
		'type'   => 'core',
	)
);

This is not about having each parameter on a new line. When the parameters are long, having each on a new line is better. Example 2:

do_action(
	'upgrader_process_complete', 
	'some long parameter that is easier to read when on a new line',
	'another long parameter that is more readable when on a new line'
);

#1323 already deals with partially fixing this. I'd go one step further. The best way to fix this bug would be to discourage or even ban single parameters inside function and filter/action calls being on multiple lines.

In that terms:

  • This should be "illegal":
do_action(
	'upgrader_process_complete', $this, array(
		'action' => 'update',
		'type'   => 'core',
	)
);
  • This should be discouraged, possibly illegal too as it makes the source harder to read:
do_action(
	'upgrader_process_complete',
	$this,
	array(
		'action' => 'update',
		'type'   => 'core',
	)
);
  • This should be the preferred/proper way as it is easiest to read:
$param = array(
	'action' => 'update',
	'type'   => 'core',
);

do_action( 'upgrader_process_complete', $this, $param );

To fix this we will need:

  1. A rule that enforces proper multi-line parameters (see example 2 above). Ideally this will be only when at least one parameter is long, lets say over 50 characters.
  2. A rule that flags or prevents single parameters that are on multiple lines.
  3. Fix for the associative array rule to make it not apply inside function and filter/action calls. Ideally this will flag cases where an array is used "inline" and suggest setting it to a variable above the function/filter/action call.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review #1323 and the existing associative-array rule first. Define how function and filter/action calls should handle long parameters, multi-line single parameters, and inline associative arrays, then verify the three proposed rules against the examples in this issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.