Problem/Motivation
Currently I don't see a convention when and how parameter signatures should be broken to multiple lines.
In
📌
Use PHP 8 constructor property promotion for existing code
Needs work
we are converting constructors to use constructor property promotion.
In the existing PR there are no line breaks between the parameters.
This is a consequence of not having a convention or recommendation.
In Drupal core, a regex search that having line breaks between promoted property parameters is actually the majority.
However, there are still enough cases where promoted properties are on a single line.
E.g. this code in SystemTestController does have the line breaks, and I think it is good:
(I looked for one with attributes and promoted properties, although not all properties are promoted)
public function __construct(
#[Autowire(service: 'lock')]
LockBackendInterface $lock,
#[Autowire(service: 'lock.persistent')]
LockBackendInterface $persistent_lock,
AccountInterface $current_user,
RendererInterface $renderer,
MessengerInterface $messenger,
public ?KillSwitch $killSwitch = NULL,
public KillSwitch|null $killSwitch2 = NULL,
) {
In vendor code (symfony, drush etc) there is a mix: Some packages (drush) break these signatures to multiple lines, others (symfony) keep it in one line.
Benefits
Line breaks make long signatures easier to read, and also easier to work with when adding new parameters, reviewing git commits etc.
Three supporters required
-
https://www.drupal.org/u/drunken-monkey →
(2024-07-20)
-
https://www.drupal.org/u/ →
{userid} (yyyy-mm-dd they added support)
-
https://www.drupal.org/u/ →
{userid} (yyyy-mm-dd they added support)
Proposed changes
Argument lists may be split across multiple lines, where each subsequent line is indented once.
Parameter lists of functions and methods may be split across multiple lines, where each subsequent line is indented once.
Splitting the list of parameters is strongly recommended, if:
- The signature contains one or more promoted properties (for a constructor method), or
- At least one of the parameters has a parameter attribute, or
- The parameter list would be very long.
Parameter attributes can be placed on the same line as the parameter, or on a separate line.
They should be placed on a separate line, if the attribute itself has arguments, or if there are multiple attributes.
The part about attributes could also be handled in a separate issue.
I am replacing "arguments" with "parameters", I think this is the more word to use here.
My understanding is that "arguments" are the values we pass to a function, whereas "parameters" are the slots in the signature that receive these values.
I also mention explicitly that this is about functions and methods, I think this will reduce confusion for people who read this page for the first time.
It can be discussed whether this should be a recommendation or a convention.
My idea would be that at least for new code this should be followed.
Remaining tasks
- Add supporters
- Create a Change Record
- Review by the Coding Standards Committee
- Coding Standards Committee takes action as required
- Discussed by the Core Committer Committee, if it impacts Drupal Core
- Final review by Coding Standards Committee
- Documentation updates
- Edit all pages
- Publish change record
- Remove 'Needs documentation edits' tag
- If applicable, create follow-up issues for PHPCS rules/sniffs changes
For a full explanation of these steps see the
Coding Standards project page →
upstream work on a sniff, https://github.com/slevomat/coding-standard/issues/1684