seam-code 0.3.0__py3-none-any.whl

seam/indexer/graph_php.py

@@ -0,0 +1,914 @@
+"""PHP symbol, edge, and comment extraction from tree-sitter ASTs.
+
+LAYER: imports from graph_common (leaf) and graph_scope_infer_ext[2] (leaf) — never from graph.py.
+
+LAYERING:
+    graph_common    (leaf — no seam deps)
+         ↑
+    graph_php       (this file)
+         ↑
+    graph.py        (imports this module's public extractors at top level)
+
+WHY split from graph_ruby_php.py: graph_ruby_php.py reached the 1000-line
+limit; splitting each language into its own module keeps all files within
+limits and maintains the top-level-only import rule.
+
+All extractor functions follow the same contract:
+  - Accept a tree-sitter Node + filepath.
+  - Return a list — never raise, never return None.
+  - Edges carry confidence='INFERRED' by default (whole-index resolution
+    at read time handles EXTRACTED/AMBIGUOUS/INFERRED for cross-file edges).
+
+VERIFIED GRAMMAR FACTS (AST-dumped before coding):
+  PHP: class/function/method 'name' field (name node) + declaration_list/compound_statement
+    body; namespace_use_declaration → namespace_use_clause → qualified_name (last 'name');
+    namespace_use_group: the group { ... } is a 'namespace_use_group' child of the
+    namespace_use_declaration — must descend into it to find clause children;
+    aliased use clause: namespace_use_clause → qualified_name + 'as' + name (alias);
+    function_call_expression 'function' field = 'name' node (bare); comment node covers
+    //, #, and /* */ blocks.
+    PHP attributes: attribute_list appears as FIRST CHILD of the declaration node (not
+    prev_sibling) — the prev_sibling branch for attribute_list in phpdoc lookup is dead code.
+    enum_declaration body is 'enum_declaration_list' which may contain method_declaration nodes.
+"""
+
+import logging
+from pathlib import Path
+
+from tree_sitter import Node
+
+import seam.config as config
+
+# A3 Slice 5: PHP field-access edges + field symbols (sorts before graph_* imports).
+from seam.indexer.field_access_ext2 import (
+    collect_field_symbols_php,
+    extract_field_accesses_php,
+)
+
+# All shared types from the leaf module (no cycle — graph_common has no seam deps).
+from seam.indexer.graph_common import (
+    Comment,
+    Edge,
+    Symbol,
+    _block_comment_lines,
+    _find_enclosing_function,
+    _make_symbol,
+    _match_marker,
+    _text,
+)
+
+# Scope-inference: shared resolver from ext, PHP helpers from ext2.
+from seam.indexer.graph_scope_infer_ext import param_types_via_recorder, resolve_receiver_type_ext
+from seam.indexer.graph_scope_infer_ext2 import (
+    _PHP_SELF_NAMES,
+    collect_composition_types_php,
+    record_php_local_types,
+    record_php_param_types,
+    scan_class_fields_php,
+)
+
+# signatures_ext is the leaf enrichment module for Phase 9 languages.
+from seam.indexer.signatures_ext import _extract_php as _sig_php
+
+logger = logging.getLogger(__name__)
+
+# ── PHP doc-comment helpers ───────────────────────────────────────────────────
+
+
+def _php_phpdoc_comment(decl_node: Node) -> str | None:
+    """Capture a PHP phpdoc comment (/** ... */) immediately above the declaration.
+
+    Walks prev_sibling collecting comment nodes. Only block comments (/** */)
+    directly adjacent (no blank line) qualify as phpdoc. Line comments (// , #)
+    are also captured as leading doc if they're adjacent.
+
+    WHY no attribute_list prev_sibling branch: PHP attributes (#[...]) are the
+    FIRST CHILD of the declaration node itself, not a separate prev_sibling.
+    A prev_sibling attribute_list never appears in practice — the branch was dead
+    code and has been removed.
+
+    Returns the combined text, stripped of /* */ and * decorations, or None.
+    """
+    current = decl_node.prev_sibling
+
+    while current is not None:
+        if current.type == "comment":
+            raw = _text(current)
+            # Check adjacency: comment must end on the row just before decl start.
+            decl_start_row = decl_node.start_point[0]
+            comment_end_row = current.end_point[0]
+            if comment_end_row + 1 != decl_start_row:
+                break  # gap — not adjacent
+
+            if raw.startswith("/**"):
+                # phpdoc block: strip /** */ decorations and return.
+                return _php_strip_phpdoc(raw)
+            if raw.startswith("//") or raw.startswith("#"):
+                # Single line comment — use as doc if it's immediately above.
+                body = raw.lstrip("/").lstrip("#").strip()
+                return body if body else None
+            break  # unknown comment type
+        else:
+            break
+
+    return None
+
+
+def _php_strip_phpdoc(raw: str) -> str | None:
+    """Strip /** ... */ decorations from a PHP phpdoc block.
+
+    Returns clean text (lines joined with newline), or None if empty.
+    """
+    lines: list[str] = []
+    for line in raw.splitlines():
+        s = line.strip()
+        if s.startswith("/**"):
+            s = s[3:].strip()
+        elif s.startswith("*/"):
+            s = s[2:].strip()
+        elif s.startswith("*"):
+            s = s[1:].strip()
+        if s:
+            lines.append(s)
+    return "\n".join(lines) if lines else None
+
+
+# ── PHP symbol extraction ──────────────────────────────────────────────────────
+
+
+def _extract_symbols_php(root: Node, filepath: Path) -> list[Symbol]:
+    """Walk a PHP AST and extract class, interface, trait, enum, function, and method symbols.
+
+    Kind mapping (Phase 9 spec):
+        class_declaration       → class
+        interface_declaration   → interface
+        trait_declaration       → interface (named mixin — closest fit in closed vocabulary)
+        enum_declaration        → type
+        function_definition     → function  (top-level)
+        method_declaration (inside class/interface/trait/enum) → method ('Class.method')
+
+    PHP AST root is 'program' which contains php_tag, namespace_definition,
+    namespace_use_declaration, class_declaration, function_definition, etc.
+
+    NEVER raises — all exceptions caught and logged at DEBUG level.
+    """
+    symbols: list[Symbol] = []
+    file_str = str(filepath)
+
+    try:
+        _walk_php_symbols(root, file_str, symbols, class_name=None)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_extract_symbols_php: unexpected error for %s: %r", filepath, exc)
+
+    return symbols
+
+
+def _walk_php_symbols(
+    node: Node,
+    file_str: str,
+    symbols: list[Symbol],
+    class_name: str | None,
+) -> None:
+    """Recursive DFS walker for PHP symbol extraction.
+
+    class_name: enclosing class/interface/trait/enum name for method qualification.
+    """
+    ntype = node.type
+
+    if ntype in ("class_declaration", "interface_declaration", "trait_declaration"):
+        _handle_php_class_like(node, file_str, symbols, ntype)
+        return  # handled recursively inside
+
+    if ntype == "enum_declaration":
+        _handle_php_enum(node, file_str, symbols)
+        return  # handled recursively inside (recurses into enum body for methods)
+
+    if ntype == "function_definition" and class_name is None:
+        # Top-level function (not inside a class body).
+        _handle_php_function(node, file_str, symbols)
+        return
+
+    if ntype == "method_declaration" and class_name is not None:
+        _handle_php_method(node, file_str, symbols, class_name)
+        return
+
+    for child in node.children:
+        _walk_php_symbols(child, file_str, symbols, class_name)
+
+
+def _handle_php_class_like(
+    node: Node,
+    file_str: str,
+    symbols: list[Symbol],
+    ntype: str,
+) -> None:
+    """Emit a class/interface/trait symbol and recurse into its body."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        # Fallback: find first 'name' child
+        for child in node.children:
+            if child.type == "name":
+                name_node = child
+                break
+    if name_node is None:
+        return
+
+    name = _text(name_node)
+    doc = _php_phpdoc_comment(node)
+
+    if ntype == "class_declaration":
+        kind = "class"
+    elif ntype == "interface_declaration":
+        kind = "interface"
+    else:  # trait_declaration → interface per spec
+        kind = "interface"
+
+    fields = _sig_php(node, name, config.SEAM_MAX_SIGNATURE_LEN)
+    symbols.append(
+        _make_symbol(
+            name,
+            kind,
+            file_str,
+            node,
+            doc,
+            signature=fields["signature"],
+            decorators=fields["decorators"],
+            is_exported=fields["is_exported"],
+            visibility=fields["visibility"],
+            qualified_name=name,
+        )
+    )
+
+    # A3 Slice 5: emit field symbols for PHP property_declaration nodes (classes only).
+    if ntype == "class_declaration" and config.SEAM_FIELD_ACCESS_EDGES == "on":
+        for qual_name, field_line in collect_field_symbols_php(node, name):
+            symbols.append(Symbol(
+                name=qual_name,
+                kind="field",
+                file=file_str,
+                start_line=field_line,
+                end_line=field_line,
+                docstring=None,
+                signature=None,
+                decorators=[],
+                is_exported=None,
+                visibility=None,
+                qualified_name=qual_name,
+            ))
+
+    # Recurse into declaration_list body with this class name set.
+    for child in node.children:
+        _walk_php_symbols(child, file_str, symbols, class_name=name)
+
+
+def _handle_php_enum(node: Node, file_str: str, symbols: list[Symbol]) -> None:
+    """Emit a PHP enum symbol (kind='type') and recurse into its body for methods.
+
+    WHY recurse: PHP enums can contain method_declaration nodes inside their
+    enum_declaration_list body. These methods must be qualified 'EnumName.method'.
+    """
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        for child in node.children:
+            if child.type == "name":
+                name_node = child
+                break
+    if name_node is None:
+        return
+
+    name = _text(name_node)
+    doc = _php_phpdoc_comment(node)
+    fields = _sig_php(node, name, config.SEAM_MAX_SIGNATURE_LEN)
+    symbols.append(
+        _make_symbol(
+            name,
+            "type",
+            file_str,
+            node,
+            doc,
+            signature=fields["signature"],
+            decorators=fields["decorators"],
+            is_exported=fields["is_exported"],
+            visibility=fields["visibility"],
+            qualified_name=name,
+        )
+    )
+
+    # Recurse into enum body with enum name as class context so methods are qualified.
+    for child in node.children:
+        _walk_php_symbols(child, file_str, symbols, class_name=name)
+
+
+def _handle_php_function(node: Node, file_str: str, symbols: list[Symbol]) -> None:
+    """Emit a top-level PHP function symbol (kind='function')."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        for child in node.children:
+            if child.type == "name":
+                name_node = child
+                break
+    if name_node is None:
+        return
+
+    name = _text(name_node)
+    doc = _php_phpdoc_comment(node)
+    fields = _sig_php(node, name, config.SEAM_MAX_SIGNATURE_LEN)
+    symbols.append(
+        _make_symbol(
+            name,
+            "function",
+            file_str,
+            node,
+            doc,
+            signature=fields["signature"],
+            decorators=fields["decorators"],
+            is_exported=fields["is_exported"],
+            visibility=fields["visibility"],
+            qualified_name=name,
+        )
+    )
+
+
+def _handle_php_method(
+    node: Node,
+    file_str: str,
+    symbols: list[Symbol],
+    class_name: str,
+) -> None:
+    """Emit a PHP method_declaration symbol (kind='method', qualified 'Class.method')."""
+    name_node = node.child_by_field_name("name")
+    if name_node is None:
+        for child in node.children:
+            if child.type == "name":
+                name_node = child
+                break
+    if name_node is None:
+        return
+
+    name = _text(name_node)
+    qualified = f"{class_name}.{name}"
+    doc = _php_phpdoc_comment(node)
+    fields = _sig_php(node, qualified, config.SEAM_MAX_SIGNATURE_LEN)
+    symbols.append(
+        _make_symbol(
+            qualified,
+            "method",
+            file_str,
+            node,
+            doc,
+            signature=fields["signature"],
+            decorators=fields["decorators"],
+            is_exported=fields["is_exported"],
+            visibility=fields["visibility"],
+            qualified_name=qualified,
+        )
+    )
+
+
+# ── PHP edge extraction ────────────────────────────────────────────────────────
+
+
+def _extract_edges_php(root: Node, filepath: Path) -> list[Edge]:
+    """Extract import and call edges from a PHP AST.
+
+    Import heuristic:
+        namespace_use_declaration → namespace_use_clause → qualified_name
+        → last 'name' segment (e.g. 'use App\\Models\\User' → 'User')
+        namespace_use_group: descend into group to find clauses
+        Aliased use: 'use App\\Models\\User as U' → target = 'User' (real name)
+
+    Call heuristic:
+        function_call_expression where 'function' field is a 'name' node → bare call.
+        member_call_expression ($this->m, $obj->m) → capture receiver.
+        scoped_call_expression (ClassName::m) → capture class as receiver.
+
+    Tier B B5: when SEAM_TYPE_INFERENCE is on, member calls are resolved to
+    'Type.method' qualified targets using per-method scope (class property types +
+    param type hints + local `new ClassName()` assignments).
+
+    NEVER raises. Returns [] on any failure.
+    """
+    edges: list[Edge] = []
+    file_str = str(filepath)
+    file_stem = filepath.stem
+    infer = config.SEAM_TYPE_INFERENCE == "on"
+    composition_on = config.SEAM_COMPOSITION_EDGES == "on"
+    field_access_on = config.SEAM_FIELD_ACCESS_EDGES == "on"
+
+    try:
+        _walk_php_edges(
+            root, file_str, file_stem, edges, infer, composition_on, field_access_on,
+            None, {}, {}
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_extract_edges_php: unexpected error for %s: %r", filepath, exc)
+
+    return edges
+
+
+def _walk_php_edges(
+    node: Node,
+    file_str: str,
+    file_stem: str,
+    edges: list[Edge],
+    infer: bool,
+    composition_on: bool,
+    field_access_on: bool,
+    class_name: str | None,
+    class_fields: dict[str, str],
+    var_types: dict[str, str],
+) -> None:
+    """Recursive walker for PHP edge extraction with type-inference context threading.
+    composition_on gates holds edge emission (Slice #79).
+    field_access_on gates A3 Slice 5 reads/writes edge emission.
+    """
+    ntype = node.type
+
+    if ntype == "namespace_use_declaration":
+        _handle_php_use_declaration(node, file_str, file_stem, edges)
+        return  # no need to recurse into use declaration
+
+    if ntype == "class_declaration":
+        # Update class context and pre-scan property types.
+        new_class: str | None = None
+        cn = node.child_by_field_name("name")
+        if cn is not None:
+            new_class = _text(cn).strip() or None
+        # Slice #79: emit holds edges for PHP class properties + ctor params.
+        if composition_on and new_class:
+            _handle_php_class_holds(node, new_class, file_str, edges)
+        new_fields = scan_class_fields_php(node) if infer else {}
+        body = node.child_by_field_name("body")
+        if body is not None:
+            for child in body.children:
+                _walk_php_edges(
+                    child, file_str, file_stem, edges, infer, composition_on, field_access_on,
+                    new_class, new_fields, dict(new_fields)
+                )
+        return
+
+    if ntype == "method_declaration":
+        # New method scope: inherit class fields, bind type-hinted params.
+        new_types: dict[str, str] = dict(class_fields)
+        if infer:
+            record_php_param_types(node, new_types)
+        # 'uses' edges: method references plain user types as params. Config is read
+        # inline (not threaded) because _walk_php_edges recurses through many call sites.
+        if config.SEAM_PARAM_EDGES == "on" and class_name is not None:
+            _mn = node.child_by_field_name("name") or next(
+                (c for c in node.children if c.type == "name"), None
+            )
+            if _mn is not None:
+                _m = _text(_mn)
+                if _m:
+                    _src = f"{class_name}.{_m}"
+                    for ptype, pline in param_types_via_recorder(
+                        node, record_php_param_types, "php"
+                    ):
+                        edges.append(Edge(
+                            source=_src, target=ptype, kind="uses",
+                            file=file_str, line=pline, confidence="INFERRED", receiver=None,
+                        ))
+        body = node.child_by_field_name("body")
+        if body is not None:
+            # A3 Slice 5: emit reads/writes field-access edges for $this->field accesses.
+            if field_access_on and class_name is not None:
+                method_name_node = node.child_by_field_name("name")
+                if method_name_node is None:
+                    for c in node.children:
+                        if c.type == "name":
+                            method_name_node = c
+                            break
+                if method_name_node is not None:
+                    method_name = _text(method_name_node)
+                    if method_name:
+                        source_fn = f"{class_name}.{method_name}"
+                        for src, tgt, mode, line in extract_field_accesses_php(
+                            body, source_fn, class_name, new_types
+                        ):
+                            edges.append(Edge(
+                                source=src,
+                                target=tgt,
+                                kind=mode,
+                                file=file_str,
+                                line=line,
+                                confidence="INFERRED",
+                                receiver=None,
+                            ))
+            for child in body.children:
+                _walk_php_edges(
+                    child, file_str, file_stem, edges, infer, composition_on, field_access_on,
+                    class_name, class_fields, new_types
+                )
+        return
+
+    if infer and ntype == "expression_statement":
+        record_php_local_types(node, var_types)
+        # Still recurse to catch nested calls.
+
+    # Tier B B6: object_creation_expression (new Foo()) → instantiates edge.
+    # 'name' child = the constructed type (plain name or qualified_name for \NS\Foo).
+    # Dynamic new ($className()) has a variable_name child — skip gracefully.
+    if ntype == "object_creation_expression":
+        _handle_php_new_expression(node, file_str, edges)
+        # Recurse to catch nested news in constructor arguments.
+        for child in node.children:
+            _walk_php_edges(
+                child, file_str, file_stem, edges, infer, composition_on, field_access_on,
+                class_name, class_fields, var_types
+            )
+        return  # already recursed above
+
+    if ntype == "function_call_expression":
+        _handle_php_call(node, file_str, file_stem, edges)
+        # Still recurse — calls can be nested inside argument lists
+
+    elif ntype in ("member_call_expression", "nullsafe_member_call_expression"):
+        # Tier B B2 + B5: $obj->method() — capture receiver and try to qualify.
+        _handle_php_member_call_infer(node, file_str, edges, infer, class_name, var_types)
+        # Still recurse for nested calls
+
+    elif ntype == "scoped_call_expression":
+        # Tier B B2: ClassName::method() — capture class name as receiver.
+        _handle_php_scoped_call(node, file_str, edges)
+        # Still recurse for nested calls
+
+    for child in node.children:
+        _walk_php_edges(
+            child, file_str, file_stem, edges, infer, composition_on, field_access_on,
+            class_name, class_fields, var_types
+        )
+
+
+def _handle_php_new_expression(
+    node: Node,
+    file_str: str,
+    edges: list[Edge],
+) -> None:
+    """Emit an instantiates edge from a PHP object_creation_expression node.
+
+    Tier B B6: new Foo() → kind='instantiates', target='Foo'.
+    For namespaced new (new \\NS\\Bar()) the last segment 'Bar' is the target.
+    Dynamic new ($className()) uses variable_name child — skipped gracefully (no edge).
+    Never raises.
+    """
+    try:
+        source = _find_enclosing_function(node, "php")
+        if source is None:
+            return
+        # Children of object_creation_expression: [new, name_node, arguments_node]
+        # name_node can be 'name' (plain), 'qualified_name' (namespaced), or
+        # 'variable_name' (dynamic — skip).
+        for child in node.children:
+            if child.type == "name":
+                type_name = _text(child)
+                if type_name:
+                    edges.append(Edge(
+                        source=source,
+                        target=type_name,
+                        kind="instantiates",
+                        file=file_str,
+                        line=node.start_point[0] + 1,
+                        confidence="INFERRED",
+                        receiver=None,
+                    ))
+                return
+            if child.type == "qualified_name":
+                # \NS\Bar → last 'name' child is 'Bar'
+                last_name: str | None = None
+                for gc in child.children:
+                    if gc.type == "name":
+                        last_name = _text(gc)
+                if last_name:
+                    edges.append(Edge(
+                        source=source,
+                        target=last_name,
+                        kind="instantiates",
+                        file=file_str,
+                        line=node.start_point[0] + 1,
+                        confidence="INFERRED",
+                        receiver=None,
+                    ))
+                return
+            # variable_name or other dynamic class — skip gracefully (no edge).
+            if child.type == "variable_name":
+                return
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _handle_php_use_declaration(
+    node: Node,
+    file_str: str,
+    file_stem: str,
+    edges: list[Edge],
+) -> None:
+    """Extract import edges from a PHP namespace_use_declaration node.
+
+    Handles three forms:
+      use App\\Models\\User;          → target = 'User'
+      use App\\Models\\User as U;     → target = 'User' (real exported name, not alias)
+      use App\\{Foo, Bar};            → targets = ['Foo', 'Bar'] (grouped use)
+
+    WHY grouped use: namespace_use_group is a direct child of namespace_use_declaration.
+    The group contains namespace_use_clause children — must descend into it.
+    """
+    line = node.start_point[0] + 1
+    for child in node.named_children:
+        if child.type == "namespace_use_clause":
+            target = _php_use_clause_exported_name(child)
+            if target:
+                edges.append(
+                    Edge(
+                        source=file_stem,
+                        target=target,
+                        kind="import",
+                        file=file_str,
+                        line=line,
+                        confidence="INFERRED",
+                                            receiver=None,
+                                        )
+                )
+        elif child.type == "namespace_use_group":
+            # Grouped use: use App\{Foo, Bar} — descend into the group's clauses.
+            for clause in child.named_children:
+                if clause.type == "namespace_use_clause":
+                    target = _php_use_clause_exported_name(clause)
+                    if target:
+                        edges.append(
+                            Edge(
+                                source=file_stem,
+                                target=target,
+                                kind="import",
+                                file=file_str,
+                                line=line,
+                                confidence="INFERRED",
+                                                            receiver=None,
+                                                        )
+                        )
+
+
+def _php_use_clause_exported_name(clause_node: Node) -> str | None:
+    """Extract the real exported name from a PHP namespace_use_clause.
+
+    For a plain clause (use App\\Models\\User): returns 'User' (last name segment).
+    For an aliased clause (use App\\Models\\User as U): returns 'User' (the real
+    exported name — consistent with TS/Rust alias convention where the import edge
+    targets the real symbol, not the local alias).
+
+    namespace_use_clause → qualified_name → last 'name' child
+                         → (optional) 'as' + name (alias — ignored for edge target)
+    """
+    for child in clause_node.named_children:
+        if child.type == "qualified_name":
+            # Walk the qualified_name to find the last 'name' child.
+            last_name = None
+            for qchild in child.children:
+                if qchild.type == "name":
+                    last_name = _text(qchild)
+            return last_name
+        if child.type == "name":
+            # Bare name (e.g. from grouped use: `use App\{Foo, Bar}`)
+            return _text(child)
+    return None
+
+
+def _handle_php_call(
+    node: Node,
+    file_str: str,
+    file_stem: str,
+    edges: list[Edge],
+) -> None:
+    """Emit a call edge from a PHP function_call_expression node.
+
+    function_call_expression: 'function' field is a 'name' node → bare call.
+    Skip if function field is a variable ($fn()) or complex expression.
+    """
+    func_node = node.child_by_field_name("function")
+    if func_node is None or func_node.type != "name":
+        return  # variable call or complex expression — skip
+
+    target = _text(func_node)
+    source = _find_enclosing_function(node, "php")
+    if source is not None:
+        edges.append(
+            Edge(
+                source=source,
+                target=target,
+                kind="call",
+                file=file_str,
+                line=node.start_point[0] + 1,
+                confidence="INFERRED",
+                receiver=None,
+            )
+        )
+
+
+def _handle_php_member_call(
+    node: Node,
+    file_str: str,
+    edges: list[Edge],
+) -> None:
+    """Emit a call edge from a PHP member_call_expression node (Tier B B2).
+
+    Handles $obj->method() and $obj?->method() (nullsafe).
+    Captures the receiver text ($obj, $this, etc.) and the method name.
+    Gracefully skips when the name field is absent or not a plain 'name' node.
+    Never raises.
+    """
+    try:
+        # object field = receiver expression ($obj, $this, variable_name, etc.)
+        obj_node = node.child_by_field_name("object")
+        # name field = method name (a 'name' node in the PHP grammar)
+        name_node = node.child_by_field_name("name")
+        if name_node is None or name_node.type != "name":
+            return  # complex dynamic dispatch — skip gracefully
+
+        target = _text(name_node)
+        recv_text: str | None = _text(obj_node) if obj_node is not None else None
+        source = _find_enclosing_function(node, "php")
+        if source is not None:
+            edges.append(
+                Edge(
+                    source=source,
+                    target=target,
+                    kind="call",
+                    file=file_str,
+                    line=node.start_point[0] + 1,
+                    confidence="INFERRED",
+                    receiver=recv_text,
+                )
+            )
+    except Exception:  # noqa: BLE001
+        pass  # never raise from the extractor
+
+
+def _handle_php_member_call_infer(
+    node: Node,
+    file_str: str,
+    edges: list[Edge],
+    infer: bool,
+    class_name: str | None,
+    var_types: dict[str, str],
+) -> None:
+    """Emit a call edge from PHP member_call_expression with optional type inference (B5).
+
+    When infer=True, resolves $obj→method() receiver to 'Type.method' using var_types.
+    Fallback: emits the bare method name with raw receiver (same as B2 behavior).
+    Never raises.
+    """
+    try:
+        obj_node = node.child_by_field_name("object")
+        name_node = node.child_by_field_name("name")
+        if name_node is None or name_node.type != "name":
+            return
+
+        method_name = _text(name_node)
+        recv_text: str | None = _text(obj_node) if obj_node is not None else None
+
+        # B5: resolve receiver to type → qualify the target.
+        final_target = method_name
+        if infer and recv_text is not None:
+            resolved_type = resolve_receiver_type_ext(
+                recv_text, class_name, var_types, _PHP_SELF_NAMES
+            )
+            if resolved_type:
+                final_target = f"{resolved_type}.{method_name}"
+
+        source = _find_enclosing_function(node, "php")
+        if source is not None:
+            edges.append(
+                Edge(
+                    source=source,
+                    target=final_target,
+                    kind="call",
+                    file=file_str,
+                    line=node.start_point[0] + 1,
+                    confidence="INFERRED",
+                    receiver=recv_text,
+                )
+            )
+    except Exception:  # noqa: BLE001
+        pass  # never raise from the extractor
+
+
+def _handle_php_scoped_call(
+    node: Node,
+    file_str: str,
+    edges: list[Edge],
+) -> None:
+    """Emit a call edge from a PHP scoped_call_expression node (Tier B B2 + B5).
+
+    Handles ClassName::method() (static dispatch).
+    Because the class name is literally present in the AST (no scope lookup needed),
+    the target is immediately qualified as 'ClassName.method' (B5 intent: consistent
+    with Java method_invocation and C# invocation_expression qualification).
+    The class_name is also stored as receiver for provenance.
+    Gracefully skips when nodes are absent or not a plain 'name'. Never raises.
+    """
+    try:
+        # scoped_call_expression children: name(class) :: name(method) arguments
+        # The grammar does NOT use named fields — walk children directly.
+        names = [c for c in node.children if c.type == "name"]
+        if len(names) < 2:
+            return  # unexpected shape — degrade gracefully
+        class_name = _text(names[0])
+        method_name = _text(names[1])
+        if not class_name or not method_name:
+            return
+
+        source = _find_enclosing_function(node, "php")
+        if source is not None:
+            # B5: qualify the target directly — the class is explicit in the AST
+            # (conservatism contract satisfied: type is stated, not inferred from scope).
+            qualified_target = f"{class_name}.{method_name}"
+            edges.append(
+                Edge(
+                    source=source,
+                    target=qualified_target,
+                    kind="call",
+                    file=file_str,
+                    line=node.start_point[0] + 1,
+                    confidence="INFERRED",
+                    receiver=class_name,
+                )
+            )
+    except Exception:  # noqa: BLE001
+        pass  # never raise from the extractor
+
+
+def _handle_php_class_holds(
+    class_node: Node, class_name: str, file_str: str, edges: list[Edge]
+) -> None:
+    """Emit holds edges for each typed property/ctor-param in a PHP class.
+
+    Delegates to collect_composition_types_php for (held_type, line) pairs and
+    emits one Edge per unique pair. Never raises (backstop try/except).
+    """
+    try:
+        for held_type, held_line in collect_composition_types_php(class_node):
+            edges.append(
+                Edge(
+                    source=class_name,
+                    target=held_type,
+                    kind="holds",
+                    file=file_str,
+                    line=held_line,
+                    confidence="INFERRED",
+                    receiver=None,
+                )
+            )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_handle_php_class_holds: failed: %r", exc)
+
+
+# ── PHP comment extraction ─────────────────────────────────────────────────────
+
+
+def _extract_comments_php(root: Node, filepath: Path) -> list[Comment]:
+    """Walk a PHP AST and extract semantic comment markers (WHY/HACK/NOTE/TODO/FIXME).
+
+    PHP comment node types:
+        comment — covers // line, # line, and /* */ /* */ /** */ block comments.
+    All variants are scanned; phpdoc blocks use _block_comment_lines for multi-line.
+
+    NEVER raises. Returns [] on any failure.
+    """
+    comments: list[Comment] = []
+
+    try:
+        _walk_php_comments(root, comments)
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("_extract_comments_php: unexpected error: %r", exc)
+
+    return comments
+
+
+def _walk_php_comments(node: Node, comments: list[Comment]) -> None:
+    """Recursive walker for PHP comment nodes."""
+    if node.type == "comment":
+        raw = _text(node)
+        base_row = node.start_point[0] + 1
+
+        if raw.startswith("/*"):
+            # Block comment (/** */ or /* */) — scan each line.
+            for offset, body in _block_comment_lines(raw):
+                result = _match_marker(body)
+                if result is not None:
+                    marker, text = result
+                    comments.append(Comment(marker=marker, text=text, line=base_row + offset))
+        elif raw.startswith("//"):
+            body = raw[2:].strip()
+            result = _match_marker(body)
+            if result is not None:
+                marker, text = result
+                comments.append(Comment(marker=marker, text=text, line=base_row))
+        elif raw.startswith("#"):
+            body = raw[1:].strip()
+            result = _match_marker(body)
+            if result is not None:
+                marker, text = result
+                comments.append(Comment(marker=marker, text=text, line=base_row))
+
+    for child in node.children:
+        _walk_php_comments(child, comments)