Webidl Laravel Package

Product Decisions This Supports

• Build vs. buy (really: generate vs. hand-write). This is a build-time code generator, not a runtime library. It parses a WebIDL contract and emits PHP interfaces, traits, and stubs. The decision it informs is whether your team hand-maintains a spec-shaped API surface in PHP or generates it from a single source of truth — typically a saving of hundreds to thousands of lines that would otherwise drift from the spec.
• Spec-as-contract roadmap calls. If your roadmap includes implementing or exposing a spec defined in WebIDL (W3C DOM, browser-adjacent APIs, MediaWiki REST surface definitions), adopting the IDL as the canonical artifact and generating PHP from it is a defensible architecture decision. This package is the enabler for that decision in PHP.
• Interchangeable backend / abstraction decisions. Its strongest proven use case is Wikimedia's own IDLeDOM: one generated interface set, multiple implementations (native ext-dom vs. a pure-PHP DOM), so application code is written against interfaces and the backend is swappable. Use this to justify an interface-first design over a concrete-class design.
• Type-safety and static-analysis investment. Generated interfaces with return types and typed properties improve PHPStan/Psalm coverage and IDE autocomplete across a large surface area — relevant when prioritizing "reduce runtime type bugs" work.
• Use cases where it fits: generating a PHP binding for an IDL you own; keeping generated code in lockstep with a spec revision in CI; producing interface/trait splits so implementers only fill in behavior.
• Use cases where it does not fit (decide against): wire-format validation of JSON payloads (use a JSON Schema validator), OpenAPI-driven client/server generation (use an OpenAPI generator), or any scenario where you only need a handful of interfaces (just write them).

When to Consider This Package

Adopt it when all of these hold:

• You have, or are committing to, a WebIDL definition as the authoritative contract.
• The generated surface is large enough that hand-maintenance is a real cost or drift risk (rule of thumb: dozens of interfaces, not three).
• You are comfortable adding a codegen step to your build/CI and committing or caching the output.
• You can absorb the ownership cost: this is effectively a single-organization tool with thin documentation.

Look elsewhere when:

• Community/support signals are your bar. 1 GitHub star, 0 recorded dependents, and a read-only GitHub mirror — the real development happens on Wikimedia's Gerrit. Expect no issue triage, no Stack Overflow corpus, and no external contributors. Treat it as vendored internal tooling, not a community dependency.
• You need contributor velocity. Outside patches route through Gerrit and MediaWiki developer access, which is friction most product teams won't want.
• Documentation-driven onboarding matters. Plan on reading the source and IDLeDOM's usage as your primary reference; budget a spike, not a doc read.
• Survivability is a hard requirement. Pin a commit, vendor or fork it, and assume you may own it. Do not put it on a runtime critical path — it should be a require-dev / build-time dependency only.
• Your problem isn't WebIDL-shaped. Most REST/API contract work is better served by OpenAPI tooling or JSON Schema validators.

How to Pitch It (Stakeholders)

To executives: This is not a product bet; it's a low-cost engineering accelerator. MIT-licensed, zero licensing spend, and it converts a spec document into typed PHP automatically instead of paying engineers to hand-maintain it and chase drift. The real cost is ownership: the project is Wikimedia-internal, thinly documented, and effectively single-maintainer, so we'd vendor it and treat it as our code. Recommendation: fund a short spike, not a commitment.

To engineering: It's a parser/generator — WebIDL in, PHP interfaces and traits out. It gives us one source of truth, deterministic regeneration in CI, PHPStan-friendly typed contracts, and a clean interface/implementation split so backends can be swapped (the pattern Wikimedia uses for IDLeDOM). Caveats to accept up front: GitHub is a mirror, patches go to Gerrit, docs are the source code, and we pin and vendor it rather than tracking upstream. Use it as a dev dependency; never ship it to production runtime.

Ask: a 1–2 day spike generating interfaces from our target IDL, measured against the hand-written alternative in lines saved, drift risk, and maintenance burden — then a go/no-go.