Parser Laravel Package

Getting Started

amphp/parser is a low-level utility for building streaming parsers using PHP generators. To begin, install via Composer: composer require amphp/parser. The core concept is to define a parser as a generator function that yields parsing results and accepts input chunks incrementally. The primary entry point is the Parser class, which wraps your generator and handles iteration logic. Start by defining a simple parser for a fixed-size header or delimiter-based stream — for example, parsing newline-terminated messages — using yield to return parsed chunks as they become available.

Implementation Patterns

• Generator-based parsers: Encapsulate parsing logic inside a function* (string &$input): Generator where you consume $input incrementally, yield completed values (e.g., parsed messages), and update $input in-place (or via slicing) as you go.
• Reusable parser combinators: Build composable parsers (e.g., parseUntil(), parseBytes()) that chain to form more complex parsers — like building JSON tokens or HTTP headers line-by-line.
• Integration with amphp/byte-stream: Use with BufferedInputStream or InputStream to feed parsed streams from network sockets (e.g., custom protocols over TCP).
• Lazy consumption: Pull results only as needed (via next()/send()) to enable backpressure — ideal for high-throughput or memory-constrained streaming scenarios.

Gotchas and Tips

• Input mutation is manual: The parser generator receives string &$input by reference; it’s your responsibility to consume bytes (e.g., substr($input, $consumed) or unset chunks) to avoid re-processing or memory bloat.
• Yield semantics matter: Always yield on complete semantic units (e.g., a full record), not partial state — partials must be accumulated internally in the generator’s scope.
• No built-in error recovery: Errors (e.g., malformed input) must be handled explicitly; consider yielding null, throwing exceptions, or returning error types within your yielded structure.
• Performance tuning: For large streams, avoid unnecessary string concatenation — prefer substr() or unpack() on the existing buffer. Reuse generator instances where possible to reduce allocation overhead.
• Debugging tip: Manually drive the parser generator with IteratorIterator or Generator::current() during development, feeding known test bytes via send() to trace state transitions.