What Are the Differences Between PSR-0 and PSR-4?
When migrating a Laravel application from classmap autoloading to namespaced classes, the distinction between PSR-0 and PSR-4 often becomes a source of confusion. The core issue isn't just about "namespaces"; it is fundamentally about how the autoloader maps a fully qualified class name to a specific file path on your disk.
The Core Problem: Underscores vs. Directories
The primary architectural difference lies in how each standard handles underscores (_) within class names. Under PSR-0, underscores are treated as directory separators. This means that if you have a class named Some_Class_Name, the autoloader expects to find it at a path containing slashes: some/class/name.php.
PSR-4, introduced later to address the verbosity and complexity of PSR-0, treats underscores strictly as namespace delimiters within the file path itself. In a PSR-4 structure, the class name Some_Class_Name must reside in a directory literally named Some_Class_Name. The underscore is not converted into a slash; it remains part of the folder or filename hierarchy.
This distinction simplifies the mental model for developers. With PSR-0, every time you added an underscore to a class name, you were forced to add a new directory level. PSR-4 allows you to keep your namespace structure flat while maintaining readable class names.
Configuration Mechanics in Composer
The practical impact of this difference becomes evident when configuring composer.json. In a PSR-0 setup, the psr-0 map required explicit rules for every namespace prefix and its corresponding base directory. If you wanted to support multiple namespaces with underscores, your configuration grew linearly with complexity.
{
"autoload": {
"psr-0": {
"My_Project_": "src/",
"Another_Namespace_": "lib/"
}
}
}
In contrast, PSR-4 utilizes the base namespace as a directory prefix. You define the root directory of your project in autoload_psr_4_classes, and Composer automatically appends the remaining parts of the class name to that path. Crucially, it does not perform any string replacement on underscores.
{
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
If you have a class App\\Core\\User_Controller, PSR-4 expects the file at src/Core/User_Controller.php. If you attempted to place it at src/Core/User/Controller.php (converting the underscore to a slash), the autoloader would fail to find it. This strict mapping eliminates the ambiguity that plagued PSR-0 implementations.
Why PSR-4 Became the Standard
The shift to PSR-4 was driven by the need for scalability and readability. As projects grew, maintaining complex psr-0 maps became error-prone. Developers often had to manually manage directory structures that didn't intuitively match their class names. The "complex rules" mentioned in migration guides refer to these manual mappings and the necessity of converting underscores to slashes just to make the file system align with the namespace definition.
By adopting PSR-4, you remove the requirement for directory-level separation between every underscored segment of a class name. This allows for deeper nesting of namespaces without creating overly deep folder structures on the filesystem. For example, a deeply nested namespace like Vendor\\Library\\SubComponent can be organized as vendor/library/sub_component.php in PSR-4, whereas PSR-0 would require three separate directories: vendor, library, and sub-component.
Migrating Your Laravel Project
When moving an existing Laravel project away from classmap autoloading, you must ensure your classes adhere to the PSR-4 standard. This involves restructuring your codebase so that directory names match the namespace exactly, including any underscores present in the class name itself.
You do not need to manually convert underscores to slashes in your file paths. Instead, you should refactor your files to maintain the underscore within the directory or filename if the class name contains one. Once the structure is corrected, updating composer.json to use the psr-4 autoload section and running composer dump-autoload will generate the optimized autoloader without errors.
For teams looking for deeper insights into these standards, resources like Laracasts provide excellent visual breakdowns of how PSR-4 autoloading functions under the hood. Understanding these mechanics ensures that your application remains maintainable as it scales.