Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

PHP says Class not found, but the file is there

ErrorFatal error: Class 'Mailer' not found

Short answer

PHP finds a class only if the file defining it was already loaded or an autoloader can map the name to a file. Three things break that: vendor/autoload.php is never required, the namespace does not match the PSR-4 mapping in composer.json, or the generated autoloader is stale and needs dump-autoload.

  • Applies to PHP 8.3, PHP 8.4, Composer 2.8
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask Composer's autoloader what it knows about the class. If it prints nothing, the map is wrong or stale; if it prints a path, the autoloader is not being loaded.

    composer dump-autoload -o
    php -r 'require "vendor/autoload.php"; var_dump(class_exists("App\\Service\\Mailer"));'
  2. 2Match what you see, then jump to its fix

    1. 1The failing script is an entry point that does not start with require 'vendor/autoload.php'.The autoloader file is never requiredFix
    2. 2The autoloader is loaded, class_exists prints false for this one class.The namespace does not match the PSR-4 mappingFix
    3. 3The class exists on disk and the mapping is right, but it was added or moved after the last install.The generated autoloader is out of dateFix

What does the error look like?

  • Fatal error: Class 'Mailer' not found
  • Class not found, although the file is included

Cause 1 of 3

The autoloader file is never required

1Check

The manual says an autoloader is PHP's last chance to load a class before it fails. It must be registered before the class is first used, so look at the top of the entry file.

grep -rn "vendor/autoload.php" public/ index.php 2>/dev/null

2Fix

Require the Composer autoloader once, at the start of the entry script, with a path that works from there.

<?php
require __DIR__ . '/../vendor/autoload.php';

3Verify

The class_exists probe prints true when run through that entry file.

php public/index.php

Confirmed by php.net

Did this fix it?

Cause 2 of 3

The namespace does not match the PSR-4 mapping

1Check

A psr-4 entry maps a namespace prefix to a folder, and the prefix is not part of the file path. The prefix has to end in two backslashes in JSON, and the rest of the class name has to follow the folder layout.

grep -n -A3 '"psr-4"' composer.json

2Fix

Make composer.json, the namespace line and the folder agree, for example App\ pointing at src/ and src/Service/Mailer.php declaring namespace App\Service.

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

3Verify

Rebuild and probe the class again.

composer dump-autoload
php -r 'require "vendor/autoload.php"; var_dump(class_exists("App\\Service\\Mailer"));'

Confirmed by getcomposer.org

Did this fix it?

Cause 3 of 3

The generated autoloader is out of date

1Check

Composer generates the autoloader files on install; the classmap form is built by scanning the folders at that time. A class added later is missing from a classmap-only autoloader.

composer dump-autoload --classmap-authoritative

2Fix

Regenerate the autoloader without a full install. Do not use the authoritative flag in development, where classes change often.

composer dump-autoload

3Verify

The probe from the first step prints true.

php -r 'require "vendor/autoload.php"; var_dump(class_exists("App\Service\Mailer"));'

Confirmed by getcomposer.org

Did this fix it?

How do I stop it coming back?

  • One class per file, with the file path following the namespace.
  • Run composer dump-autoload as part of the deploy script.
  • Do not mix manual require calls with Composer autoloading for the same classes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.