php_rs_parser/
lib.rs

1//! Fast, fault-tolerant PHP parser that produces a fully typed AST.
2//!
3//! This crate parses PHP source code (PHP 8.0–8.5) into a [`php_ast::Program`]
4//! tree, recovering from syntax errors so that downstream tools always receive
5//! a complete AST.
6//!
7//! # Quick start
8//!
9//! ```
10//! let arena = bumpalo::Bump::new();
11//! let result = php_rs_parser::parse(&arena, "<?php echo 'hello';");
12//! assert!(result.errors.is_empty());
13//! ```
14//!
15//! # Version-aware parsing
16//!
17//! Use [`parse_versioned`] to target a specific PHP version. Syntax that
18//! requires a higher version is still parsed into the AST, but a
19//! [`diagnostics::ParseError::VersionTooLow`] diagnostic is emitted.
20//!
21//! ```
22//! let arena = bumpalo::Bump::new();
23//! let result = php_rs_parser::parse_versioned(
24//!     &arena,
25//!     "<?php enum Status { case Active; }",
26//!     php_rs_parser::PhpVersion::Php80,
27//! );
28//! assert!(!result.errors.is_empty()); // enums require PHP 8.1
29//! ```
30
31pub mod diagnostics;
32pub(crate) mod expr;
33pub mod instrument;
34pub(crate) mod interpolation;
35pub(crate) mod parser;
36pub mod phpdoc;
37pub(crate) mod precedence;
38pub(crate) mod stmt;
39pub mod version;
40
41use diagnostics::ParseError;
42use php_ast::source_map::SourceMap;
43use php_ast::{Comment, Program};
44pub use version::PhpVersion;
45
46/// The result of parsing a PHP source string.
47pub struct ParseResult<'arena, 'src> {
48    /// The original source text. Useful for extracting text from spans
49    /// via `&result.source[span.start as usize..span.end as usize]`.
50    pub source: &'src str,
51    /// The parsed AST. Always produced, even when errors are present.
52    pub program: Program<'arena, 'src>,
53    /// All comments found in the source, in source order.
54    /// Comments are not attached to AST nodes; callers can map them by span.
55    pub comments: Vec<Comment<'src>>,
56    /// Parse errors and diagnostics. Empty on a successful parse.
57    pub errors: Vec<ParseError>,
58    /// Pre-computed line index for resolving byte offsets in [`Span`](php_ast::Span)
59    /// to line/column positions. Use [`SourceMap::offset_to_line_col`] or
60    /// [`SourceMap::span_to_line_col`] to convert.
61    pub source_map: SourceMap,
62}
63
64/// Parse PHP `source` using the latest supported PHP version (currently 8.5).
65///
66/// The `arena` is used for all AST allocations, giving callers control over
67/// memory lifetime. The returned [`ParseResult`] borrows from both the arena
68/// and the source string.
69pub fn parse<'arena, 'src>(
70    arena: &'arena bumpalo::Bump,
71    source: &'src str,
72) -> ParseResult<'arena, 'src> {
73    let mut parser = parser::Parser::new(arena, source);
74    let program = parser.parse_program();
75    ParseResult {
76        source,
77        program,
78        comments: parser.take_comments(),
79        errors: parser.into_errors(),
80        source_map: SourceMap::new(source),
81    }
82}
83
84/// Parse `source` targeting the given PHP `version`.
85///
86/// Syntax that requires a higher version than `version` is still parsed and
87/// included in the AST, but a [`diagnostics::ParseError::VersionTooLow`] error
88/// is also emitted so callers can report it to the user.
89pub fn parse_versioned<'arena, 'src>(
90    arena: &'arena bumpalo::Bump,
91    source: &'src str,
92    version: PhpVersion,
93) -> ParseResult<'arena, 'src> {
94    let mut parser = parser::Parser::with_version(arena, source, version);
95    let program = parser.parse_program();
96    ParseResult {
97        source,
98        program,
99        comments: parser.take_comments(),
100        errors: parser.into_errors(),
101        source_map: SourceMap::new(source),
102    }
103}
php_rs_parser/lib.rs

php_rs_parser/
lib.rs
