phpDocumentor / phpDocumentor/guides
Use precise PSR-4 autoload prefixes and flatten src/<Namespace>/ across packages
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 36
- Forks
- 22
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 24
Description
Follow-up from #1078.
Several packages declare a PSR-4 autoload prefix broader than the namespace their classes actually live under, e.g. guides-markdown declares "phpDocumentor\\Guides\\": "src/" even though every class is under phpDocumentor\Guides\Markdown\.... This forces a non-optimized autoloader (common in dev environments) to check that package's src/ for classes anywhere under phpDocumentor\Guides\, not just its own subset. Packages with the same imprecise prefix: guides-code, guides-graphs, guides-markdown, guides-pages, guides-restructured-text, guides-theme-bootstrap, guides-theme-rst.
Fix, per the direction agreed in #1078:
- Flatten src// into src/ for the affected packages (guides-cli already uses this flat layout, so there's precedent in the monorepo).
- Declare a precise PSR-4 prefix per package, e.g.
"phpDocumentor\\Guides\\Markdown\\": "src/". - Do the moves in a dedicated commit with no other changes, so git recognizes them as renames rather than delete+add.
guides-restructured-text needs special handling: it has classes under both RestructuredText/ and a separate top-level PHPStan/ subtree, so it isn't a clean single-namespace-per-package fit like the others.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Compare the Composer PSR-4 declarations and src layouts in guides-code, guides-graphs, guides-markdown, guides-pages, guides-restructured-text, guides-theme-bootstrap, and guides-theme-rst with the flat layout in guides-cli and the direction from #1078. Flatten the affected namespaces, use precise package prefixes, and keep moves in a dedicated rename-only commit. Account separately for the PHPStan subtree in guides-restructured-text.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- build-system
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100