Composer Autoloading classes not found

Composer Autoloading classes not found

  1. Blog
  2. 15 November 2026
  3. 4 min read

Stefan Bogdanescu

Founder & Senior Architect

Composer Autoloading classes not found

When you include vendor/autoload.php in your application and encounter a "Class not found" error despite having a valid composer.json configuration, the issue almost always lies in how the autoloader maps namespaces to file paths. In the scenario provided, the developer has defined a PSR-4 autoload rule mapping the Classes\ namespace to the includes/libraries/Classes/ directory. The code attempts to instantiate \Classes\Contact, yet the autoloader fails to locate includes/libraries/Classes/Contact.php.

The root cause here is a mismatch between the declared namespace in the file and the expected class name relative to that base path. Let's examine the specific configuration:

{
    "autoload": {
        "psr-4": {
            "Classes\\": "includes/libraries/Classes/"
        }
    }
}

This rule tells Composer: "If I see a class named Classes\Foo, look for the file at includes/libraries/Classes/Foo.php." The file structure confirms this location exists. However, inside Contact.php, the namespace declaration is simply:

namespace Classes;

And the class definition is:

class Contact { ... }

This results in a fully qualified class name of Classes\Contact. When you use use Classes\Contact; in your controller, the autoloader correctly interprets this as Classes\Contact and looks for includes/libraries/Classes/Contact.php. If the error persists, it is likely due to one of three specific reasons: missing cache regeneration, incorrect file permissions, or a subtle path mismatch.

The Cache Problem

The most common reason for "Class not found" errors after updating composer.json or moving files is that the autoloader map has not been regenerated. Composer caches the mapping between namespaces and file paths in vendor/composer/autoload_classmap.php. If you modify your composer.json, add new classes, or rename directories without touching the vendor directory, the old cache remains valid while your codebase changes.

You must run:

composer dump-autoload

This command regenerates all autoload files based on your current project structure. After running this command, ensure you are restarting your PHP process (e.g., clearing an opcode cache in production environments or restarting a long-running server) so the new vendor/autoload.php is loaded fresh. Without this step, PHP continues to use the old namespace-to-path mapping, leading to false negatives where valid classes appear missing.

Namespace and Class Name Alignment

It is critical that the class name inside the file matches exactly what your use statement expects. In the provided example, the file defines namespace Classes; and creates a class named Contact. This forms the namespace-qualified name Classes\Contact. The autoloader rule "Classes\\": "includes/libraries/Classes/" correctly resolves this to the physical path.

However, developers sometimes accidentally define the class with a different casing or add an extra backslash in the PHP file that breaks the PSR-4 resolution. For instance, if the file contained namespace Classes\Contact;, the autoloader would look for a subdirectory named Contact inside the base path, which does not exist. Always ensure the namespace declaration matches the intended hierarchy exactly.

File Structure and Base Path Nuances

Another potential pitfall is the placement of the vendor directory relative to your application root. The example shows includes/libraries/Classes/. If your composer.json is located in a subdirectory (e.g., admin/composer.json) rather than the project root, you must ensure that vendor/autoload.php is included from the correct context where the base path resolves correctly.

If you are running the script from a different directory, PHP's current working directory changes, but PSR-4 autoloading relies on absolute or relative paths defined in composer.json, not include_path. Ensure that the path "includes/libraries/Classes/" is relative to the directory containing composer.json. If your composer.json sits at the root of the project and your web server serves from a subdirectory, this usually works fine. However, if you move files around without updating the base path in composer.json, the resolution fails immediately.

Debugging Autoload Failures

If the above checks do not resolve the issue, inspect the autoloader's internal logic by enabling debug output. You can temporarily modify your bootstrap file to include:

require __DIR__ . '/vendor/autoload.php';
echo "Autoload map check:\n";
var_dump(\Classes\Contact::class); // Outputs the FQCN used by the autoloader

If the class still does not load, verify that the file includes/libraries/Classes/Contact.php is actually present and readable. Ensure there are no typos in the filename (e.g., contact.php instead of Contact.php). PHP filenames are case-sensitive on most servers, and PSR-4 expects the filename to match the class name exactly.

For more complex monolithic applications where mixing legacy include paths with Composer autoloading can cause confusion, consider isolating your autoloaded logic into a dedicated namespace or using a framework like Laravel, which handles these path mappings robustly out of the box. If you are building on top of a Laravel-like structure, ensuring your service providers register your classes correctly is often the key to avoiding these manual mapping headaches.

Our network