Blade Parser Laravel Package

Getting Started

1. Install via Composer: composer require stillat/blade-parser
2. Parse your first template:

   use stillat\BladeParser\Parser;
   
   $parser = new Parser();
   $document = $parser->parseString('@extends('layouts.app') @section('content') Hello {{ $name }} @endsection');
   

3. Inspect the AST: Access top-level nodes via $document->getNodes() — each node has a type (e.g., @extends, @section, {{ }}) and metadata (content, position).
4. Start with examples: Check examples/ in the repo for basic traversal and transformation use cases.

Implementation Patterns

• Linting/Validation: Traverse the AST to enforce rules (e.g., disallow direct use of @php blocks, detect unused sections).
• Formatting/Refactoring: Use the parser to tokenize → analyze → rewrite safely (e.g., convert @yield to @section + @show, or normalize spacing around directives).
• IDE Tooling Integration: Emit LSP-compatible diagnostics by mapping node positions back to source offsets.
• Dependency Extraction: Identify used components, layouts, or partials (e.g., extract all @include paths) for dependency graphs.
• Custom Directives Analysis: Parse user-defined directives (e.g., @auth sugar) since they’re treated as raw tokens in the AST — useful for auditing non-core Blade extensions.

Workflow Tip: Always parse from disk (not rendered output!) using $parser->parseFile('resources/views/dashboard.blade.php') to get accurate source mapping.

Gotchas and Tips

• No execution safety: While the parser avoids compiling/running Blade, it does not validate semantic correctness (e.g., unclosed @if passes parsing). Implement your own structural validation.
• Syntax coverage gaps: Experimental directives (e.g., @class, @props) may parse inconsistently — verify via $node->rawContent if AST node is unexpected.
• Whitespace sensitivity: Trimming directives (@endphp, @endsection) are preserved as-is; use $node->getSourceContext()->getLine() to correlate with original line numbers.
• Rewriting pitfalls: Never rebuild Blade manually — use $document->getSource() for exact round-tripping, or the SourceTransformer class for surgical edits.
• Extension point: Override TokenStream or implement custom NodeVisitor for deep static analysis (e.g., detect Blade expressions with unresolved variables via {{ $var->method() }}).