Smarty Lexer Laravel Package

Getting Started

The smarty/smarty-lexer package is not meant to be used directly by end users—it's an internal dependency for generating the lexer/parser classes of the Smarty templating engine. As such, day-to-day usage is almost non-existent for typical developers. You’ll only interact with it if:

• You're contributing to or modifying the Smarty core (e.g., updating template syntax rules).
• You’re debugging low-level template parsing issues (e.g., tokenization anomalies).

If you're simply using Smarty in your Laravel app (e.g., via smarty/smarty), this package is already pulled in transitively—no setup needed. Check composer.lock under smarty/smarty-lexer if curious.

Implementation Patterns

• Automatic Generation: Since Smarty v3.1.35, the lexer/parser is auto-generated via composer install. No manual invocation required.
• Customizing Grammar (Advanced): To modify the lexer/parser (e.g., add custom template tags), you’d edit .atg (ANTLR grammar) files in src/grammar/, then run:

  php -d memory_limit=-1 vendor/bin/amber
  

  (Amber is the PHP ANTLR4 tool used by this package.)
• CI/CD Integration: If extending Smarty, add a pre-commit hook to regenerate lexer files after grammar changes and include them in the PR (the generated PHP classes must be committed, as end users don’t have Amber installed).

Gotchas and Tips

• PHP Version Compatibility: v4.x introduced fixes for inconsistent tokenization between PHP 7.x and 8.x. Ensure your development and production PHP versions match to avoid subtle parsing differences.
• Stale Generated Files: Manually regenerating lexer/parser with Amber may produce non-deterministic output across environments (due to ANTLR non-determinism). Always commit the generated output and verify diffs.
• No Public API: This package exposes only generator tooling—not runtime APIs. Avoid trying to use it for custom lexing outside Smarty.
• Maturity Warning: Low stars (12) and 0 dependents indicate minimal external adoption beyond Smarty internals. Treat it as an internal tool, not a general-purpose lexer library. Verify any forks against upstream smarty/smarty compatibility.
• Debugging Template Parse Errors: When SmartyCompilerException shows cryptic line numbers, inspect templates_c/your_template.php and correlate token IDs with src/Lexer.php’s protected static $tokenMap array.