PHP Fold Long Comments

Collapses the comments that are long enough to be in the way when a PHP file opens - block comments and runs of // lines alike - and leaves the short ones alone.

/**                                    ⌄  /** The question the creating route ⋯
 * The question the creating route is
 * answered by Crm\Rules\Order\...     →
 * ... twelve more lines of prose
 */

/**                                       /**
 * @param int $orderId                 →   * @param int $orderId
 * @return Order                           * @return Order
 */                                        */

Why this exists

VS Code collapses one kind of folding range on open and only one:

"editor.foldingImportsByDefault": true

There is no foldingCommentsByDefault to go with it. The existing fold-on-open extensions drive the built-in Fold All Block Comments command instead, which is all-or-nothing: a fourteen-line explanation and a three-line @param/@return docblock collapse together, and folding the second one buys nothing while costing a click every time you read the signature.

This extension puts a length between them.

What it does

When a PHP file becomes the active editor for the first time, every block comment spanning at least minimumLines lines is collapsed, and so is every run of that many consecutive // or # lines. Short ones stay open. Unfolding one keeps it open — the file is only folded once, the same way editor.foldingImportsByDefault folds a model once — and closing the tab resets that.

The line count spans the comment whole, /** and */ included, which is how it reads on screen. A line-comment run ends at a blank line or at a line with code before its //, so a trailing comment never joins one; #[ attributes are not comments.

Requirements

VS Code 1.80 or newer. Block comments also need a folding provider for PHP that tags comment ranges; // runs do not.

This matters for block comments. For those the extension does not parse PHP: it asks VS Code for the document's folding ranges, keeps the ones tagged Comment, and folds those. With no such provider the ranges come from VS Code's indentation fallback, which tags nothing, and no block comment is folded — the extension goes quiet rather than guessing at line numbers, because a line guessed wrong would collapse the enclosing class instead of the comment.

Two providers are known to tag them:

• PHP Fold Imports — free, no language server. Its companion setting is the import fold this one is named after.
• Intelephense Premium — folding is a licensed feature there; without a key the language server reports foldingRangeProvider: false and contributes no ranges at all.

Configuration

{
    // How many lines a comment (block, or a run of // lines) has to span before it folds on open.
    // Minimum 2, default 6.
    "phpFoldLongComments.minimumLines": 6,

    // Fold on open at all. The Fold Long Comments command keeps working when this is off.
    "phpFoldLongComments.enabled": true
}

minimumLines is resource-scoped, so a workspace with denser comments can carry its own value in .vscode/settings.json.

Changing either setting re-folds the active file. Lowering the threshold therefore folds more straight away; raising it cannot un-collapse what is already folded, and takes effect the next time the file opens.

Command

PHP Fold Long Comments: Fold Long Comments (phpFoldLongComments.foldNow) applies the same pass to the current file on demand — after unfolding a few to read them, or to see the effect of a new threshold without reopening the tab. It runs even with enabled off.

Ctrl+K Ctrl+J unfolds everything in the file, as always.

Limitations

• PHP only. .blade.php files are usually mapped to the blade language and are not touched.
• A line-comment run holding the cursor stays open, because putting the cursor back inside it would unfold it again straight away.
• The active editor only. editor.fold is an editor command and applies to whatever is focused, so a file opened into a background split folds when you switch to it.

How it works

select.js is the whole decision: given the folding ranges of a document, return the start lines of the Comment-kind ones that span minimumLines or more; given its text, return the runs of // / # lines that long. It has no dependency on the vscode module, which is what makes it testable as plain Node.

extension.js is the plumbing around it. On onDidChangeActiveTextEditor (and on the editor that triggered activation) it asks vscode.executeFoldingRangeProvider for the ranges and hands the selected start lines to editor.fold as selectionLines, which collapses the innermost region starting at each one.

Line comments have no folding range from any provider - there is no closing marker to end one on - so editor.fold would have nothing to collapse there. Each run is selected instead and handed to Create Folding Range from Selection (editor.createFoldingRangeFromSelection), which makes a manual range of exactly those lines and collapses it; the cursor and selections are put back afterwards. A run a provider already reports as a comment range is left to that range.

The one race worth naming: folding providers activate on the same onLanguage:php event this extension does, so the first ask can come back before they have registered — indistinguishable from a file with no block comments. A document that reports no comment ranges at all is therefore asked a second time, 300 ms later, before being left alone.

Development

node test.js             # unit tests, no dependencies
./build.sh               # test, pack the vsix, reinstall, then reload the window

Every push and pull request runs the same suite on GitHub Actions, preceded by a node --check of the two files that ship.

License

MIT — see LICENSE.txt.