feat: asymmetric visibility support (PHP 8.4+)

Add parsing support for PHP 8.4 asymmetric visibility modifiers on class
properties and constructor promotion parameters.

- Parse `public private(set)`, `protected private(set)`, `private(set)`,
  `protected(set)` modifiers in class body via `read_member_flags`
- Parse asymmetric visibility on constructor promoted parameters via
  `read_promoted` in function.js
- Add `visibilitySet` field to `Declaration` and `PropertyStatement` AST nodes
- Add `flagsSet` field to `Parameter` AST node
- Update `types.d.ts` with new fields
- All (set) parsing is gated behind `version >= 804`

Co-authored-by: Thomas Genin <664857+genintho@users.noreply.github.com>

Author: jorgsowa

src/ast/declaration.js

@@ -13,6 +13,12 @@ const IS_PUBLIC = "public";
 const IS_PROTECTED = "protected";
 const IS_PRIVATE = "private";
 
+const SET_VISIBILITY_MAP = {
+  0: IS_PUBLIC,
+  1: IS_PROTECTED,
+  2: IS_PRIVATE,
+};
+
 /**
  * A declaration statement (function, class, interface...)
  * @constructor Declaration
@@ -54,6 +60,10 @@ Declaration.prototype.parseFlags = function (flags) {
       this.visibility = IS_PRIVATE;
     }
     this.isStatic = flags[1] === 1;
+    this.visibilitySet =
+      flags[4] !== undefined && flags[4] !== -1
+        ? SET_VISIBILITY_MAP[flags[4]]
+        : null;
   }
 };
 

src/ast/parameter.js

@@ -34,6 +34,7 @@ const KIND = "parameter";
  * @property {AttrGroup[]} attrGroups
  * @property {MODIFIER_PUBLIC|MODIFIER_PROTECTED|MODIFIER_PRIVATE} flags
  * @property {PropertyHook[]} hooks
+ * @property {MODIFIER_PUBLIC|MODIFIER_PROTECTED|MODIFIER_PRIVATE} flagsSet
  */
 module.exports = Declaration.extends(
   KIND,
@@ -47,6 +48,7 @@ module.exports = Declaration.extends(
     nullable,
     flags,
     hooks,
+    flagsSet,
     docs,
     location,
   ) {
@@ -59,6 +61,7 @@ module.exports = Declaration.extends(
     this.nullable = nullable;
     this.flags = flags || 0;
     this.hooks = hooks || [];
+    this.flagsSet = flagsSet || 0;
     this.attrGroups = [];
   },
 );

src/ast/propertystatement.js

@@ -13,13 +13,20 @@ const IS_PUBLIC = "public";
 const IS_PROTECTED = "protected";
 const IS_PRIVATE = "private";
 
+const SET_VISIBILITY_MAP = {
+  0: IS_PUBLIC,
+  1: IS_PROTECTED,
+  2: IS_PRIVATE,
+};
+
 /**
  * Declares a properties into the current scope
  * @constructor PropertyStatement
  * @memberOf module:php-parser
  * @extends {Statement}
  * @property {Property[]} properties
  * @property {string|null} visibility
+ * @property {string|null} visibilitySet
  * @property {boolean} isStatic
  * @property {boolean} isAbstract
  * @property {boolean} isFinal
@@ -56,6 +63,10 @@ PropertyStatement.prototype.parseFlags = function (flags) {
   this.isStatic = flags[1] === 1;
   this.isAbstract = flags[2] === 1;
   this.isFinal = flags[2] === 2;
+  this.visibilitySet =
+    flags[4] !== undefined && flags[4] !== -1
+      ? SET_VISIBILITY_MAP[flags[4]]
+      : null;
 };
 
 module.exports = PropertyStatement;

src/parser/class.js

@@ -388,69 +388,94 @@ module.exports = {
   /*
    * Read member flags
    * @return array
-   *  1st index : 0 => public, 1 => protected, 2 => private
+   *  1st index : -1 => no visibility, 0 => public, 1 => protected, 2 => private
    *  2nd index : 0 => instance member, 1 => static member
    *  3rd index : 0 => normal, 1 => abstract member, 2 => final member
+   *  4th index : 0 => no readonly, 1 => readonly
+   *  5th index : -1 => no set modifier, 0 => public(set), 1 => protected(set), 2 => private(set)
    */
   read_member_flags(asInterface) {
-    const result = [-1, -1, -1, -1];
-    if (this.is("T_MEMBER_FLAGS")) {
-      let idx = 0,
-        val = 0;
-      do {
-        switch (this.token) {
-          case this.tok.T_PUBLIC:
-            idx = 0;
-            val = 0;
-            break;
-          case this.tok.T_PROTECTED:
-            idx = 0;
-            val = 1;
-            break;
-          case this.tok.T_PRIVATE:
-            idx = 0;
-            val = 2;
-            break;
-          case this.tok.T_STATIC:
-            idx = 1;
-            val = 1;
-            break;
-          case this.tok.T_ABSTRACT:
-            idx = 2;
-            val = 1;
-            break;
-          case this.tok.T_FINAL:
-            idx = 2;
-            val = 2;
-            break;
-          case this.tok.T_READ_ONLY:
-            idx = 3;
-            val = 1;
-            break;
-        }
-        if (asInterface) {
-          if (idx === 0 && val === 2) {
+    const result = [-1, 0, 0, 0, -1];
+    const seen = new Set();
+    while (this.is("T_MEMBER_FLAGS")) {
+      let idx = -1,
+        val = -1;
+      switch (this.token) {
+        case this.tok.T_PUBLIC:
+        case this.tok.T_PROTECTED:
+        case this.tok.T_PRIVATE: {
+          idx = 0;
+          val =
+            this.token === this.tok.T_PUBLIC
+              ? 0
+              : this.token === this.tok.T_PROTECTED
+                ? 1
+                : 2;
+          if (asInterface && val === 2) {
             // an interface can't be private
             this.expect([this.tok.T_PUBLIC, this.tok.T_PROTECTED]);
             val = -1;
-          } else if (idx === 2 && val === 1) {
-            // an interface cant be abstract
+          }
+          this.next(); // consume the visibility keyword
+          if (this.version >= 804 && this.token === "(") {
+            // visibility(set) modifier: e.g. private(set)
+            this.next(); // consume '('
+            if (this.token !== this.tok.T_STRING || this.text() !== "set") {
+              this.error("set");
+            } else {
+              this.next(); // consume 'set'
+            }
+            if (this.expect(")")) {
+              this.next(); // consume ')'
+            }
+            if (seen.has(4)) {
+              this.error(); // set modifier already defined
+            } else if (val !== -1) {
+              seen.add(4);
+              result[4] = val;
+            }
+            continue;
+          }
+          if (seen.has(idx)) {
             this.error();
-            val = -1;
+          } else if (val !== -1) {
+            seen.add(idx);
+            result[idx] = val;
           }
+          continue;
         }
-        if (result[idx] !== -1) {
-          // already defined flag
-          this.error();
-        } else if (val !== -1) {
-          result[idx] = val;
-        }
-      } while (this.next().is("T_MEMBER_FLAGS"));
+        case this.tok.T_STATIC:
+          idx = 1;
+          val = 1;
+          break;
+        case this.tok.T_ABSTRACT:
+          idx = 2;
+          val = 1;
+          break;
+        case this.tok.T_FINAL:
+          idx = 2;
+          val = 2;
+          break;
+        case this.tok.T_READ_ONLY:
+          idx = 3;
+          val = 1;
+          break;
+      }
+      if (asInterface && idx === 2 && val === 1) {
+        // an interface can't be abstract
+        this.error();
+        val = -1;
+      }
+      if (seen.has(idx)) {
+        // already defined flag
+        this.error();
+      } else if (val !== -1) {
+        seen.add(idx);
+        result[idx] = val;
+      }
+      this.next();
     }
 
-    if (result[1] === -1) result[1] = 0;
-    if (result[2] === -1) result[2] = 0;
-    if (result[3] === -1) result[3] = 0;
     return result;
   },
 

src/parser/function.js

@@ -268,7 +268,7 @@ module.exports = {
       }
     }
 
-    const flags = this.read_promoted();
+    const [flags, flagsSet] = this.read_promoted();
 
     if (
       !readonly &&
@@ -320,6 +320,7 @@ module.exports = {
       nullable,
       flags,
       hooks,
+      flagsSet,
     );
     if (attrs) result.attrGroups = attrs;
     return result;
@@ -387,17 +388,67 @@ module.exports = {
     const MODIFIER_PUBLIC = 1;
     const MODIFIER_PROTECTED = 2;
     const MODIFIER_PRIVATE = 4;
+
+    let firstModifier;
     if (this.token === this.tok.T_PUBLIC) {
       this.next();
-      return MODIFIER_PUBLIC;
+      firstModifier = MODIFIER_PUBLIC;
     } else if (this.token === this.tok.T_PROTECTED) {
       this.next();
-      return MODIFIER_PROTECTED;
+      firstModifier = MODIFIER_PROTECTED;
     } else if (this.token === this.tok.T_PRIVATE) {
       this.next();
-      return MODIFIER_PRIVATE;
+      firstModifier = MODIFIER_PRIVATE;
+    } else {
+      return [0, 0];
+    }
+
+    // PHP 8.4+ asymmetric visibility
+    if (this.version >= 804) {
+      if (this.token === "(") {
+        // shorthand: visibility(set) — firstModifier is the set modifier, read visibility is implicit
+        this.next(); // consume '('
+        if (this.token !== this.tok.T_STRING || this.text() !== "set") {
+          this.error("set");
+        } else {
+          this.next(); // consume 'set'
+        }
+        if (this.expect(")")) {
+          this.next(); // consume ')'
+        }
+        return [0, firstModifier]; // no explicit read visibility, set = firstModifier
+      }
+
+      // Check for explicit form: readVisibility setVisibility(set)
+      let setModifier = 0;
+      if (this.token === this.tok.T_PUBLIC) {
+        this.next();
+        setModifier = MODIFIER_PUBLIC;
+      } else if (this.token === this.tok.T_PROTECTED) {
+        this.next();
+        setModifier = MODIFIER_PROTECTED;
+      } else if (this.token === this.tok.T_PRIVATE) {
+        this.next();
+        setModifier = MODIFIER_PRIVATE;
+      }
+
+      if (setModifier > 0) {
+        if (this.expect("(")) {
+          this.next(); // consume '('
+        }
+        if (this.token !== this.tok.T_STRING || this.text() !== "set") {
+          this.error("set");
+        } else {
+          this.next(); // consume 'set'
+        }
+        if (this.expect(")")) {
+          this.next(); // consume ')'
+        }
+        return [firstModifier, setModifier];
+      }
     }
-    return 0;
+
+    return [firstModifier, 0];
   },
   /*
    * Reads a list of arguments

test/snapshot/__snapshots__/acid.test.js.snap

@@ -1033,6 +1033,7 @@ Program {
                 },
               ],
               "visibility": "protected",
+              "visibilitySet": null,
             },
             Method {
               "arguments": [],
@@ -1606,6 +1607,7 @@ Program {
               "nullable": false,
               "type": null,
               "visibility": "public",
+              "visibilitySet": null,
             },
           ],
           "extends": null,
@@ -1774,6 +1776,7 @@ Program {
                 "raw": "bool",
               },
               "visibility": "public",
+              "visibilitySet": null,
             },
             Method {
               "arguments": [],
@@ -1835,6 +1838,7 @@ Program {
                 "raw": "bool",
               },
               "visibility": "protected",
+              "visibilitySet": null,
             },
             Method {
               "arguments": [],
@@ -1896,6 +1900,7 @@ Program {
                 "raw": "bool",
               },
               "visibility": "protected",
+              "visibilitySet": null,
             },
           ],
           "extends": [
@@ -2177,6 +2182,7 @@ Program {
                   "attrGroups": [],
                   "byref": false,
                   "flags": 0,
+                  "flagsSet": 0,
                   "hooks": [],
                   "kind": "parameter",
                   "loc": Location {
@@ -2889,6 +2895,7 @@ Program {
                 "raw": "string",
               },
               "visibility": "public",
+              "visibilitySet": null,
             },
             Method {
               "arguments": [],
@@ -2986,6 +2993,7 @@ Program {
               "nullable": false,
               "type": null,
               "visibility": "private",
+              "visibilitySet": null,
             },
           ],
           "kind": "trait",
@@ -4140,6 +4148,7 @@ next:
                   "attrGroups": [],
                   "byref": false,
                   "flags": 0,
+                  "flagsSet": 0,
                   "hooks": [],
                   "kind": "parameter",
                   "loc": Location {
@@ -5336,6 +5345,7 @@ next:
                                               "nullable": false,
                                               "type": null,
                                               "visibility": "",
+                                              "visibilitySet": null,
                                             },
                                           ],
                                           "extends": Name {