Class Not Found / Autoloader Failures

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

References

• ↗ https://getcomposer.org/doc/01-basic-usage.md#autoloading

Tags

Related Terms