Php Yacc Laravel Package

Getting Started

Begin by installing via Composer: composer require --dev ircmaxell/php-yacc. Examine the examples/ directory — especially examples/php/grammar.y and template.php — to grasp YACC syntax and required parser template structure. The minimal workflow is:

1. Create a grammar file (e.g., simple.y) with terminals, non-terminals, and rules
2. Copy or adapt template.php for your needs (handles parser class skeleton and action code injection)
3. Generate parser: vendor/bin/phpyacc -f simple.y -t template.php -o SimpleParser.php
   Note: CLI is unstable — lock versions and avoid scripting against it. Requires PHP 8.1+. Generated files must be committed and autoloaded — never generated at runtime.

Implementation Patterns

• Build-time generation only: Run phpyacc in CI/pre-commit hooks; the parser class becomes static code. Avoid any runtime generation.
• Lexer integration: Use parser-generated token constants (e.g., SimpleParser::T_NUMBER) as lexer emission tokens. Ensure your lexer yields arrays like [token_id, value, line] for compatibility.
• AST construction: Leverage the -n flag (v0.0.7+) to name semantic values, e.g.:

  %name expr
  expr: expr '+' expr { $$ = new AddNode($expr_1, $expr_2); }
  

  Avoids fragile $1, $2 references.
• Token sharing: Use conditionals in grammar (e.g., #if defined('PHP7')) to support multiple language variants, inspired by PHP-Parser’s dual PHP5/7 support.
• Parser lifecycle: Instantiate a new parser per parse job — instances hold internal state (e.g., lookahead, stack) and are not thread-safe.

Gotchas and Tips

• Silent failures: Mismatched tokens (lexer yields T_NUM but grammar expects T_NUMBER) cause non-descriptive errors — log lexer output during debugging.
• Template syntax hazards: Generated code uses $$, $1, $2, etc. — avoid <?php $var = $$ ... ?> in templates; use <?= sparingly and always with explicit defaults (<?= $action ?? '' ?>).
• Conflict visibility: Shift/Reduce and Reduce/Reduce warnings go to stderr only (v0.0.5+). Use phpyacc -v to generate detailed conflict logs — inspect them early in grammar design.
• Missing YACC features: %union, %type, and %left/%right associativity are not supported. Semantic type annotations like $<expr>{...} won’t work — rely on naming (-n) and convention.
• Debugging: Set YACC_DEBUG=1 env var (check generated parser for YACC_DEBUG usage) or inspect debug() calls in the parser. Enable verbose output with phpyacc -v.
• Maintenance risk: Last release is August 2020 with 0 dependents and no active development. Pin to ircmaxell/php-yacc:~0.0.7 and audit generated code in CI. For production-critical parsing, consider forking or migrating to nikic/php-parser (which uses kmyacc directly).