Add a modern Tree-sitter PHP grammar

This one’s got all the frills, including injections into HTML documents and a PHPDoc grammar.

As part of this change, we're also migrating to `web-tree-sitter` version 0.20.8 with some customizations. The PR I submitted at tree-sitter/tree-sitter#2795 is landed on this fork, though if the same issues get fixed in a different way on the source, I'll adopt that approach as well. The PHPDoc parser needed another external added.

Author: savetheclocktower

packages/language-php/grammars/modern-tree-sitter-php-html.cson

@@ -0,0 +1,33 @@
+name: 'PHP'
+scopeName: 'text.html.php'
+type: 'modern-tree-sitter'
+parser: 'tree-sitter-php'
+
+injectionRegex: 'php|PHP'
+
+treeSitter:
+  grammar: 'tree-sitter/tree-sitter-php.wasm'
+  highlightsQuery: 'tree-sitter/queries/highlights.scm'
+  tagsQuery: 'tree-sitter/queries/tags.scm'
+  foldsQuery: 'tree-sitter/queries/folds.scm'
+  indentsQuery: 'tree-sitter/queries/indents.scm'
+
+fileTypes: [
+  'aw'
+  'ctp'
+  'inc'
+  'install'
+  'module'
+  'php'
+  'php_cs'
+  'php3'
+  'php4'
+  'php5'
+  'phpt'
+  'phtml'
+  'profile'
+]
+
+firstLineRegex: "^\\#!.*(?:\\s|\\/)php\\d?(?:$|\\s)|^\\s*<\\?(php|=|\\s|$)"
+
+contentRegex: "<\\?(php|=|\\s|$)"

packages/language-php/grammars/modern-tree-sitter-php.cson

@@ -0,0 +1,11 @@
+scopeName: 'source.php'
+type: 'modern-tree-sitter'
+parser: 'tree-sitter-php'
+
+# Give it a precise injectionRegex that won't get accidentally matched with
+# anything. This grammar only exists as a way to apply the `source.php` scope.
+injectionRegex: '^(internal-php)$'
+
+treeSitter:
+  grammar: 'tree-sitter/tree-sitter-php.wasm'
+  highlightsQuery: 'tree-sitter/queries/empty.scm'

packages/language-php/grammars/modern-tree-sitter-phpdoc.cson

@@ -0,0 +1,11 @@
+
+scopeName: 'comment.block.documentation.phpdoc.php'
+type: 'modern-tree-sitter'
+parser: 'tree-sitter-phpdoc'
+
+injectionRegex: '^(phpdoc|PHPDoc)$'
+
+treeSitter:
+  parserSource: 'github:claytonrcarter/tree-sitter-phpdoc#915a527d5aafa81b31acf67fab31b0ac6b6319c0'
+  grammar: 'tree-sitter/tree-sitter-phpdoc.wasm'
+  highlightsQuery: 'tree-sitter/queries/phpdoc/highlights.scm'

packages/language-php/grammars/tree-sitter/queries/empty.scm

@@ -0,0 +1 @@
+; placeholder

packages/language-php/grammars/tree-sitter/queries/folds.scm

@@ -0,0 +1 @@
+;

packages/language-php/grammars/tree-sitter/queries/highlights-html.scm

@@ -0,0 +1 @@
+; Placeholder

packages/language-php/grammars/tree-sitter/queries/highlights.scm

@@ -0,0 +1,8 @@
+;
+
+["{" "(" "["] @indent
+["}" ")" "]"] @dedent
+
+":" @indent
+
+["endif" "endfor" "endforeach" "enddeclare" "endswitch"] @dedent

packages/language-php/grammars/tree-sitter/queries/indents.scm

@@ -0,0 +1,17 @@
+
+((document) @punctuation.definition.begin.comment.phpdoc.php
+  (#set! adjust.startAndEndAroundFirstMatchOf "^/\\*\\*"))
+
+((document) @punctuation.definition.end.comment.phpdoc.php
+  (#set! adjust.startAndEndAroundFirstMatchOf "(?:\\*)?\\*/$"))
+
+(tag_name) @storage.type.class.phpdoc.php
+
+(tag (type_list) @entity.other.type.instance.phpdoc.php)
+
+(variable_name) @variable.other.phpdoc.php
+
+(uri) @markup.underline.link.phpdoc.php
+
+(inline_tag "{" @punctation.definition.tag.begin.brace.curly.phpdoc.php)
+(inline_tag "}" @punctation.definition.tag.end.brace.curly.phpdoc.php)

packages/language-php/grammars/tree-sitter/queries/phpdoc/highlights.scm

@@ -0,0 +1,41 @@
+
+(namespace_definition
+  name: (namespace_name) @name) @module
+
+(interface_declaration
+  name: (name) @name) @definition.interface
+
+(trait_declaration
+  name: (name) @name) @definition.interface
+
+(class_declaration
+  name: (name) @name) @definition.class
+
+(class_interface_clause [(name) (qualified_name)] @name) @impl
+
+(property_declaration
+  (property_element (variable_name (name) @name))) @definition.field
+
+(function_definition
+  name: (name) @name) @definition.function
+
+(method_declaration
+  name: (name) @name) @definition.function
+
+(object_creation_expression
+  [
+    (qualified_name (name) @name)
+    (variable_name (name) @name)
+  ]) @reference.class
+
+(function_call_expression
+  function: [
+    (qualified_name (name) @name)
+    (variable_name (name)) @name
+  ]) @reference.call
+
+(scoped_call_expression
+  name: (name) @name) @reference.call
+
+(member_call_expression
+  name: (name) @name) @reference.call

packages/language-php/grammars/tree-sitter/queries/tags.scm

@@ -0,0 +1,132 @@
+exports.activate = function () {
+
+  // Here's how we handle the mixing of PHP and HTML:
+  //
+  // * The root language layer uses the `tree-sitter-php` parser, and handles
+  //   all tasks: highlighting, indentation, folds.
+  // * HTML gets injected into all `text` nodes.
+  // * A corresponding PHP injection point is created for non-text nodes and
+  //   represents all non-HTML regions of the buffer.
+  //
+  // We do it this way so that we can limit the scope `source.php` to only
+  // those ranges identified by the injection. The way the `tree-sitter-php`
+  // tree is organized rules out all other options for adding scope boundaries
+  // to embedded PHP ranges. And injections enjoy an ability that query
+  // captures do not: they are allowed to apply their base scope to arbitrary
+  // ranges of the tree. If we can describe the ranges in the `content`
+  // callback, we can scope each range the way we want.
+  //
+  // This may seem like an odd thing to do, but it's critical for us to know
+  // when we're in `source.php` and when we aren't. For instance, nearly all of
+  // the snippets in `language-php` are valid only in one mode or the other.
+  //
+  // This means that, technically speaking, the PHP injection layer doesn't
+  // have any tasks, and doesn't even need to do any parsing. If injections had
+  // the option of re-using another layer's tree, we'd want to do that, but
+  // right now there's not a need for such a feature.
+
+  atom.grammars.addInjectionPoint('text.html.php', {
+    type: 'program',
+    language: () => 'html',
+    content(node) {
+      return node.descendantsOfType('text');
+    },
+
+    // We don't need a base scope for this injection because the whole file is
+    // already scoped as `text.html.php`. The PHP embeds add a `source.php`
+    // scope, but still has `text.html.php` as the root. This is how the TM
+    // grammar works, so we're replicating it here.
+    languageScope: null
+  });
+
+  atom.grammars.addInjectionPoint('text.html.php', {
+    type: 'program',
+    language() {
+      return 'internal-php';
+    },
+    content(node) {
+      let results = [];
+      // At the top level we should ignore `text` nodes, since they're just
+      // HTML. We should also ignore the middle children of
+      // `text_interpolation` nodes (also `text`), but we need to include their
+      // first and last children, which correspond to `?>` and `<?php`.
+      //
+      // In practice, it seems that `text` is always a child of the root except
+      // inside of `text_interpolation`, and `text_interpolation` is always a
+      // child of the root. The only exceptions I've noticed are when the tree
+      // is in an error state, so they may not be worth worrying about.
+      for (let child of node.children) {
+        if (child.type === 'text') { continue; }
+        if (child.type === 'text_interpolation') {
+          for (let grandchild of child.children) {
+            if (grandchild.type === 'text') { continue; }
+            results.push(grandchild);
+          }
+          continue;
+        }
+        results.push(child);
+      }
+      return results;
+    },
+    includeChildren: true,
+    newlinesBetween: true,
+    includeAdjacentWhitespace: true
+  });
+
+  const TODO_PATTERN = /\b(TODO|FIXME|CHANGED|XXX|IDEA|HACK|NOTE|REVIEW|NB|BUG|QUESTION|COMBAK|TEMP|DEBUG|OPTIMIZE|WARNING)\b/;
+  const HYPERLINK_PATTERN = /\bhttps?:/
+
+  function isPhpDoc(node) {
+    let { text } = node;
+    return text.startsWith('/**') && !text.startsWith('/***')
+  }
+
+  atom.grammars.addInjectionPoint('text.html.php', {
+    type: 'comment',
+    language: (node) => {
+      return TODO_PATTERN.test(node.text) ? 'todo' : undefined;
+    },
+    content: (node) => node,
+    languageScope: null
+  });
+
+  for (let type of ['comment', 'string_value']) {
+    atom.grammars.addInjectionPoint('text.html.php', {
+      type,
+      language(node) {
+        // PHPDoc can parse URLs better than we can.
+        if (isPhpDoc(node)) return undefined;
+        return HYPERLINK_PATTERN.test(node.text) ?
+          'hyperlink' : undefined;
+      },
+      content: (node) => node,
+      languageScope: null
+    });
+  }
+
+  atom.grammars.addInjectionPoint('text.html.php', {
+    type: 'heredoc',
+    language(node) {
+      let id = node.firstNamedChild;
+      if (id.type !== 'heredoc_start') { return null; }
+      console.log('returning heredoc name:', id.text);
+      return id.text;
+    },
+    content(node) {
+      let body = node.children.find(c => c.type === 'heredoc_body');
+      let results = body.children.filter(c => c.type === 'string_value');
+      return results;
+    }
+  });
+
+  atom.grammars.addInjectionPoint('text.html.php', {
+    type: 'comment',
+    language(node) {
+      if (isPhpDoc(node)) {
+        return 'phpdoc';
+      }
+    },
+    content(node) { return node; }
+  });
+
+};

packages/language-php/grammars/tree-sitter/tree-sitter-php.wasm

@@ -1,10 +1,11 @@
 {
   "name": "language-php",
   "version": "0.48.1",
+  "main": "lib/main",
   "description": "PHP language support in Atom",
   "engines": {
     "atom": "*",
-    "node": "*"
+    "node": ">=12"
   },
   "repository": "https://github.com/pulsar-edit/pulsar",
   "license": "MIT"

packages/language-php/grammars/tree-sitter/tree-sitter-phpdoc.wasm

@@ -3005,7 +3005,7 @@ class LanguageLayer {
 
     this.tree = null;
     this.lastSyntaxTree = null;
-    this.temporaryTrees = null;
+    this.temporaryTrees = [];
 
     while (trees.length > 0) {
       let tree = trees.pop();
@@ -4049,7 +4049,7 @@ class NodeRangeSet {
   }
 
   getRanges(buffer) {
-    const previousRanges = this.previous && this.previous.getRanges(buffer);
+    const previousRanges = this.previous?.getRanges(buffer);
     let result = [];
 
     for (const node of this.nodes) {
@@ -4192,7 +4192,7 @@ class NodeRangeSet {
   // For injection points with `newlinesBetween` enabled, ensure that a
   // newline is included between each disjoint range.
   _ensureNewline(buffer, newRanges, startIndex, startPosition) {
-    const lastRange = newRanges[newRanges.length - 1];
+    const lastRange = last(newRanges);
     if (lastRange && lastRange.endPosition.row < startPosition.row) {
       newRanges.push({
         startPosition: new Point(
@@ -4289,7 +4289,7 @@ class RangeList {
   }
 
   insertOrdered(newRange) {
-    let index = this.ranges.findIndex((r, i) => {
+    let index = this.ranges.findIndex(r => {
       return r.start.compare(newRange.start) > 0;
     });
     this.ranges.splice(index, 0, newRange);