- What is clean/phpdoc-md and what does it do?
- It is a Composer-installable PHP CLI tool that parses your source files and PHPDoc blocks and writes clean Markdown API documentation. It extracts classes, interfaces, traits, methods, properties, and constants, preserves tags such as @param, @return, @throws, and @deprecated, and outputs portable Markdown that renders on GitHub, GitLab, or any static site generator. It is a dev-time build tool, not a runtime library, so it never enters your application's request path.
- How do I install clean/phpdoc-md in a Laravel project?
- Install it as a dev dependency with composer require --dev clean/phpdoc-md so it stays out of your production autoload and deploy artifact. There is no service provider or config file to register because it is a standalone CLI utility rather than a Laravel package. You then run the binary directly or wrap it in a Composer script or a small custom Artisan command.
- Does clean/phpdoc-md support Laravel and which PHP versions can I use?
- It is framework-agnostic and runs fine inside a Laravel repository because it only reads PHP source and docblocks; it does not require Laravel at all. The practical constraint is the last release in November 2022, so newer PHP 8.3 and 8.4 syntax such as property hooks is unlikely to be handled without verification. Test it against your target PHP version before committing to it.
- Which PHPDoc tags and code structures does clean/phpdoc-md document?
- It covers classes, interfaces, traits, methods, properties, and constants, and it preserves standard annotations including @param, @return, @throws, and @deprecated. The generated Markdown is organised per structure so it reads as a browsable API reference. Annotations outside the standard docblock tags are not interpreted.
- Can I generate documentation for a whole namespace or directory tree at once?
- Yes. The tool supports batch processing, so you can point it at an entire directory tree or namespace and produce a full set of Markdown files in one run. That makes it practical to regenerate docs for a complete package or app namespace instead of file by file.
- Can I run clean/phpdoc-md in CI to keep API docs up to date?
- You can, but treat it carefully as a CI gate. Because it is a simple CLI, a Composer script in your pipeline is enough to regenerate Markdown on each build. Before relying on it, confirm whether it fails the process on parse errors or silently skips files it cannot parse, since silent partial output would let incomplete docs pass review.
- Is clean/phpdoc-md safe to use in production?
- It should never be a production dependency. Keep it in require-dev, never autoload it at runtime, and never reference it from application code. Its only output is static Markdown, so there is no deploy artifact impact when you scope it to developer tooling alongside Pint or PHPStan.
- How does clean/phpdoc-md handle enums, readonly properties, and Eloquent magic properties?
- Static parsing of PHPDoc and class structure cannot see Eloquent's dynamic attributes, relationships, or facades, so models will expose far less surface than they actually have. Newer language constructs such as enums, readonly properties, and property hooks are risky on a package last released in 2022 and should be verified on a sample before adoption. Expect to hand-annotate magic behaviour with docblocks if you need it documented.
- Is clean/phpdoc-md actively maintained?
- There has been no release since November 2022, and the project has a single maintainer with a small star count, so the main risk is abandonment rather than correctness. Repository metadata is also hard to resolve, which is worth clarifying before you depend on it. Pin the version, keep it a dev dependency, and treat it as a time-boxed spike unless you are prepared to fork and own it.
- What are the alternatives to clean/phpdoc-md for PHP API documentation?
- phpDocumentor is the established option with richer output formats, and Scribe or similar tools cover HTTP API references for Laravel. IDE-based docblock navigation and static analysis handle day-to-day browsing without generating files at all. The niche for clean/phpdoc-md is a lightweight, Markdown-first reference you can commit next to your code and publish with MkDocs, Docusaurus, or an internal wiki.