Api Doc Laravel Package

Technical Evaluation

Architecture fit — poor, with a category mismatch to resolve first. Despite the brief describing this as a "Laravel/PHP package," pedrotroller/api-doc is a Symfony bundle that extends NelmioApiDocBundle v2.x. It hooks into Nelmio's annotation-driven extractor pipeline and Symfony's translator service to emit localized description/summary fields into generated API docs. It assumes Symfony's DI container, event dispatcher, and Translation component — none of which map onto Laravel's container, routing, or localization model. Before any evaluation is actionable, confirm whether the target application is actually Laravel or Symfony; if Laravel, this package is architecturally out of scope.

Integration feasibility — low. Adopting it means either (a) running a hybrid Symfony/Laravel stack (not realistic), or (b) reading the package as a reference implementation and porting its translation-decorator pattern to the actual doc generator in use (Scramble, Scribe, L5-Swagger, or zircote/swagger-php on Laravel; NelmioApiDocBundle v4/v5 with a custom DescriberInterface or ModelDescriber decorator on Symfony). The porting surface is small — the package is a thin set of decorators/wrappers — so the cost is measured in hours, not weeks.

Technical risk — high, concentrated in abandonment and version skew.

• Last release 2016-06-08; single maintainer; 0 dependents, 1 star. Effectively a personal utility, not a supported library.
• Pinned to NelmioApiDocBundle ^2.x, which is EOL. Nelmio v3 (2017) and v4/v5 replaced the annotation extractor with swagger-php, removing the extension points this package relies on.
• Likely PHP ^5.5|^7.0 and Symfony ^2.3|^3.0 constraints — direct Composer conflicts with PHP 8.x, Symfony 5+/6+/7, and every current Laravel release.
• Zero security/maintenance posture: no CI, no issue triage, no disclosure process.

Key questions for the sponsor:

1. Is the consuming application Laravel or Symfony — and which version?
2. Is the actual requirement localized API documentation (per-locale descriptions, multi-language developer portal) or localized API responses? These are different problems with different solutions.
3. Which doc generator is in production today, and does it support OpenAPI 3.0/3.1?
4. Is there a hard dependency on Nelmio v2 for legacy reasons, or is this a greenfield decision?
5. What is the acceptable support horizon for a docs pipeline dependency — 12 months, 36 months?

Integration Approach

Stack fit. Not viable as a drop-in on Laravel 9–12 or Symfony 5+. Viable only on a legacy Symfony 2.8/3.x application already running NelmioApiDocBundle v2 — a shrinking population — and even then only as a pinned, vendored dependency you accept ownership of.

Recommended path: do not install; re-implement the pattern.

• Laravel: implement locale-aware docs via a post-processing step over the generated OpenAPI JSON (a small service that walks paths.*.description and substitutes from lang/{locale}/api.php), or via Scramble/Scribe's documentation hooks. This preserves the capability while dropping the dependency.
• Symfony (modern): upgrade to NelmioApiDocBundle v4/v5 and decorate the relevant Describer services with a translator-aware wrapper — the same conceptual move as this package, against a supported upstream.
• Symfony (legacy, unavoidable): pin nelmio/api-doc-bundle:^2.13 and this package, vendor-fork it into the repo, and schedule migration off it.

Compatibility matrix to verify before committing: PHP constraint, symfony/framework-bundle constraint, nelmio/api-doc-bundle constraint, and whether the annotation reader (doctrine/annotations vs. sensio/framework-extra-bundle) is still resolvable.

Sequencing.

1. Day 1 — stack confirmation. Resolve Laravel vs. Symfony and the current doc generator. This gates everything downstream.
2. Day 2 — spike. Timebox a one-day proof-of-concept porting the translation decorator onto the real generator, covering two endpoints and two locales.
3. Day 3 — decision. If the spike holds, adopt the ported pattern and archive this package as reference only. If it fails, fall back to static per-locale doc builds (generate openapi.en.json, openapi.fr.json at build time) — cheaper, cache-friendly, and avoids runtime translation entirely.
4. Follow-on — translation catalog pipeline. The real long-term cost is not the decorator; it is managing per-locale API description catalogs alongside code changes.

Operational Impact

Maintenance. Effectively unmaintained upstream and here. Every future PHP or framework upgrade is a manual compatibility patch you own. Budget a recurring line item — small per incident, but indefinite. Treat the codebase as an internal fork from day one.

Support. No community, no maintainer response, no dependents to learn from. Internal documentation of why the translation decorator exists is mandatory, because the original rationale lives only in a 2016 commit history.

Scaling. Throughput is a non-issue — documentation generation is a build-time, low-QPS workload. The scaling cost is organizational: adding a locale means adding a catalog, and every new endpoint must ship with descriptions in N locales or silently regress to fallback text. That is a process burden on every API-contributing team, and it is where the real TCO sits.

Failure modes to design against.

• Composer resolution failure on PHP 8 / modern Symfony — the most likely first failure, and a hard blocker.
• Silent fallback when a translation key is missing: docs render the raw key or the default-locale string, and no one notices until an external developer reads it.
• Prod cache staleness — translated docs baked into a cached build and not regenerated on locale catalog change.
• Extractor/service not registered after a framework upgrade — docs build fails or emits untranslated output without an error.
• Annotation parser drift — Nelmio v2's reader assumptions breaking under a newer doctrine/annotations.

Ramp-up. The package itself is small and quick to read — a competent PHP engineer will understand it in under a day. The surrounding knowledge (Nelmio v2 internals, Symfony 2/3 annotation conventions, 2016-era Composer constraints) is legacy and increasingly hard to hire for; that, not the code, is the ramp-up cost. A developer familiar with modern OpenAPI tooling will need explicit context transfer to work on a legacy Nelmio v2 pipeline.

Bottom line for the sponsor. The capability — localized API documentation — is legitimate and worth having. This package is not the vehicle: it is abandoned, mis-scoped for a Laravel stack, and pinned to an EOL upstream. Recommend a one-day spike to port the translation-decorator pattern onto the current generator, and record this package as a design reference rather than a dependency.