Lexer Contracts Laravel Package

Product Decisions This Supports

• Extensibility boundary for a parser/DSL product. If we ship a templating engine, query language, config-format parser, or internal codegen tool built on phplrt/phplrt, these contracts let us expose a public "bring your own lexer" extension point without forcing consumers to install the whole parser framework. That's a product decision about how open our integration surface is, made at near-zero dependency cost.
• Build vs. buy, framed correctly. This is not a "buy a lexer" decision — it's a "buy a stable interface surface" decision. The package contains contracts only; the real capability (tokenizing) lives in phplrt/lexer. The decision it informs is whether to define our own lexer interface or adopt a pre-existing one that already has an implementation behind it.
• Dependency-graph budget for a library we publish. If we publish a package that accepts a lexer (a linter, a formatter, a static-analysis plugin), depending on contracts-only keeps our require block tiny and avoids coupling our users to a specific tokenizer. That is a real packaging/roadmap choice, not a technicality.
• Swap-ability and testing strategy. Interface-only dependencies make mocking and multi-backend support tractable — useful if roadmap includes "support two tokenizers" or "let enterprise customers plug in a proprietary lexer."
• Vendor-risk triage. With 1 star and 0 dependents, treat this as a coupled-to-upstream artifact rather than a strategic dependency. The decision it supports is containment: use it at the edges, behind our own adapter, so we can replace it in a sprint rather than a quarter.
• Use cases it realistically unlocks: custom tokenizers for internal template/log/SQL dialects, IDE-ish devtooling (syntax highlighting, linting pipelines), and codegen front-ends — all internal-facing and low blast radius.

When to Consider This Package

Consider it when:

• We are already committed to phplrt and need a custom Lexer implementation that interoperates with its parser stack.
• We are publishing a library that consumes a lexer and want the smallest possible Composer footprint — contracts-only, MIT, no runtime behavior.
• We want to type-hint or unit-test against lexer interfaces without dragging in a concrete implementation.
• We need a defensible, documented contract rather than a homegrown interface that drifts.

Look elsewhere when:

• We need actual tokenization — use phplrt/lexer or phplrt/phplrt directly. This package gives us nothing to run.
• We are not on phplrt. nikic/php-parser, doctrine/lexer, or a 200-line hand-rolled tokenizer is a better fit, and avoids inheriting a low-traction dependency.
• We are a single internal application. Adding a contracts-only package alongside the framework it belongs to buys us nothing; just depend on the framework.
• We anticipate needing to patch the interfaces. This is a read-only subtree split of the phplrt/phplrt monorepo — fixes and PRs must go upstream, and version numbers track the monorepo, not this package's own release cadence. If we need to fork and modify, we fork the monorepo and lose the "tiny dependency" benefit entirely.

Adoption criteria before we commit: pin an exact version, wrap it in our own adapter interface so no application code imports Phplrt\Lexer\* directly, and confirm upstream is actively maintained (last release, issue responsiveness) since the split repo itself carries almost no independent signal.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed PHP package that defines interfaces for a lexer — the tokenizing stage of a parser. It adds essentially no code to our runtime and no licensing cost. It is worth adopting only as an internal seam: it lets us offer a pluggable, swappable tokenizer in parser-based products while keeping our dependency footprint clean. The caveat is maturity: the standalone repo shows 1 star and 0 dependents, and it is a read-only mirror of a larger monorepo, so its health is entirely the health of that upstream project. Recommendation: use it at the boundary, not at the core; do not build a roadmap commitment on it.

To engineering: Contracts-only, interfaces for lexers. Value is that we can accept a lexer without depending on a concrete tokenizer, which makes testing and multi-backend support straightforward. Constraints: it's a subtree split — no direct PRs here, versioning follows phplrt/phplrt, and it ships no behavior (you still need phplrt/lexer). Proposed pattern: our own thin adapter interface wraps these contracts so replacement is a one-file change, and we pin versions explicitly rather than floating.

To product/design: The practical payoff is that parser-based features (template syntax, query languages, custom formats) can support customer- or team-supplied tokenizer extensions later without re-architecting. That optionality is cheap now and expensive to retrofit, which is the entire argument for the dependency.