PHP Fold Long Comments

Collapses the block comments that are long enough to be in the way when a PHP file opens, 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. 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.

Requirements

VS Code 1.80 or newer, and a folding provider for PHP that tags comment ranges.

This matters. 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 nothing 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 block comment 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.
• Block comments only. A run of consecutive // lines has no closing marker and no folding range of its own, so it is left as it is.
• 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. 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.

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.