Phpdoc Md Laravel Package

Product Decisions This Supports

• Docs-as-code / reference documentation for internal PHP libraries. If we maintain shared packages (SDK, domain utilities, internal Composer packages), this converts existing PHPDoc blocks into Markdown that can live in the repo, render on GitHub/GitLab, or feed a static docs site. That directly reduces "docs drift" — the recurring cost of reference docs going stale relative to code.
• Build vs. buy vs. skip. It sits at the low end of the build/buy curve: MIT-licensed, single-purpose, no runtime dependency in production. The realistic decision is adopt-and-vendor (small surface area, forkable) rather than integrate as a platform dependency.
• Roadmap input for developer-experience work. Useful signal for prioritizing "self-documenting code" standards (enforced docblocks + generated reference) over hand-maintained wiki pages. Supports a lightweight ADR/lint rule that PRs touching public APIs carry complete docblocks.
• Use cases it genuinely fits: API reference pages for a package's public classes, onboarding cheat-sheets generated per release, wiki snapshots at tag time in CI, and README "API" sections that would otherwise be hand-edited.
• Use cases it does not fit: end-user product documentation, HTTP/API contract docs, tutorials, or anything requiring diagrams, search, versioning, or cross-references. Those need a real docs platform.
• Cheap experiment. Because it's a dev-only tool with no production footprint, the decision cost of a 1–2 day spike is low; the primary risk is maintenance, not integration.

When to Consider This Package

Consider it when all of the following hold:

• The documentation target is class/method-level reference derived from docblocks we already write — not narrative or product docs.
• The surface is small and contained (one or a few packages), so a partially imperfect renderer is acceptable and reviewable by eye.
• The team is comfortable vendoring or forking a ~44-star, MIT-licensed tool and pinning it, with no expectation of upstream fixes.
• Our PHP version and syntax are within what the tool parsed as of its last release (Nov 2022) — verify against PHP 8.2/8.3 features (enums, readonly properties, first-class callable syntax, DNF types) before committing.
• Output is consumed in-repo or via a static site where Markdown is the native format.

Look elsewhere when any of these are true:

• Maintenance matters. Last release 2022 and low community traction imply unpatched parser gaps as PHP evolves. If docs generation is on a critical release path, that's unacceptable.
• Framework awareness is needed. This is not a Laravel-integrated tool: no Artisan command, no service provider, no route/controller/command introspection. For Laravel-native API docs, evaluate Scramble or Scribe; for general PHP API reference, phpDocumentor (HTML + richer reflection) is the safer, maintained choice.
• You need OpenAPI/JSON Schema output, request/response examples from real code, or versioned multi-release docs — none of which this addresses.
• You want a single docs pipeline. Introducing a fourth tool for one output format adds CI and ownership overhead that may exceed the value at our scale.

How to Pitch It (Stakeholders)

To executives: This is a small, free, MIT-licensed developer tool that turns the code comments our engineers already write into Markdown reference documentation. It does not touch production, adds no runtime dependency, and costs at most a short evaluation spike. The upside is less time spent hand-maintaining package reference docs and fewer stale docs during onboarding. The caveat is honest: it is a low-traffic project with no release since late 2022, so we treat it as a forkable utility we can pin and patch ourselves rather than a strategic dependency. Recommended next step is a time-boxed spike on one internal package; if the output quality isn't there, we fall back to phpDocumentor with no sunk cost.

To engineering: It parses PHPDoc blocks and emits Markdown — a docs-as-code primitive, not a framework tool. No Laravel package, no Artisan command, no service provider; you wire it into a Composer script or CI step and commit or publish the output. Verify parser coverage against our PHP version and syntax before adopting, since upstream activity stopped in 2022. Preferred integration: dev-only dependency, pinned version, generated output reviewed in PRs or published on release tags. If we adopt, budget a small owner and a fork contingency; if the docblock surface grows beyond class/method reference, escalate to phpDocumentor or Scramble instead of stretching this tool.