Tolerant Php Parser Laravel Package

Getting Started

Install via Composer: composer require microsoft/tolerant-php-parser. Start by parsing incomplete or syntactically invalid PHP code—this is the core value. For example, parse a file being edited in an IDE where braces are mismatched or semicolons are missing:

$parser = new \Microsoft\PhpParser\Parser();
$code = '<?php class Foo { public function bar( $x'; // Broken!
$ast = $parser->parseFile($code);
$diagnostics = $ast->getDiagnostics(); // Shows parse errors instead of crashing

Use getDiagnostics() to surface syntax issues programmatically—ideal for linters or live error highlighting. First-target use case: integrating real-time syntax feedback in a Laravel-based IDE extension or dev tool.

Implementation Patterns

• IDE-grade incremental parsing: Call parseFile() on changed substrings during typing (e.g., with editor onDidChangeContent events) to maintain responsive tooling—no need to re-parse entire files.
• AST traversal for diagnostics: Extend \Microsoft\PhpParser\NodeVisitor to traverse the AST and surface custom checks (e.g., detect insecure usage of eval()):

  $ast->acceptVisitor(new class extends NodeVisitor {
      public function visitCallExpression(Node $node) {
          $funcName = $node->getFirstDescendantNode(NodeName::class);
          if ($funcName && $funcName->getText() === 'eval') {
              $this->reportIssue('Use of eval() detected', $node);
          }
          return NodeVisitor::DONT_TRAVERSE_CHILDREN;
      }
  });
  

• Hybrid with nikic/php-parser: Use tolerant parser before nikic’s stricter parser—tolerant handles broken code and extracts AST fragments, while nikic validates final output.
• Laravel-specific: Wrap in a console command or queue job to analyze legacy Laravel codebases where syntax errors may exist, reporting diagnostics as structured JSON for CI dashboards.

Gotchas and Tips

• AST ≠ nikic/php-parser: The node structure differs significantly (e.g., different class names, method signatures). Don’t assume interoperability—expect adapter code when migrating from nikic.
• No runtime guarantees: This only gives syntax-level structure. Never use it for runtime validation (e.g., form validation), even if the AST is "successful"—errors like undefined variables won’t be reported.
• Diagnostics are positional: Diagnostics report start and length positions, not line/column. Convert with:

  $line = substr_count($code, "\n", 0, $diagnostic->getPosition());
  $col = $diagnostic->getPosition() - strrpos($code, "\n", $diagnostic->getPosition() - strlen($code)) - 1;
  

• PHP version support is incomplete: Verify support for PHP 8.1+ features (e.g., readonly properties, union types in parameter positions) in real code before committing.
• No autoloading of diagnostics: Diagnostics are not exceptions—parseFile() never throws unless memory/core issues occur. Always check $ast->getDiagnostics() even if parsing "succeeds".
• Fragile for fragments: When parsing code without <?php, use parseSourceString() and prepend <?php explicitly to avoid tokenization issues with T_INLINE_HTML.
• Benchmark large files: The parser is optimized for latency, but verify performance on 10k+ LOC Laravel models/controllers before deploying to production tooling.