Class Not Found / Autoloader Failures
debt(d7/e3/b3/t7)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints note automated=no and the tool listed is composer (not a static linter). The error only surfaces at runtime when the class is actually instantiated, and the code_pattern 'Class .* not found' is a runtime fatal error, not a static analysis warning. It won't appear until the code path is exercised.
Closest to 'simple parameterised fix' (e3). The quick_fix describes a small set of checks: verify namespace matches directory structure (PSR-4), confirm file name case matches class name, and run composer dump-autoload. This is a small targeted fix within one component — not a one-liner swap but not a multi-file refactor either.
Closest to 'localised tax' (b3). The issue is scoped to the specific class or module that has the namespace/path mismatch. Once fixed, the rest of the codebase is unaffected. It applies broadly to web and cli contexts but each instance of the problem is localised to the offending class registration.
Closest to 'serious trap' (t7). The misconception field explicitly states: 'Class not found means the class doesn't exist — it usually means the autoloader can't find the file due to namespace/path mismatch.' This directly contradicts the obvious reading of the error message. A competent developer unfamiliar with PHP autoloading will waste significant time looking for a missing class definition rather than examining namespace/path alignment or running dump-autoload. The case-sensitivity trap (fatal on Linux, silent on macOS) compounds the confusion.
TL;DR
Explanation
PHP loads classes on demand via autoloaders registered with spl_autoload_register(). Composer generates a PSR-4 autoloader that maps namespace prefixes to directories. Common causes of 'class not found': wrong namespace (App\Models vs App\Model), file name doesn't match class name (case-sensitive on Linux), forgot to run composer dump-autoload after adding a new file, or class is in a file not included in autoload paths in composer.json. Debug with composer dump-autoload -v to see what's mapped.
Common Misconception
Why It Matters
Common Mistakes
- Wrong namespace declaration — namespace doesn't match directory structure.
- File name case mismatch (UserService.php vs userservice.php) — fatal on Linux, works on macOS.
- Forgetting composer dump-autoload after adding new classes.
Code Examples
// File: src/Services/userService.php
namespace App\Service; // Wrong: should be App\Services
class UserService {}// File: src/Services/UserService.php
namespace App\Services; // Matches PSR-4: App\\ => src/
class UserService {}
// composer.json:
// "autoload": {"psr-4": {"App\\\\": "src/"}}
// Run: composer dump-autoload