RFC: New option phpVersion

[czosel]

From the discussion in #1274 the idea to introduce a new option phpVersion emerged. Since this affects a few other ongoing discussions we'd like to share the plan and ask for feedback! If you agree to the proposal and have nothing to add, feel free to post a 👍 reaction!

The basic issue we'd like to solve is that in some cases we need to know the PHP version in use to achieve optimal formatting. For example, starting with PHP 7.3, heredoc/nowdoc can be formatted in a more readable (indented) way, which doesn't work in previous versions.

The following table summarizes the areas where we'd currently benefit from knowing the PHP Version:

Feature	Available since	Benefit
#1274 Flexible heredoc/nowdoc syntax	7.3	Prettier way to print heredoc/nowdoc
#939 Array shorthand notation	5.4	Print array(...) as shorthand [...]
#493 Trailing commas in arrays and lists	5.0 (?)	Print trailing commas by default
Trailing commas in "use"	7.2	(same)
Trailing commas in function calls	7.3	(same)

We propose to do the following changes:

• Introduce new option phpVersion
  As the name says, this options allows you to specify the PHP version you're using. Any valid PHP version numer can be specified as value, but they fall in different categories:

  • 7.1, 7.0, 5.6, 5.5, 5.4: Since our formatting doesn't change between these versions, all of them are equivalent. Since most users are using one of these versions, this category would be the default.
  • 7.2: Print trailing commas in "use"
  • 7.3, 7.4: Print trailing commas in function calls
  • 5.3, 5.2, 5.1, 5.0 and older: Don't force array shorthand notation
  • older versions: Show "not supported" message

• trailing commas

  • remove all option values of except none and all, make it a Boolean (none => false, all => true)
  • change the default to true (which checks the phpVersion setting to determine which trailing commas can be printed) (see Behavior change: Add trailing commas to array items #493 (comment))

• array shorthand
  Print array(...) as shorthand [...] except when phpVersion < 5.4

• flexible heredoc/nowdoc
  Print heredoc/nowdoc in "classic" (non-flexible) style except when phpVersion >= 7.3

If you'd like to read more about the reasoning behind this, alternatives and trade-offs please see #1274. Thanks!

[joemaller]

Could an implementation of this also support presets? @czosel mentioned config presets in #1274 (comment) and I could see those being equally useful. (eg. WordPress vs. Symfony) Maybe they could be pluggable with separate packages providing the definitions, similar to how eslint and stylelint work with their config packages.

[czosel]

Hmm, I think that would contradict prettiers option philisophy (you probably know the text, but I find it helps to re-read it sometimes 🙂). I used the preset analogy because phpVersion allows to infer several "low-level" decisions based on a single high-level configuration setting. But I currently don't see why would want more of them. It would be great if this plugin could achieve the same level of standardization in the PHP community as Prettier did for JS.

[alexander-akait]

👍 On roadmap

[ZeeCoder]

This makes perfect sense to me. it makes config simpler.
Just reading about trailing commas was annoying when I set things up. 😅

that's exactly what I don't want to have to care about.

[sparcbr]

Is there a specific option to force the old behavior of using 'array()' instead of shorthand notation without using the generic "phpVersion": "5.3" ?

[alexander-akait]

@sparcbr Please open a new issue