feat(formatter): add first-method-chain-on-new-line option

azjezz · azjezz · commit 3237e2009e8b · 2025-12-19T12:22:37.000+01:00
closes #775 Signed-off-by: azjezz <azjezz@protonmail.com>
diff --git a/crates/formatter/src/internal/format/member_access.rs b/crates/formatter/src/internal/format/member_access.rs
@@ -265,6 +265,11 @@ impl<'arena> MemberAccessChain<'arena> {
         matches!(self.accesses.first(), Some(MemberAccess::StaticMethodCall(_)))
     }
 
+    #[inline]
+    fn is_first_link_object_method_call(&self) -> bool {
+        matches!(self.accesses.first(), Some(MemberAccess::MethodCall(_) | MemberAccess::NullSafeMethodCall(_)))
+    }
+
     #[inline]
     fn is_already_broken(&self, f: &FormatterState) -> bool {
         let mut accesses_len = self.accesses.len();
@@ -624,6 +629,10 @@ fn should_inline_first_access<'arena>(
     f: &FormatterState<'_, 'arena>,
     member_access_chain: &MemberAccessChain<'arena>,
 ) -> bool {
+    if f.settings.first_method_chain_on_new_line && member_access_chain.is_first_link_object_method_call() {
+        return false;
+    }
+
     if member_access_chain.find_fluent_access_chain_start().is_some_and(|start| start == 0) {
         return false;
     }
diff --git a/crates/formatter/src/settings.rs b/crates/formatter/src/settings.rs
@@ -325,6 +325,27 @@ pub struct FormatSettings {
     #[serde(default)]
     pub method_chain_breaking_style: MethodChainBreakingStyle,
 
+    /// When method chaining breaks across lines, place the first method on a new line.
+    ///
+    /// This follows PER-CS 4.7: "When [method chaining is] put on separate lines, [...] the first method MUST be on the next line."
+    ///
+    /// When enabled:
+    /// ```php
+    /// $this
+    ///     ->getCache()
+    ///     ->forget();
+    /// ```
+    ///
+    /// When disabled:
+    /// ```php
+    /// $this->getCache()
+    ///     ->forget();
+    /// ```
+    ///
+    /// Default: `true`
+    #[serde(default = "default_true")]
+    pub first_method_chain_on_new_line: bool,
+
     /// Whether to preserve line breaks in method chains, even if they could fit on a single line.
     ///
     /// Default: false
@@ -930,6 +951,7 @@ impl Default for FormatSettings {
             null_type_hint: NullTypeHint::default(),
             break_promoted_properties_list: true,
             method_chain_breaking_style: MethodChainBreakingStyle::NextLine,
+            first_method_chain_on_new_line: true,
             line_before_binary_operator: true,
             sort_uses: true,
             sort_class_methods: false,
diff --git a/crates/formatter/tests/cases/chain_comments/after.php b/crates/formatter/tests/cases/chain_comments/after.php
@@ -19,7 +19,8 @@ private function generateMenuItemUrl(MenuItemDto $menuItemDto): string
                 // set any other parameters defined by the menu item
                 ->setAll($routeParameters);
 
-            $mainTemplate = $this->cleanupTemplate($template)
+            $mainTemplate = $this
+                ->cleanupTemplate($template)
                 // Cleanup head, we'll insert it after having parsed the DOM
                 ->replaceRegex('/<head>((.|\n)*?)<\/head>/', '<head></head>');
         }
diff --git a/crates/formatter/tests/cases/issue_122/after.php b/crates/formatter/tests/cases/issue_122/after.php
@@ -5,7 +5,8 @@
     ->belongsTo('user_permissions.user_id', 'users.id')
     ->belongsTo('user_permissions.permission_id', 'permissions.id');
 
-$item = $this->getCachePool()
+$item = $this
+    ->getCachePool()
     ->getItem($key)
     ->set($value);
 
diff --git a/docs/tools/formatter/configuration-reference.md b/docs/tools/formatter/configuration-reference.md
@@ -55,6 +55,7 @@ excludes = ["src/**/AutoGenerated/**/*.php"]  # Additionally excluded from forma
 | `inline-empty-classlike-braces` | `boolean` | `false` | Place empty class-like bodies on the same line. |
 | `inline-empty-anonymous-class-braces` | `boolean` | `true` | Place empty anonymous class bodies on the same line. |
 | `method-chain-breaking-style`| `enum("same-line", "next-line")` | `"next-line"` | How to break method chains. |
+| `first-method-chain-on-new-line` | `boolean` | `true` | When method chaining breaks across lines, place the first method call on a new line. Only applies to object method calls (`->`, `?->`), not static methods (`::`) or property access ([PER-CS 4.7](https://www.php-fig.org/per/coding-style/#47-method-and-function-calls) compliant). |
 | `preserve-breaking-member-access-chain` | `boolean` | `false` | Preserve existing line breaks in method chains. |
 | `preserve-breaking-argument-list` | `boolean` | `false` | Preserve existing line breaks in argument lists. |
 | `preserve-breaking-array-like` | `boolean` | `true` | Preserve existing line breaks in array-like structures. |

Original file line number	Diff line number	Diff line change
`@@ -19,7 +19,8 @@ private function generateMenuItemUrl(MenuItemDto $menuItemDto): string`
`19`	`19`	`// set any other parameters defined by the menu item`
`20`	`20`	`->setAll($routeParameters);`
`21`	`21`
`22`		`- $mainTemplate = $this->cleanupTemplate($template)`
	`22`	`+ $mainTemplate = $this`
	`23`	`+ ->cleanupTemplate($template)`
`23`	`24`	`// Cleanup head, we'll insert it after having parsed the DOM`
`24`	`25`	`->replaceRegex('/<head>((.\|\n)*?)<\/head>/', '<head></head>');`
`25`	`26`	`}`