feat: hug a single heredoc argument and attach the comma to its closing marker

src/printer.mjs

@@ -32,6 +32,7 @@ import {
   hasEmptyBody,
   isNextLineEmptyAfterNamespace,
   shouldPrintHardlineBeforeTrailingComma,
+  isHeredocNode,
   isDocNode,
   getAncestorNode,
   isReferenceLikeNode,
@@ -626,7 +627,7 @@ function printArgumentsList(path, options, print, argumentsKey = "arguments") {
         node.kind
       ))
       ? indent([
-          lastArg && shouldPrintHardlineBeforeTrailingComma(lastArg)
+          lastArg && shouldPrintHardlineBeforeTrailingComma(lastArg, options)
             ? hardline
             : "",
           ",",
@@ -1648,6 +1649,32 @@ function isStringOnItsOwnLine(node, text) {
   );
 }
 
+// `foo(<<<'SQL' ... SQL)` and `foo("multi-line string")`: a single string-like argument
+// stays on the call's line instead of breaking the argument list (PER-CS 4.7:
+// one argument spanning several lines does not split the list). A heredoc only
+// hugs from PHP 7.3 on, when its closing marker may be followed by `)`.
+function shouldHugSingleStringArgument(node, options) {
+  if (node.arguments.length !== 1) {
+    return false;
+  }
+
+  const [argument] = node.arguments;
+
+  return (
+    isStringOnItsOwnLine(argument, options.originalText) ||
+    (options.phpVersion >= 7.3 && isHeredocNode(argument))
+  );
+}
+
+function printSingleStringArgument(path, print) {
+  const [argument] = path.node.arguments;
+  const printed = path.map(print, "arguments");
+
+  // PER-CS 10: the heredoc body and closing marker are indented once past the
+  // statement; a quoted string keeps its literal lines as they are.
+  return ["(", isHeredocNode(argument) ? indent(printed) : printed, ")"];
+}
+
 function printComposedTypes(path, print, glue) {
   return group(
     path.map(({ isFirst }) => (isFirst ? [print()] : [glue, print()]), "types")
@@ -2162,17 +2189,9 @@ function printNode(path, options, print) {
 
       return node.kind;
     case "call": {
-      // Multiline strings as single arguments
-      if (
-        node.arguments.length === 1 &&
-        isStringOnItsOwnLine(node.arguments[0], options.originalText)
-      ) {
-        return [
-          print("what"),
-          "(",
-          join(", ", path.map(print, "arguments")),
-          ")",
-        ];
+      // Multiline strings and heredocs as single arguments
+      if (shouldHugSingleStringArgument(node, options)) {
+        return [print("what"), printSingleStringArgument(path, print)];
       }
 
       // chain: Call (*LookupNode (Call (*LookupNode (...))))
@@ -2186,19 +2205,16 @@ function printNode(path, options, print) {
       const isAnonymousClassNode =
         node.what && node.what.kind === "class" && node.what.isAnonymous;
 
-      // Multiline strings as single arguments
+      // Multiline strings and heredocs as single arguments
       if (
         !isAnonymousClassNode &&
-        node.arguments.length === 1 &&
-        isStringOnItsOwnLine(node.arguments[0], options.originalText)
+        shouldHugSingleStringArgument(node, options)
       ) {
         return [
           "new ",
           ...path.call(printAttrs, "what"),
           print("what"),
-          "(",
-          join(", ", path.map(print, "arguments")),
-          ")",
+          printSingleStringArgument(path, print),
         ];
       }
 
@@ -2590,7 +2606,8 @@ function printNode(path, options, print) {
           ifBreak(
             !needsForcedTrailingComma && shouldPrintComma(options, 5.0)
               ? [
-                  lastElem && shouldPrintHardlineBeforeTrailingComma(lastElem)
+                  lastElem &&
+                  shouldPrintHardlineBeforeTrailingComma(lastElem, options)
                     ? hardline
                     : "",
                   ",",
@@ -2942,7 +2959,8 @@ function printNode(path, options, print) {
             node.type === "heredoc" ? linebreak : "",
             ...path.map(print, "value"),
             getEncapsedQuotes(node, { opening: false }),
-            node.type === "heredoc" && docShouldHaveTrailingNewline(path)
+            node.type === "heredoc" &&
+            docShouldHaveTrailingNewline(path, options)
               ? hardline
               : "",
           ];
@@ -2969,7 +2987,7 @@ function printNode(path, options, print) {
         join(linebreak, node.value.split("\n")),
         linebreak,
         node.label,
-        docShouldHaveTrailingNewline(path) ? hardline : "",
+        docShouldHaveTrailingNewline(path, options) ? hardline : "",
       ];
     }
     case "name":

src/util.mjs

@@ -228,7 +228,14 @@ function isDocNode(node) {
  * Heredoc/Nowdoc nodes need a trailing linebreak if they
  * appear as function arguments or array elements
  */
-function docShouldHaveTrailingNewline(path, recurse = 0) {
+// Before PHP 7.3 the closing marker of a heredoc or nowdoc had to be alone on
+// its line, so anything following it (`,`, `:`, `=>`) needed a line break.
+// Flexible heredocs (7.3+) lift that restriction; the marker is then followed
+// by the comma, as in PER-CS 10. Two exceptions keep the line break in every
+// version: a concatenation operator, which the `bin` printer lays out on its
+// own line, and the `:` of a `case`, which php-parser does not accept right
+// after a closing marker although PHP does.
+function docShouldHaveTrailingNewline(path, options, recurse = 0) {
   const node = path.getNode(recurse);
   const parent = path.getNode(recurse + 1);
   const parentParent = path.getNode(recurse + 2);
@@ -237,6 +244,10 @@ function docShouldHaveTrailingNewline(path, recurse = 0) {
     return false;
   }
 
+  if (options.phpVersion >= 7.3 && !["bin", "case"].includes(parent.kind)) {
+    return false;
+  }
+
   if (
     (parentParent &&
       ["call", "new", "echo"].includes(parentParent.kind) &&
@@ -271,7 +282,8 @@ function docShouldHaveTrailingNewline(path, recurse = 0) {
 
   if (parent.kind === "bin") {
     return (
-      parent.left === node || docShouldHaveTrailingNewline(path, recurse + 1)
+      parent.left === node ||
+      docShouldHaveTrailingNewline(path, options, recurse + 1)
     );
   }
 
@@ -319,7 +331,7 @@ function docShouldHaveTrailingNewline(path, recurse = 0) {
   }
 
   if (parent.kind === "retif") {
-    return docShouldHaveTrailingNewline(path, recurse + 1);
+    return docShouldHaveTrailingNewline(path, options, recurse + 1);
   }
 
   return false;
@@ -564,19 +576,26 @@ function isNextLineEmptyAfterNamespace(text, node) {
   return hasNewline(text, idx);
 }
 
-function shouldPrintHardlineBeforeTrailingComma(lastElem) {
-  if (
-    lastElem.kind === "nowdoc" ||
-    (lastElem.kind === "encapsed" && lastElem.type === "heredoc")
-  ) {
+function isHeredocNode(node) {
+  return (
+    node.kind === "nowdoc" ||
+    (node.kind === "encapsed" && node.type === "heredoc")
+  );
+}
+
+// Before PHP 7.3 the closing marker of a heredoc or nowdoc had to be alone on
+// its line, so a trailing comma after it needed a line of its own. Flexible
+// heredocs (7.3+) allow `LABEL,`, which is also what PER-CS 10 shows.
+function shouldPrintHardlineBeforeTrailingComma(lastElem, options) {
+  if (options.phpVersion >= 7.3) {
+    return false;
+  }
+
+  if (isHeredocNode(lastElem)) {
     return true;
   }
 
-  if (
-    lastElem.kind === "entry" &&
-    (lastElem.value.kind === "nowdoc" ||
-      (lastElem.value.kind === "encapsed" && lastElem.value.type === "heredoc"))
-  ) {
+  if (lastElem.kind === "entry" && isHeredocNode(lastElem.value)) {
     return true;
   }
 
@@ -754,6 +773,7 @@ export {
   hasEmptyBody,
   isNextLineEmptyAfterNamespace,
   shouldPrintHardlineBeforeTrailingComma,
+  isHeredocNode,
   isDocNode,
   getAncestorNode,
   normalizeMagicMethodName,

tests/call/__snapshots__/jsfmt.spec.mjs.snap

@@ -655,55 +655,45 @@ string
 $var\`,
 );
 
-call(
-    <<<FOO
+call(<<<FOO
     string
     string
     string
     $var
-    FOO
-    ,
-);
+    FOO);
 
-call(
-    <<<'FOO'
+call(<<<'FOO'
     string
     string
     string
-    FOO
-    ,
-);
+    FOO);
 
 call(
     <<<FOO
     string
     string
     string
     $var
-    FOO
-    ,
+    FOO,
     <<<FOO
     string
     string
     string
     $var
-    FOO
-    ,
+    FOO,
 );
 
 call(
     <<<'FOO'
     string
     string
     string
-    FOO
-    ,
+    FOO,
     <<<'FOO'
     string
     string
     string
-    FOO
-    ,
+    FOO,
 );
 
 $var = ($this->foo)();

tests/comments/__snapshots__/jsfmt.spec.mjs.snap

@@ -2760,8 +2760,7 @@ echo // Comment
     Example of string
     spanning multiple lines
     using heredoc syntax.
-    EOD
-    ,
+    EOD,
     $a;
 
 ================================================================================

tests/echo/__snapshots__/jsfmt.spec.mjs.snap

@@ -427,16 +427,14 @@ echo <<<EOD
     Example of string
     spanning multiple lines
     using heredoc syntax.
-    EOD
-    ,
+    EOD,
     "test";
 
 echo <<<'EOD'
     Example of string
     spanning multiple lines
     using nowdoc syntax.
-    EOD
-    ,
+    EOD,
     "test";
 
 echo 'string