php-ast = "*" # AST types and visitor/fold traits

bumpalo = "*" # only needed when using parse_arena() directly

- **`ParserContext`** — reusable context for repeated re-parses; `reparse_owned()` returns a lifetime-free `ParseResult`, `reparse()` returns the arena form

- **`OwnedVisitor` / `OwnedScopeVisitor`** — traverse a `ParseResult` AST with no arena involved; see `php_ast::owned::visitor`

- **`FoldOwned`** — transform a `ParseResult` AST into a new owned AST; see `php_ast::owned::fold`

- **`Visitor` / `ScopeVisitor`** — arena-form traversal traits; see [`docs.rs/php-ast`](https://docs.rs/php-ast)

- **`Fold`** — arena-form transformation trait; reads one arena, writes another

Use `ParserContext` when parsing the same document repeatedly (e.g. on every keystroke). It reuses the backing arena memory in O(1), avoiding allocator churn.

`reparse_owned()` returns a fully-owned `ParseResult` — no lifetimes, no `drop` discipline required:

let a = ctx.reparse_owned("<?php echo 1;");

let b = ctx.reparse_owned("<?php echo 2;"); // a can stay alive

assert!(a.errors.is_empty());

assert!(b.errors.is_empty());

`reparse()` returns an `ArenaParseResult` that borrows from the context arena. The borrow checker prevents calling `reparse` again while that result is alive — drop it first:

`reparse_versioned` and `reparse_owned_versioned` are also available for targeting a specific PHP version.

`OwnedVisitor` works directly on a `ParseResult` — no arena, no lifetime parameters. Override only the node types you care about:

use php_ast::owned::visitor::{OwnedVisitor, walk_owned_expr};

use php_ast::owned::{Expr, ExprKind};

use std::ops::ControlFlow;

struct VarCounter { count: usize }

impl OwnedVisitor for VarCounter {

fn visit_expr(&mut self, expr: &Expr) -> ControlFlow<()> {

if matches!(&expr.kind, ExprKind::Variable(_)) {

self.count += 1;

}

walk_owned_expr(self, expr)

}

}

let result = php_rs_parser::parse("<?php $x = $y + $z;");

let mut v = VarCounter { count: 0 };

v.visit_program(&result.program);

assert_eq!(v.count, 3);

Return `ControlFlow::Break(())` to stop traversal early. Return `ControlFlow::Continue(())` without calling `walk_owned_*` to skip a subtree.

Use `OwnedScopeVisitor` + `OwnedScopeWalker` when you need to know **which namespace, class, or function** you are currently inside:

use php_ast::owned::visitor::{OwnedScopeVisitor, OwnedScopeWalker, OwnedScope};

use php_ast::owned::{ClassMember, ClassMemberKind};

use std::ops::ControlFlow;

struct MethodCollector { methods: Vec<String> }

impl OwnedScopeVisitor for MethodCollector {

fn visit_class_member(

&mut self,

member: &ClassMember,

scope: &OwnedScope,

) -> ControlFlow<()> {

if let ClassMemberKind::Method(m) = &member.kind {

self.methods.push(format!(

"{}::{}",

scope.class_name.as_deref().unwrap_or("<anon>"),

m.name,

));

}

ControlFlow::Continue(())

}

}

let result = php_rs_parser::parse("<?php class Foo { function bar() {} }");

let mut walker = OwnedScopeWalker::new(MethodCollector { methods: vec![] });

walker.walk(&result.program);

Use the arena `Visitor` when you need maximum throughput and manage the arena lifetime yourself:

Use `ScopeVisitor` + `ScopeWalker` for scope-aware arena traversal:

`FoldOwned` transforms a `ParseResult` AST into a new owned AST. Override only the node types you want to change; all others are rebuilt identically:

use php_ast::owned::fold::{FoldOwned, fold_owned_expr};

use php_ast::owned::{Expr, ExprKind};

impl FoldOwned for NegateInts {

fn fold_expr(&mut self, expr: &Expr) -> Expr {

if let ExprKind::Int(n) = &expr.kind {

return Expr { kind: ExprKind::Int(-n), span: expr.span };

}

fold_owned_expr(self, expr)

}

}

let result = php_rs_parser::parse("<?php $x = 1;");

let transformed = NegateInts.fold_program(&result.program);

`Fold` is the arena-form transformation trait. It reads from one arena and writes into a new output arena — the correct design for arena-allocated ASTs where in-place mutation would break lifetime invariants:

`pretty_print_owned` works directly on a `ParseResult` — no arena needed:

let result = php_rs_parser::parse("<?php echo 1 + 2;");

let output = php_printer::pretty_print_owned(&result.program);

Use `pretty_print_owned_file` to append a trailing newline. Use `pretty_print_owned_with_config` for custom indentation.

When using the arena API (e.g. inside an LSP handler that already holds an `ArenaParseResult`), use the arena-form functions directly to avoid an extra conversion:

let arena = bumpalo::Bump::new();

let result = php_rs_parser::parse_arena(&arena, "<?php // comment\necho 1;");

let output = php_printer::pretty_print_owned_with_config(&result.program, &config);

| **php-ast** | [](https://crates.io/crates/php-ast) | AST type definitions; arena `Visitor`/`ScopeVisitor`/`Fold` traits; owned (lifetime-free) `OwnedVisitor`/`OwnedScopeVisitor`/`FoldOwned` traits |

| **php-printer** | [](https://crates.io/crates/php-printer) | Pretty printer — converts an AST back to PHP source; supports both arena and owned AST |

Source flows through `Lexer → Parser → arena-allocated AST nodes`. The lexer is lazy (tokens produced on demand with peeking slots); the parser is Pratt-based recursive descent with panic-mode error recovery. The owned AST (`php_ast::owned`) provides lifetime-free mirrors of every node type, enabling storage and manipulation without arena lifetime constraints.

**When to use the arena API vs. the owned API:**

| Use case | Recommended API |

|---|---|

| One-shot parsing, CLI tools, batch processing | `parse()` → `ParseResult` (owned) |

| Store results in `HashMap`, send across threads | `parse()` → `ParseResult` (owned) |

| Walk or transform a `ParseResult` | `OwnedVisitor` / `FoldOwned` |

| LSP server, repeated re-parses | `ParserContext::reparse_owned()` or `reparse()` |

| Maximum throughput, arena lifetime under your control | `parse_arena()` → arena `Visitor` / `Fold` |

[dev-dependencies]

serde_json = { workspace = true }