New Recipe: php-ts-mode

[skyler544]

Emacs 30+ introduces a native php-ts-mode; I've been using it for a few weeks and it seems to work fine. The new mode depends on all three of these recipes; I'm opening this as a single PR but if you prefer I can close this one and resubmit it as three different ones as described in the contributing guidelines.

Thanks for this package!

[renzmann]

The only thing I'm not sure about is having multiple recipes that declare the same :ext - with our current implementation of treesit-auto--get-buffer-recipe, it would load the mode first appearing in treesit-auto--selected-recipes. As someone well outside the PHP realm, the only one that definitely makes sense to me is the PHP recipe; the other two (jsdoc and phpdoc) look odd. Are they additional grammars that are supposed to load when php-ts-mode is activated? Are jsdoc and phpdoc supposed to have their own modes?

The PHP one by itself looks good, but I'd need a bit more clarity on how the jsdoc and phpdoc ones are supposed to work - even if it's just for my sake as someone unfamiliar with that ecosystem.

[skyler544]

Thanks for the input, and sorry about the delayed response. You're definitely right about the inclusion of :ext being incorrect; I've added a commit removing it from the jsdoc and phpdoc recipes.

The minimal set of grammars needed for the new php-ts-mode to activate properly is [php phpdoc html javascript jsdoc css]. I'm no PHP whiz, but most of these requirements make sense to me in the context of web development; PHP can output HTML for instance, and HTML can include CSS and JS. The phpdoc parser is for docblock style comments, which can be used to annotate methods in PHP similar to docstrings in Emacs Lisp. I assume jsdoc has a similar purpose.

The following config example sets up php-ts-mode successfully with the recipes from this PR loaded via use-package's :load-path keyword:

(use-package php-ts-mode
  :mode ("\\.php$" . php-ts-mode))

(use-package treesit-auto
  :load-path "/path/to/treesit-auto"
  :hook ((after-init . treesit-auto-install-all)
         (after-init . global-treesit-auto-mode))
  :custom
  (treesit-auto-install t)
  (treesit-auto-langs '(php phpdoc html javascript jsdoc css)))

This approach won't work if the user prefers to be prompted when opening a PHP file instead of automatically installing the grammars. Looking through the code in this library, I didn't immediately see any other modes that need multiple parsers; is there another similar case that can be used as an example for the best way of ensuring that /all/ of the needed parsers are installed when prompting the user?

On another note, php-ts-mode has its own variable for keeping track of which parsers are needed
and where to get them from: php-ts-mode--language-source-alist. However, some of the recipes it includes aren't correct because the Emacs maintainers haven't yet decided what to do in cases of nonstandard parser repository structures. Relevant thread here if you're interested. This of course means that treesit-auto is still a valuable tool to have for php-ts-mode.