@sylphx/synth-php

PHP parser using Synth's universal AST. Conversion layer over tree-sitter-php.

Features

- ✅ Strategic Dependency - Uses tree-sitter-php (battle-tested PHP parser)
- 🚀 Full PHP Support - PHP 7 and PHP 8+ features
- 🎯 Universal AST - Converts tree-sitter CST to Synth's language-agnostic format
- 🔌 Plugin System - Transform AST with sync/async plugins
- 📦 Battle-Tested - tree-sitter powers VS Code, Atom, and many other editors

Installation

``bash
npm install @sylphx/synth-php
`

Usage

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = function greet($name) {
return "Hello, " . $name . "!";
}

echo greet("World");
?>

const tree = parse(php)
console.log(tree.nodes[tree.root])
`

$3

`typescript
import { PhpParser, createParser, parse, parseAsync } from '@sylphx/synth-php'

// Standalone function (recommended)
const tree = parse('')

// Async parsing (for plugins)
const tree = await parseAsync('')

// Class instance
const parser = new PhpParser()
const tree = parser.parse('')

// Factory function
const parser = createParser()
const tree = parser.parse('')
`

$3

`typescript
import { parse, parseAsync, type Tree } from '@sylphx/synth-php'

// Sync plugin
const myPlugin = {
name: 'my-plugin',
transform(tree: Tree) {
// Modify tree
return tree
}
}

const tree = parse('', { plugins: [myPlugin] })

// Async plugin
const asyncPlugin = {
name: 'async-plugin',
async transform(tree: Tree) {
// Async modifications
return tree
}
}

const tree = await parseAsync('', { plugins: [asyncPlugin] })
`

AST Structure

The parser generates a universal Synth AST by converting tree-sitter's concrete syntax tree. Each node includes:

$3

`typescript
{
type: 'FunctionDefinition', // Mapped from tree-sitter type
parent: NodeId,
children: [NodeId],
span: {
start: { offset, line, column },
end: { offset, line, column }
},
data: {
text: 'function greet()...', // Original source text
isNamed: true, // tree-sitter named node
originalType: 'function_definition' // Original tree-sitter type
}
}
`

Supported PHP Features

$3


- ✅ Variables ($name, $value)
- ✅ Superglobals ($_GET, $_POST, $_SESSION, etc.)
- ✅ Variable variables ($$name)
- ✅ Static variables
- ✅ Global variables

$3

- ✅ Strings (single '...', double "...", heredoc, nowdoc)
- ✅ Integers (decimal, hex, octal, binary)
- ✅ Floats (3.14, 1.5e10)
- ✅ Booleans (true, false)
- ✅ null
- ✅ Arrays (array(...), [...])
- ✅ Objects
- ✅ Resources
- ✅ Callable types

$3

- ✅ if/elseif/else statements
- ✅ for loops
- ✅ foreach loops (with key/value)
- ✅ while loops
- ✅ do-while loops
- ✅ switch/case statements
- ✅ match expressions (PHP 8+)
- ✅ try/catch/finally
- ✅ break, continue, return
- ✅ goto statements

$3

- ✅ Function definitions (function name())
- ✅ Parameters and default values
- ✅ Type hints (int, string, array, classes)
- ✅ Return type declarations (: int, : string)
- ✅ Variadic functions (...$args)
- ✅ Anonymous functions (closures)
- ✅ Arrow functions (fn() => ...) (PHP 7.4+)
- ✅ use keyword for closures

$3

- ✅ Class declarations (class MyClass)
- ✅ Constructors (__construct)
- ✅ Properties (public, private, protected, static)
- ✅ Methods (public, private, protected, static, abstract, final)
- ✅ Constants (const NAME = value)
- ✅ Visibility modifiers
- ✅ Constructor property promotion (PHP 8+)

$3

- ✅ extends keyword
- ✅ implements keyword (interfaces)
- ✅ Abstract classes and methods
- ✅ Final classes and methods
- ✅ Interfaces
- ✅ Traits (trait, use)

$3

- ✅ Named arguments
- ✅ Match expressions
- ✅ Nullsafe operator (?->)
- ✅ Constructor property promotion
- ✅ Union types (int|string)
- ✅ Mixed type
- ✅ Attributes (#[...])
- ✅ Enumerations (enum)
- ✅ Readonly properties

$3

- ✅ Arithmetic (+, -, , /, %, *)
- ✅ Comparison (==, ===, !=, !==, <, >, <=, >=, <=>)
- ✅ Logical (&&, ||, !, and, or, xor)
- ✅ String (. concatenation)
- ✅ Assignment (=, +=, -=, .=, etc.)
- ✅ Ternary (? :)
- ✅ Null coalescing (??) (PHP 7+)
- ✅ Instanceof operator
- ✅ Error suppression (@)

$3

- ✅ Namespace declarations (namespace App\Models;)
- ✅ use statements
- ✅ Aliased imports (use Foo as Bar)
- ✅ Grouped imports

$3

- ✅ Line comments (// and #)
- ✅ Block comments (/ ... /)
- ✅ PHPDoc comments (/* ... /)

Examples

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = class Calculator {
public function add($a, $b) {
return $a + $b;
}

public function subtract($a, $b) {
return $a - $b;
}
}
?>

const tree = parse(php)

// Find class declaration
const classNode = tree.nodes.find(n => n.type === 'ClassDeclaration')
console.log(classNode)

// Find method declarations
const methodNodes = tree.nodes.filter(n => n.type.includes('Method'))
console.log(methodNodes)
`

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = function add(int $a, int $b): int {
return $a + $b;
}
?>

const tree = parse(php)

// Find function with type declarations
const funcNode = tree.nodes.find(n => n.type === 'FunctionDefinition')
console.log(funcNode)
`

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = $numbers = [1, 2, 3, 4, 5];
$squared = array_map(fn($n) => $n * $n, $numbers);
?>

const tree = parse(php)

// Find arrow function
const arrowNode = tree.nodes.find(n => n.type.includes('Arrow'))
console.log(arrowNode)
`

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = $result = match($status) {
'success' => 'Operation successful',
'error' => 'An error occurred',
default => 'Unknown status'
};
?>

const tree = parse(php)

// Find match expression
const matchNode = tree.nodes.find(n => n.type.includes('Match'))
console.log(matchNode)
`

$3

`typescript
import { parse } from '@sylphx/synth-php'

const php = enum Status: string {
case Pending = 'pending';
case Approved = 'approved';
case Rejected = 'rejected';
}
?>

const tree = parse(php)

// Find enum declaration
const enumNode = tree.nodes.find(n => n.type.includes('Enum'))
console.log(enumNode)
`

$3

`typescript
import { parse, type Tree, type Node } from '@sylphx/synth-php'

// Plugin to count functions
const functionCounterPlugin = {
name: 'function-counter',
transform(tree: Tree) {
const functions = tree.nodes.filter(n => n.type === 'FunctionDefinition')
console.log(Found ${functions.length} functions)
return tree
}
}

const php = function foo() {}
function bar() {}
function baz() {}
?>

const tree = parse(php, { plugins: [functionCounterPlugin] })
// Output: Found 3 functions
`

Use Cases

- Code Analysis - Analyze PHP codebases for patterns, complexity, dependencies
- Linting - Build custom linters for PHP code
- Documentation - Generate API docs from PHPDoc comments
- Refactoring - Automate code transformations
- Metrics - Calculate code metrics (cyclomatic complexity, LOC, etc.)
- IDE Features - Power autocomplete, go-to-definition, find references
- Code Generation - Generate PHP code from templates
- Migration Tools - Automate PHP version upgrades (5 → 7 → 8)
- Security Analysis - Detect security vulnerabilities

Performance

- Fast Parsing - tree-sitter is highly optimized
- Incremental Parsing - tree-sitter supports incremental re-parsing
- Low Memory - Synth's arena-based storage is memory efficient
- O(1) Node Access - NodeId-based access is constant time

Architecture

`
PHP Source Code
↓
tree-sitter-php (parse)
↓
tree-sitter CST
↓
@sylphx/synth-php (convert)
↓
Synth Universal AST
↓
Plugins (transform)
↓
Final AST
`

Why tree-sitter-php?

- ✅ Battle-Tested - Powers VS Code, Atom, Neovim, and GitHub's code navigation
- ✅ Complete - Supports PHP 7 and PHP 8+ including latest features
- ✅ Fast - Written in C, highly optimized
- ✅ Incremental - Supports incremental parsing for editors
- ✅ Error Recovery - Handles partial/invalid code gracefully
- ✅ Maintained - Actively maintained by the tree-sitter community

Our Value: Universal AST format, cross-language tools, plugin system, and TypeScript API.

API Reference

$3

Parse PHP source code synchronously.

`typescript
const tree = parse('')
`

$3

Parse PHP source code asynchronously (for async plugins).

`typescript
const tree = await parseAsync('')
`

$3

Create a new PhpParser instance.

`typescript
const parser = createParser()
`

$3

Main parser class with plugin support.

`typescript
const parser = new PhpParser()
parser.use(plugin)
const tree = parser.parse('')
`

$3

`typescript
interface PhpParseOptions {
buildIndex?: boolean // Build query index (not yet implemented)
plugins?: Plugin[] // Plugins to apply
phpVersion?: 7 | 8 // PHP version (for compatibility)
}
``

License

MIT

---

Part of the Synth universal AST ecosystem - Works seamlessly with all other Synth parsers and tools.

---