PHP namespaces and "use"

PHP namespaces and "use"

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

Stefan Bogdanescu

Founder & Senior Architect

Why include Works but use Fails in PHP Namespaces

When you move code into namespaces, the mental model shifts from "files containing classes" to "fully qualified class names." A common stumbling block occurs when developers try to mix static file loading (include, require) with dynamic name resolution (use). The specific error you are encountering—Fatal error: Class 'Shape\Shape' not found—isn't a bug in PHP; it is a direct consequence of how the autoloader and the include mechanism interact within a namespace context.

In your current setup, you have three files residing in the same directory: ShapeInterface.php, Shape.php, and Circle.php. All of them declare the default namespace as Shape. Inside Circle.php, you are relying on relative path includes to load the other files.

When you execute include 'Shape.php', PHP physically loads the file content into memory. It parses the code and registers the class Shape\Shape in the global namespace map. Because the file is executed, the class definition happens regardless of whether you have an explicit use statement pointing to it. The same logic applies to ShapeInterface. Since the files are physically present and included by name, PHP finds them without needing a mapping function.

The moment you uncomment the use Shape; or use Shape\ShapeInterface; statements, however, the behavior changes entirely. A use statement does not load files; it is a compile-time directive that tells the parser to look up a specific fully qualified class name in the current namespace scope. When PHP processes the line use Shape;, it searches for a class named Shape\Shape.

Here lies the conflict:

  1. The Namespace: You are inside the Shape namespace.
  2. The Lookup: The parser looks for a class named Shape\Shape relative to the current scope. This resolves to the string Shape\Shape.
  3. The Reality: At this exact moment in the execution flow, before the include 'Shape.php' line runs, that class has not been defined yet.

Even if you were in the global namespace (no namespace block), writing use Shape; would look for a top-level class named Shape. But because you are inside namespace Shape;, the relative lookup becomes absolute. The parser is essentially asking, "Where is the class Shape\Shape?" and it finds nothing because the file inclusion hasn't happened yet to register that name.

The Autoloader vs. Static Includes

To solve this without relying on fragile include statements, you should leverage an autoloader or a dependency manager like Composer. Relying on relative includes inside a class file that also defines namespacing is generally considered an anti-pattern in larger applications because it creates tight coupling and bypasses the standard PSR-4 discovery rules.

If you are building a small script and must stick with include, you must remove the use statements entirely. The classes will resolve correctly based on their fully qualified names once the files are included. You might end up writing:

namespace Shape;

include 'Shape.php';
include 'ShapeInterface.php';

class Circle extends Shape implements ShapeInterface {
    // Implementation details here
}

This works because extends and implements keywords resolve names relative to the current namespace after the classes are defined. You don't need use for inheritance when you already know the file path and structure.

However, if you want to use use, you must separate the definition from the loading logic. Typically, this means placing your base classes in a separate directory or using a PSR-4 autoloader where the namespace matches the directory structure. For example, if Shape.php is located at src/Shape/Shape.php, the code would be:

# Directory structure
src/
  Shape/
    ShapeInterface.php
    Shape.php
    Circle.php

With this structure, you wouldn't use relative includes. Instead, you would configure an autoloader in your entry point (like index.php or a Laravel application) to map the Shape namespace to the src/Shape directory. This allows the use Shape\Shape; statement to work seamlessly because the autoloader intercepts the missing class error and loads the correct file before execution continues.

When to Use Which Approach

The decision between include and an autoloader depends on your project scale. In a monolithic script with all files in one directory, omitting use statements is acceptable as long as you accept the verbosity of fully qualified names or rely on the include order. This approach has zero overhead but lacks flexibility.

If you are using Laravel, the framework's service container and autoloading system handle these dependencies automatically. In that context, you rarely need to manually include files or write explicit use statements for local classes unless you are defining traits or importing specific constants from a different namespace entirely. For more on managing dependencies in modern PHP stacks, you might find the LaravelCompany guide useful for understanding how dependency injection interacts with namespaces.

Ultimately, the error occurs because use expects the class to be defined before the line is processed, whereas your include statements haven't run yet. Removing the use directives when using static includes resolves the immediate issue, while adopting an autoloader provides a scalable path forward for larger applications.

Our network