phpDocumentor / phpDocumentor/guides

Use precise PSR-4 autoload prefixes and flatten src/<Namespace>/ across packages

Open
#1,375 0 comments 0 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.