[FR] Multi-line arrays: sniff to enforce the array opener on the same line as the equals sign

[rodrigoprimo]

Setting the scene

PER-CS 2.0, section 11 (Arrays) contains the following rule for multi-line array declarations:

When the array declaration is split across multiple lines, the opening bracket MUST be placed on the same line as the equals sign.

Proposed new sniff: NormalizedArrays.Arrays.ArrayOpenerLine

Notes for the implementation

Like the sibling sniffs, register Collections::arrayOpenTokensBC() and resolve the opener/closer with Arrays::getOpenClose(). Detect multi-line arrays by comparing the opener's and closer's line. For the assignment anchor, confirm the token before the opener is T_EQUAL.

Note on other assignment operators: += and ??= can also assign an array, so they are plausible additions. I'm assuming the PER-CS 2.0 rule is only meant to apply to =.

Suggested error code:

• OpenerNotSameLine: the opener of a multi-line array is not on the same line as the =.

Describe the solution you'd like

A new sniff as outlined above.

The sniff should be able to flag and auto-fix the following (auto-fixing is skipped when a comment sits between the = and the opener, as the comment cannot be safely moved):

// OK: opening bracket on the same line as the equals sign.
$x = [
    1,
    2,
];

// OK: long array syntax, opener on the same line.
$x = array(
    1,
    2,
);

// OK: single-line array, not in scope.
$x = [1, 2];

// Error (fixable): opening bracket pushed to the next line.
$x =
[
    1,
    2,
];

// Error (fixable): long array syntax.
$x =

array(
    1,
    2,
);

// Out of scope: `return` is not a `=` assignment.
return
[
    1,
    2,
];

// Out of scope: nested array anchored to `=>`.
$x = [
    'key' =>
        [
            1,
            2,
        ],
];

Also see the examples outlined in the PER documents (rules + migration guide).

Additional context (optional)

This ticket is the result of a detailed analysis of the rules as outlined in PER-CS 2.0, as well as a critical look at what's still missing rule-wise.

• I intend to create a pull request to implement this feature.