Wikipeg Laravel Package

Product Decisions This Supports

• Build vs. buy on parsing. Every "we need a small language" feature request (filter syntax, query DSL, pricing/eligibility rules, template placeholders, custom import formats) forks into either hand-rolling a recursive-descent parser or adopting a generator. WikiPEG is the "buy" option: you write a .pegjs grammar, it compiles to a plain PHP parser class, no Node/JS runtime in production. That's a genuine differentiator over PEG.js/Peggy, which would force a JS toolchain into a PHP deploy.
• Roadmap sequencing. This is an enabler, not a feature. Adopting it is a bet that you'll ship 2+ grammar-driven features over the next year; if only one is on the roadmap, a one-off hand-written parser is cheaper.
• Feature scope decisions it unlocks or blocks. It makes user-authored expressions feasible (think: a rules editor, saved-search syntax, a mini expression language in admin UI). It does not help with IDE-grade tooling — no incremental reparse, no error recovery, limited "fix-it" diagnostics — so any roadmap item promising live validation or autocomplete inside a custom language needs a different answer.
• Vendor/risk decision. Wikimedia-authored, MIT-licensed, but a Gerrit mirror with 9 stars, zero Packagist dependents, and contributions that don't flow through GitHub PRs. The PM decision is whether you're comfortable pinning a version, vendoring a fork if needed, and owning the grammar file as internal IP.
• Not a Laravel decision. There's no service provider, config, facade, or queue/HTTP integration — treat it as a standalone library you wrap in a small ParserService yourself. Don't let it into a "Laravel packages we standardize on" list.

When to Consider This Package

Adopt when:

• You have a real grammar — operator precedence, nesting, ambiguity, dozens of productions — where regex and explode() have already failed once.
• The grammar is stable and versioned; you can commit the .pegjs file and the generated PHP alongside your app and regenerate deliberately.
• You need PHP-only at runtime and can't add a JS build step to CI.
• You're willing to pin an exact version, watch the Wikimedia Gerrit repo for changes, and accept slow upstream responsiveness to your issues.
• MIT license compatibility matters (commercial/closed-source Laravel product) — it's clean here.

Look elsewhere when:

• Parsing PHP itself → nikic/php-parser.
• Simple expressions / user math or conditionals → symfony/expression-language; it's better supported and reviewers already know it.
• Just tokenizing or splitting → doctrine/lexer or plain regex.
• You need a large community, fast security turnaround, or Laravel-native ergonomics — this package offers none of those; 0 dependents is a signal, not an accident.
• Performance-critical hot paths or very large inputs — benchmark the generated parser against a hand-written one before committing.
• You need error recovery / partial parses for editor-style UX.

How to Pitch It (Stakeholders)

For executives (one paragraph): We have a recurring class of requests that need a small custom language — a filter syntax, a rules editor, an import format. Today each one becomes bespoke parser code that's expensive to change and hard to test. WikiPEG lets us describe the language as a readable grammar file and generate the PHP parser, so changes become grammar edits instead of rewrites. It's MIT-licensed and PHP-only at runtime. The trade-off is that it's a low-profile Wikimedia library with a thin external community, so we'd pin a version and treat the grammar as first-class internal code. Recommendation: prototype on one feature before standardizing.

For engineering (the honest version): It's a PHP port of PEG.js — write .pegjs, run the CLI, get a PHP class with parse(). No JS in the deploy pipeline, which is the whole reason to prefer it over Peggy. Caveats: development happens on Wikimedia Gerrit, not GitHub; expect to fork or vendor rather than get upstream PRs merged; generated code is committed and reviewed like any other source. Wrap it behind a domain interface so we can swap to a hand-written Pratt parser if the grammar stays small. Start with a spike on the smallest real grammar we have, with a test suite driven by grammar fixtures — if the spike is clean, the second and third languages are nearly free.