Why Did Moving My PHP Class Break Everything? Understanding Composer’s Autoloader

Have you ever moved a PHP class file to a different directory, only to be greeted with this dreaded error?

Internal Server Error
ErrorException
include(/var/www/html/vendor/composer/../../app/Services/Old/UserService.php): 
Failed to open stream: No such file or directory

Let's understand what's actually going on under the hood.

The Problem: Moving Files Breaks Things

Consider this scenario: You have a PHP class in app/Services/Old/UserService.php, and you decide to move it to app/Services/UserService.php. You update the namespace, move the file, but suddenly your application breaks. Why? The answer lies in Composer's autoloader.

What is Autoloading?

In the old days of PHP, you had to manually include every class file you needed:

require_once 'classes/User.php';
require_once 'classes/Order.php';
require_once 'classes/Product.php';
// ... and so on

This was:

• Error-prone
• Hard to maintain
• Inefficient (you might load files you don't need)

Enter autoloading. Modern PHP uses an autoloader that automatically loads class files when they're needed. When you write:

$user = new App\Services\UserService();

PHP asks the autoloader: "Where can I find this class?"

How Composer Fits In

Composer isn't just a package manager - it's also responsible for generating the autoloader that PHP uses. It creates a map that tells PHP:

• Which namespaces exist in your application
• Where to find the files for each namespace
• How to efficiently load them

This mapping is defined in your composer.json:

{
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}

This tells Composer: "When someone tries to use a class in the App namespace, look for it in the app directory."

The Cache Problem

For performance reasons, Composer doesn't scan your filesystem every time it needs to find a class. Instead, it:

1. Creates a cached map of class locations
2. Uses this cache to quickly look up files

When you move a file, this cache becomes outdated. The autoloader is still looking in the old location!

The Solution: dump-autoload

The solution is simple: tell Composer to rebuild its autoloader cache:

composer dump-autoload

This command:

• Scans your project directories
• Creates a fresh map of class locations
• Updates the autoloader cache

When Do You Need dump-autoload?

Run composer dump-autoload when you:

• Move class files to different directories
• Change namespaces
• Add new classes that aren't in a location Composer knows about
• Modify the autoload configuration in composer.json

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com