codespaces/.agents/designs/php-support.md

PHP Language Support for Belief Map

Context and motivation

The belief map previously supported Python and TypeScript/TSX. PHP projects (Laravel, Symfony, legacy codebases) had no graph representation, meaning agents querying the belief map would get zero results for .php files -- even in monorepos containing both TS and PHP services.

This design adds PHP as a first-class language alongside Python and TS, covering the same entity/edge model: classes, interfaces, traits, enums, imports, heritage, trait usage, and constructor dependency injection.

Implementation approach

tree-sitter-php is the primary parser, mirroring the TypeScript approach. A regex fallback (parse_php_regex) ensures PHP files remain visible even when tree-sitter-php is not installed, at the cost of reduced precision.

PSR-4 autoload resolution reads composer.json (autoload.psr-4 and autoload-dev.psr-4) to map FQCNs in use statements to file paths. This mirrors the TypeScript tsconfig.json path-alias resolver. When no composer.json is found, a walk-up heuristic converts namespace separators to path separators (like the Python resolver).

Constructor DI extraction mirrors the NestJS heuristic from the TS parser: typed __construct parameters with PascalCase type-hints are treated as service dependencies, producing calls-api edges. This works for Symfony autowiring and Laravel service container injection.

Trait usage (use TraitX; inside a class body) is a PHP-specific relationship with no direct equivalent in Python or TS. Traits are registered as abstract providers (like interfaces), and classes that use them get calls-api edges to the trait's defining module.

LSP enrichment uses phpactor language-server (JSON-RPC over stdio), the open-source PHP language server. It integrates with the existing LspClient infrastructure without changes to the transport layer.

Supported entities

PHP construct	Entity kind	sexp tag	Notes
class Foo	class	cls	abstract modifier, heritage
interface Foo	interface	ifc	auto-abstract
trait Foo	trait	trt	auto-abstract; usable via use
enum Foo (PHP 8.1)	enum	enm	backed enums (: string/int)
function foo()	function	fn	top-level functions only
#[Attribute]	decorator	:deco	PHP 8 attributes on classes/fns
class { use TraitX; }	trait usage	edge	calls-api to trait module
__construct(Foo $f)	DI dependency	edge	calls-api to service module

Edge types for PHP

Same model as other languages:

• imports -- resolved via PSR-4 from use statements
• calls-api -- implements/extends + trait usage + constructor DI
• data-flow -- to modules with validation (Symfony Validator, Laravel)
• refs -- entity-level cross-file references
• calls (LSP only) -- precise function-to-function call edges

Skipped / out of scope (v1)

• Blade templates (.blade.php) -- skipped like .d.ts
• Anonymous classes (new class { ... }) -- no name, no ID
• Trait conflict resolution (insteadof / as) -- edges on all used traits
• Dynamic imports (include, require) -- not tracked
• Runtime service discovery -- no container introspection
• use function / use const -- tracked as imports but not as entity refs

File discovery

• .php extension (excluding .blade.php)
• vendor/ and var/ directories are skipped (composer deps, Symfony cache)
• bootstrap/ and storage/ are NOT skipped (may contain real source)
• composer.json defines PSR-4 autoload rules and LSP project boundaries

Fallback behavior

When tree-sitter-php is not installed:

• parse_php_regex handles classes, interfaces, traits, enums (with heritage)
• No PHP 8 attribute extraction
• No constructor DI extraction
• Method extraction is best-effort (regex within a window)
• Trait usage inside class bodies IS detected (regex)
• The graph is still usable; precision improves when tree-sitter-php is added

When phpactor is not installed:

• --lsp mode skips PHP projects with a warning
• AST-based edges (imports, calls-api, refs) are unaffected
• Only calls (LSP call-hierarchy) edges are missing

Acceptance criteria

1. Given a Laravel/Symfony project with composer.json, when running build_belief_map.py, then (node ... php ...) facts are emitted for each .php file with correct PSR-4-resolved imports edges.

2. Given a class implementing an interface, when parsing, then a calls-api edge connects them.

3. Given a class using a trait (use TraitX;), when parsing, then a calls-api edge connects the class module to the trait module.

4. Given a class with constructor type-hints, when parsing, then calls-api edges connect the class to each dependency module.

5. Given PHP 8 attributes (#[AsService]), when parsing with tree-sitter-php, then the attribute name appears in :deco.

6. Given composer.json with autoload.psr-4, when resolving imports, then use App\Service\Foo resolves to src/Service/Foo.php.

7. Given tree-sitter-php is not installed, when parsing, then parse_php_regex produces visible entities (reduced precision).

8. belief_search.py analyze <php-class-id> returns boundary/deps/rdeps without modifications to the query engine.