PHP Fatal error: Class not found - PHPUnit

PHP Fatal error: Class not found - PHPUnit

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

Stefan Bogdanescu

Founder & Senior Architect

PHP Fatal error: Class not found - PHPUnit

When you encounter a PHP Fatal error: Class 'controllers\Pages' not found while running PHPUnit, the error message can be misleading if you interpret it literally. It tells you that the class name \controllers\Pages was requested but could not be resolved in the current namespace context. In your specific case, this isn't just a random path issue; it is a fundamental failure to map your source files to their corresponding PHP namespaces.

The error originates from tests/pagesTest.php at line 7, where you instantiate \controllers\Pages. You are using the global namespace prefix (\) to tell PHP, "Find this class relative to the root of my application." However, PHPUnit's autoloader does not magically know where your source code lives unless you configure it or rely on a standard directory structure that matches your namespace declarations.

Let's look at your Pages.php file:

<?php
namespace controllers

class Pages
{
    public function render()
    {
        return 'Hello World';
    }
}

You have declared the class within the controllers namespace. For PHP to find this class when you reference it as \controllers\Pages, the physical file structure must mirror that namespace hierarchy relative to your autoload base path. By convention, a class in the controllers namespace should reside in a directory named controllers directly under your project root.

Your current project layout places Pages.php at C:\xampp\htdocs\PHPUnitTestProject\controllers\Pages.php, which seems correct for the file system. However, the error suggests PHPUnit is looking for it in the wrong place or failing to load the autoloader entirely before attempting to resolve the class.

The root cause here is often how PHPUnit discovers classes when running a specific test file directly versus running them via the bootstrap mechanism. When you execute phpunit ../../tests/PagesTest.php from the vendor/bin directory, you are invoking the CLI tool without explicitly telling it about your project's autoloader configuration.

In modern setups using Composer, PHPUnit expects to find a vendor/autoload.php and often relies on the composer.json file to define how classes are loaded. Your composer.json currently only lists PHPUnit as a dev dependency but lacks an autoload or autoload-dev section that maps your own source directories to namespaces. Without this mapping, Composer's autoloader has no idea that the controllers namespace corresponds to the controllers folder.

To fix this, you have two primary paths forward depending on your workflow. The most robust method is to configure your composer.json to handle your project's code automatically:

{
    "autoload": {
        "psr-4": {
            "controllers\\": "controllers/"
        }
    },
    "require-dev": {
        "phpunit/phpunit": "^5.5"
    }
}

After updating this file, you must run composer dump-autoload to regenerate the autoloader map. Then, instead of running PHPUnit directly from vendor/bin, you should invoke it through Composer:

./vendor/bin/phpunit tests/PagesTest.php

This ensures that when PHPUnit encounters \controllers\Pages, it delegates the resolution to your custom autoloader, which will correctly locate the file in the controllers directory.

Alternatively, if you prefer not to use Composer's autoloading for your test suite or want to stick with a simpler approach, you can manually load your project's files before running PHPUnit. However, relying on manual require statements is fragile and defeats the purpose of namespaced classes. The trade-off with configuring the autoload section in composer.json is that it adds a slight overhead to the autoloading process for every request, but for development and testing environments, this is negligible compared to the reliability gain.

Another critical detail in your test file is the use of PHPUnit_Framework_TestCase. This class name belongs to PHPUnit 4.x and early 5.x versions. You specified version 5.5.4, which still uses the old naming convention, but if you ever upgrade PHPUnit, you will need to switch to PHPUnit\Framework\TestCase in your test files as well. While not the cause of the current error, it is a common pitfall when upgrading dependencies without updating the test code simultaneously.

Finally, ensure that your working directory is set correctly. Running PHPUnit from vendor/bin often confuses path resolution if the script expects to be run from the project root. If you must run it from vendor/bin, you might need to adjust the script arguments or use the --bootstrap option to load your own custom bootstrap file that requires your source files explicitly. However, the cleanest solution remains configuring the autoload map in composer.json.

Our network