Clarifications Needed for Ambiguities in PER CS 2.0 Specification

[azjezz]

Hi there,

I'm currently working on Mago, a PHP toolchain that happens to include a formatter (crates/formatter). I'm interested in making Mago conform to PER CS 2.0 by default, but I’ve encountered some ambiguities in the specification that I'd like to clarify. Here are a few questions I have:

1. Attributes (Section 12.3)

When multiple attributes exist in a single attribute block (between #[ and ]), and breaking those attributes doesn’t result in lines shorter than 120 characters, should the block itself break? For example:

<?php

#[SomeAttributeWithASuperLongName, SomeOtherAttribute, SomeOtherAttribute, SomeOtherAttribute, SomeOtherAttribute, Foo, Bar, Baz]
class Foo
{
}

Would it be formatted as:

<?php

#[
    SomeAttributeWithASuperLongName,
    SomeOtherAttribute,
    SomeOtherAttribute,
    SomeOtherAttribute,
    SomeOtherAttribute,
    Foo,
    Bar,
    Baz,
]
class Foo
{
}

This would make it consistent with arguments, parameters, etc.

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/mod.rs#L1392-L1467

---

2. Arrow Functions (Section 7.1)

The spec says that an arrow function can break with the arrow on the next line, indented:

$fn = fn($x) =>
    $x + 1;

When the expression in the arrow function also wraps, how should it format? For example:

if ($expr) {
    $fn = fn($x) => ['foo' => 'bar', 'baz' => 'qux', 'quux' => 'quuz', 'corge' => 'grault', 'garply' => 'waldo', 'fred' => $x];
}

Should it wrap the arrow function first or the expression? For instance:

if ($expr) {
    $fn = fn($x) 
        => ['foo' => 'bar', 'baz' => 'qux', 'quux' => 'quuz', 'corge' => 'grault', 'garply' => 'waldo', 'fred' => $x];
}

// or

if ($expr) {
    $fn = fn($x) => [
        'foo' => 'bar',
        'baz' => 'qux',
        'quux' => 'quuz',
        'corge' => 'grault',
        'garply' => 'waldo',
        'fred' => $x,
    ];
}

And if it's the second, when the expression wraps, does the arrow function need to also wrap again if it still exceeds 120 characters?

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/expression.rs#L592-L627

---

3. Ternary Operators (Section 6.3)

The specification mentions spaces around ? and :, but what happens when the ternary wraps? For example:

$foo = $bar
    ? 'baz'
    : 'qux';
    
// or

$foo = $bar ?
    'baz' :
    'qux';

What should wrap first—the ternary operator or the expressions inside it?

$foo = $foo 
    ? $foo
    : ['foo' => 'bar', 'baz' => 'qux', 'quux' => 'quuz', 'corge' => 'grault', 'garply' => 'waldo', 'fred' => $x];

// or
$foo = $foo ? $foo : [
    'foo' => 'bar',
    'baz' => 'qux',
    'quux' => 'quuz',
    'corge' => 'grault',
    'garply' => 'waldo',
    'fred' => $x,
];

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/expression.rs#L838-L866

---

4. Try/Catch/Finally (Section 5.6)

In this section, the example provided is:

<?php

try {
    // try body
} catch (FirstThrowableType $e) {
    // catch body
} catch (OtherThrowableType | AnotherThrowableType $e) {
    // catch body
} finally {
    // finally body
}

Regarding OtherThrowableType | AnotherThrowableType type hints, should it be consistent with other type hints, or should there always be a space between the | operator?

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/mod.rs#L1226-L1373

---

5. Foreach (Section 5.5)

The specification does not mention how to format the foreach statement when it wraps. Should it be formatted as follows?

foreach (
    $array as $key => $value
) {
    // body
}

// or

foreach (
    $array as
        $key => $value
) {
    // body
}

What about when the target of the foreach wraps?

foreach ($array as [
    $a,
    $b,
    $c,
    $d,
]) {
    // body
}

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/control_structure.rs#L390-L438

---

6. Method Chaining (Section 4.7)

The spec mentions method chaining can be put on separate lines, e.g.:

$someInstance
    ->create()
    ->prepare()
    ->run();

When should method chaining break? Should there be a threshold for the number of methods called or the character count exceeding 120? Should it break before or after arguments of methods?

$someInstance->create()->prepare()->run($foo, $bar, $baz);

// Break as:
$someInstance
    ->create()
    ->prepare()
    ->run($foo, $bar, $baz);

// Or:
$someInstance->create()->prepare()->run(
    $foo,
    $bar,
    $baz
);

Does this chain include property access, null-safe method calls, or method closure creation?

$foo->property?->method()?->property?->method()->closure(...);

ref: https://github.com/carthage-software/mago/blob/89bfe68a778f75b8b99273a8e531ceef81c886b3/crates/formatter/src/format/call.rs#L17-L94

---

7. Line Width and Blank Lines (Section 2.3)

The spec says:

There MUST NOT be a hard limit on line length.

The soft limit on line length MUST be 120 characters.

Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD be split into multiple subsequent lines of no more than 80 characters each.

This is confusing. Is the soft limit 120 or 80? If it’s 120, why split lines into 80-character chunks?

Additionally, the spec mentions:

Blank lines MAY be added to improve readability and to indicate related blocks of code except where explicitly forbidden.

What about multiple blank lines in a row? Should they be allowed, or should they be collapsed into one?

---

Thanks for taking the time to clarify these ambiguities! These answers will help me make Mago more consistent with the intent of the specification.

[azjezz]

another question regarding method chaining, should the first call be indented?

meaning which one of these two is correct?

<?php

$app->get('/', function ($request) {
    if ($request->has('name')) {
        return 'Hello, ' . $request->get('name');
    } else {
        return 'Hello, world!';
    }
})
    ->get('/hello/{name}', function ($request, $name) {
        return 'Hello, ' . $name;
    })
    ->post('/hello', function ($request) {
        return 'Hello, ' . $request->get('name');
    })
    ->get('/stats', function ($request) {
        return 'Stats';
    })
    ->get('/stats/{id}', function ($request, $id) {
        return 'Stats for ' . $id;
    });

or

<?php

$app->get('/', function ($request) {
        if ($request->has('name')) {
            return 'Hello, ' . $request->get('name');
        } else {
            return 'Hello, world!';
        }
    })
    ->get('/hello/{name}', function ($request, $name) {
        return 'Hello, ' . $name;
    })
    ->post('/hello', function ($request) {
        return 'Hello, ' . $request->get('name');
    })
    ->get('/stats', function ($request) {
        return 'Stats';
    })
    ->get('/stats/{id}', function ($request, $id) {
        return 'Stats for ' . $id;
    });

[KorvinSzanto]

Sounds like an interesting project!

1. Attributes (Section 12.3)

should the block itself break?

PER-CS specifies this:

If the attribute list is split into multiple lines for any reason, then the attributes MUST be placed in separate attribute blocks. Those blocks may themselves contain multiple attributes provided this rule is respected.

#[Foo, Baz, Bar]

// Becomes
#[Foo]
#[Baz, Bar]

2. Arrow Functions (Section 7.1)

I would wrap the expression and leave the arrow function syntax unwrapped as shown in your second example. PER-CS says the following:

The expression portion MAY be split to a subsequent line. If so, the => MUST be included on the second line, and MUST be indented once.

To my eyes, that applies when splitting the entirety of the expression to the next line, and not when splitting the expression itself, though the doc could be more clear about this a la "Method and Function calls":

A single argument being split across multiple lines (as might be the case with a closure or array) does not constitute splitting the argument list itself.

3. Ternary Operators (Section 6.3)

PER-CS doesn't explicitly allow splitting ternary operators across lines, though something like your last example is allowed:

$foo = $foo ? $foo : [
    'foo' => 'bar',
    'baz' => 'qux',
    'quux' => 'quuz',
    'corge' => 'grault',
    'garply' => 'waldo',
    'fred' => $x,
];
// or actually
$baz = $baz ?: [
    'multiline',
    'array',
];

4. Try/Catch/Finally (Section 5.6)

The operator spacing on try/catch is inconsistent and might change in the future:

• Add handling for compound types. #45
• Operator spacing union types / multi-catch expressions #67 (comment)

5. Foreach (Section 5.5)

Wrapping foreach isn't explicitly allowed by PER-CS today

6. Method Chaining (Section 4.7)

When should method chaining break?

When and where to split is up to the implementor. Other than requiring certain statements to be on their own line, PER-CS only offers the following:

The soft limit on line length MUST be 120 characters.

Lines SHOULD NOT be longer than 80 characters; lines longer than that SHOULD be split into multiple subsequent lines of no more than 80 characters each.

Note that these are not hard limits, so really any line length is allowed by PER-CS. This rule is intended to encourage implementors to split their own lines at reasonable lengths where they deem appropriate.

another question regarding method chaining, should the first call be indented?

Yes, and on its own line. So neither of your examples are allowed.

7. Line Width and Blank Lines (Section 2.3)

This is confusing. Is the soft limit 120 or 80? If it’s 120, why split lines into 80-character chunks?

Note the usage of RFC-2119 terms:

Soft line limit MUST be 120
This means the soft limit is 120 characters

Lines SHOULD NOT be longer than 80 characters, longer lines SHOULD be split
This is a recommendation

While I agree this is confusing, I much prefer it to a hard line limit. The way I apply this to my code is I keep lines under 80 characters where possible and convenient, and under 120 characters unless I have a really good reason. Having the soft limit and the recommendation allows me avoid things like splitting a large base64 string, or a URL across multiple lines when not necessary.

Hope this helps!

[samdark]

Closing since the questions were answered. @azjezz if there are any suggestions to existing wording or rules of the PER, please create separate issues. Thanks.