Api Doc Bundle Laravel Package

Technical Evaluation

Architecture fit — primary blocker. Despite being filed under "Laravel/PHP package," this repository is a fork of nelmio/NelmioApiDocBundle, a Symfony bundle. It ships a Bundle subclass, an extension class, and a DIC-driven config tree, and it is designed to be registered in config/bundles.php and wired into the Symfony kernel. Laravel has no bundle/kernel registration model, no service container tag system matching Symfony's, and no Resources/config convention. There is no adapter, no service provider shim, and no evidence of Laravel-specific work in the fork. The integration feasibility for a Laravel application is effectively zero without a rewrite. For a Symfony application the package is technically installable but functionally redundant against upstream.

Integration feasibility. Composer install from a VCS repository is mechanically possible (repositories: {type: vcs}), but the package exposes no Packagist identity, has zero dependents, and therefore has never been exercised outside its author's machine. Even in a Symfony context, adopting a fork requires a documented divergence rationale — none is present. The fork's value proposition over upstream nelmio/api-doc-bundle is unstated, which for a TPM means the adoption cost is paid with no corresponding benefit.

Technical risk — high and unmitigated.

Key questions to force before any decision.

1. Does the target application actually run Symfony, or is "Laravel/PHP" a catalog misclassification? This single answer flips the evaluation.
2. What does this fork change relative to nelmio/api-doc-bundle at the last common commit — is there a diff worth owning?
3. If Laravel: has the team benchmarked dedoc/scramble, knuckleswtf/scribe, or darkaonline/l5-swagger? Any of these delivers first-class Laravel support today.
4. If Symfony: why not pin upstream, which has maintainers, a release train, and a CVE surface we can monitor?
5. What is the documented spec output (OpenAPI 2.0 vs 3.x)? Consumers downstream — gateways, client codegen, contract tests — constrain this.

Recommendation: no-go for adoption. Classify as an evaluation artifact only. The low opportunity score (28.36) is consistent with the evidence: this is a personal mirror with no adoption surface.

Integration Approach

Stack fit. Two branches, and the TPM decision differs for each:

• Laravel target: do not integrate. There is no service provider, no publishable config, no facade. Building the bridge is a multi-sprint engineering project whose output is a bespoke fork of an abandoned fork. Substitute dedoc/scramble (attribute/reflection-driven, zero-annotation) or knuckleswtf/scribe (Laravel-native, generates OpenAPI plus human-readable docs), or darkaonline/l5-swagger if the org is already standardized on swagger-php annotations.
• Symfony target: integrate upstream nelmio/api-doc-bundle, not this fork. Same API surface, live maintenance.

Migration path (if a team insists on the fork). Do not add it as a normal dependency. Vendor it behind an internal package (acme/api-docs) that pins the VCS commit, so the fork can be swapped for upstream or a replacement without touching application code. Record the diff against upstream in the internal package README; that diff is the entire justification and should be reviewed at each upgrade.

Compatibility checklist to run in a spike, not in production.

• PHP version vs. the fork's composer.json constraint, and whether the constraint allows the runtime you actually deploy.
• Symfony component major versions (symfony/framework-bundle, symfony/config, symfony/dependency-injection) — forks age out of the support window fast.
• doctrine/annotations presence and version; on PHP 8.2+ this pulls deprecation noise into every build.
• Attribute vs. annotation support in the pinned commit.
• Whether the generated spec validates against OpenAPI 3.0/3.1 in a linter (Spectral) — a spec that fails validation is worse than no spec.

Sequencing. (1) Spike, 3–5 days, timeboxed, one engineer, on a throwaway branch — confirm the framework question and produce a sample spec diffed against the incumbent tool's output. (2) If the spike clears, wrap in the internal package and run it in shadow mode alongside the existing documentation source in CI for one release cycle. (3) Cut over only after the shadow diff is empty or fully explained. (4) Gate the dependency with Dependabot/Renovate plus a quarterly upstream-diff review; if upstream diverges by more than an agreed threshold, escalate as a re-evaluation trigger.

Operational Impact

Maintenance. The real cost is not install, it is ownership. A zero-dependent fork means your team is the maintainer. Budget: PHP/Symfony minor-version compatibility work each cycle, spec-format upkeep as OpenAPI evolves, and a permanent line item to re-diff against upstream or migrate off. That is a recurring tax paid for functionality available free from maintained projects.

Support. No community, no issue triage, no security feed, no Stack Overflow corpus. Internal engineers cannot search their way out of a parser bug. Escalation path terminates at one individual with no SLA. For any system on a regulated or customer-facing surface, this fails standard third-party-risk review on the "actively maintained" criterion.

Scaling. Doc generation is a build-time concern, not a runtime one — cost is CI minutes and cache-warm latency, which is manageable. The scaling risk is organizational, not computational: one team's bespoke fork becomes an undeclared platform dependency when a second team copies it, and you inherit N copies of an unmaintained parser with N divergent config dialects.

Failure modes to instrument.

• Silent spec corruption — parser misreads an annotation/attribute and emits a stale or wrong schema. Mitigation: Spectral lint + a golden-file diff in CI that fails the build on unexplained spec changes.
• Build-time hard failure — new PHP minor deprecates the annotation reader and the doc step aborts the pipeline. Mitigation: isolate doc generation in its own CI job so it cannot block deploy, but alert on it.
• Route drift — docs describe endpoints that were renamed or removed. Mitigation: contract tests asserting spec paths against the live route table.
• Bus-factor event — repository disappears or is force-pushed. Mitigation: vendor the exact commit internally; never depend on a live VCS ref in production builds.
• Unpatched transitive CVE — inherited from symfony/* or swagger-php. Mitigation: SCA scan (Composer Audit) in CI and a documented exception process; expect to hit this within 12 months.

Ramp-up. For a Laravel team: high friction, low transferability. Bundle configuration, DIC tags, and annotation semantics are Symfony idioms; the knowledge gained does not compound into anything reusable, and it is knowledge the team must carry because no external documentation or community exists. For a Symfony team: near-zero ramp-up, but also near-zero reason to choose this fork over upstream — the familiarity argument cuts toward the maintained package. Estimate 1–2 days for a competent Symfony engineer to reproduce the spike, and 3–5 days plus a standing maintenance allocation for a Laravel engineer to discover the bridge is not worth building.

Bottom line for the roadmap. Treat this package as evidence gathering, not as a work item. Close it with a one-paragraph ADR: framework mismatch, no maintenance signal, no dependents, superseded by maintained alternatives in both ecosystems. Reopen only if the organization standardizes on Symfony and the fork demonstrates a documented, maintained divergence from upstream.