PHP RFC: Nested Classes

• Version: 0.5
• Date: 2025-02-08
• Author: Rob Landers, rob@bottled.codes
• Status: Under Discussion (Accepted or Declined)
• First Published at: http://wiki.php.net/rfc/short-and-inner-classes

This RFC proposes a significant enhancement to the PHP language: Nested Classes.

Nested classes allow the definition of one class within another, enabling tighter encapsulation and better organization of related logic. This feature naturally supports common design patterns such as Builders, DTOs, and serialization helpers, reducing boilerplate, minimizing namespace clutter, and clarifying code structure. Unlike some other languages, PHP nested classes do not implicitly capture the outer class instance, preserving explicit data flow and minimizing hidden coupling.

Nested classes allow defining classes (including enums) within other classes, interfaces, or enums, following standard visibility rules. This allows developers to declare a class as private or protected and restrict its usage to an outer class.

class Outer {
    public class Inner {
        public function __construct(public string $message) {}
    }
 
    private class PrivateInner {
        public function __construct(public string $message) {}
    }
}
 
$foo = new Outer\Inner('Hello, world!');
echo $foo->message;
// outputs: Hello, world!
$baz = new Outer\PrivateInner('Hello, world!');
// Uncaught TypeError: Cannot instantiate class Outer\PrivateInner from the global scope

Nested classes are just regular class definitions with visibility. That means, except where otherwise noted, “how would nested classes work in situation X?” can be answered with “the same as any other class/object.”

Nested classes are a powerful tool for organizing code and encapsulating functionality. Some use-cases include:

• Builder patterns: Nested classes can be used to create complex objects step-by-step, encapsulating the construction logic within the outer class.
• Data Transfer Objects (DTOs): Nested classes can be used to define data structures that are closely related to the outer class, improving code organization and readability.
• Serialization helpers: Nested classes can be used to define custom serialization logic for the outer class, encapsulating the serialization details within the outer class.
• Encapsulation: Nested classes can be used to encapsulate functionality that is only relevant to the outer class, reducing the visibility of the nested class and improving code organization.
• Namespace management: Nested classes can help reduce the number of top-level classes in a namespace, improving code organization and reducing clutter.

class Message {
    public function __construct(private string $message, private string $from, private string $to) {}
 
    public function Serialize(): string {
        return serialize(new SerializedMessage($this));
    }
 
    private class SerializedMessage {
        public string $message;
        public string $from;
        public string $to;
 
        public function __construct(Message $message) {
            $this->message = $message->message;
            $this->from = $message->from;
            $this->to = $message->to;
        }
    }
}

class Person {
    public class Builder {
        use AgeCalculator;
 
        private string $name;
        private DateTimeInterface $age;
 
        public function setName(string $name): self {
            $this->name = $name;
            return $this;
        }
 
        public function setBirthday(DateTimeInterface $age): self {
            $this->age = $age;
            return $this;
        }
 
        public function build(): Person {
            return new Person($this->name, $this->calculateAge($this->age));
        }
    }
 
    public function __construct(private string $name, private int $age) {}
}

enum Status {
    case Active;
    case Inactive;
 
    private enum Processing {
        case Pending;
        case Completed;
    }
 
    public class Message {
 
        private Processing $processing = Processing::Pending;
 
        public function __construct(private Status $status) {}
 
        public function getMessage(): string {
            return match ([$this->status, $this->processing]) {
                [Status::Active, Processing::Pending] => "Active and Pending",
                [Status::Active, Processing::Completed] => "Active and Completed",
                [Status::Inactive, Processing::Pending] => "Inactive and Pending",
                [Status::Inactive, Processing::Completed] => throw new LogicException('should not happen'),
            };
        }
    }
 
    public function createMessage(): Message {
        return new Message($this);
    }
}

interface Reader {
    public class Buffer {
        public string $bytes;
    }
 
    public function read(): void;
    public function getBuffer(): Buffer;
}
 
// in another file:
use Reader\Buffer;
 
class FileReader implements Reader {
    protected Buffer $buffer;
 
    public function __construct() {
        $this->buffer = new Buffer();
    }
 
    public function read(): void {
        $this->buffer->bytes = random_bytes(5);
    }
 
    public function getBuffer(): Buffer {
        return $this->buffer;
    }
}

PHP developers today often simulate nested classes through long namespace chains or anonymous classes embedded in methods. While these patterns work, they come with visibility challenges, verbosity, and a lack of cohesion between related types. Nested classes solve these problems natively, offering better encapsulation without requiring new runtime behavior or complex inheritance tricks.

Declaring a nested class uses the same syntax as declaring a top-level class. You can define readonly, final, and abstract nested classes. In addition, nested classes may be declared with visibility modifiers (private, protected, public), which determine where the nested class can be referenced or instantiated.

If a nested class does not explicitly declare visibility (private, protected, or public), it is implicitly considered public. This matches PHP’s existing class behavior for methods and properties.

class Outer {
    private class Inner {}
    protected readonly class ReadOnlyInner {}
    public abstract class AbstractInner {}
    public final class FinalInner {}
}

Outer classes remain “public” (accessible and visible to all), and visibility modifiers cannot be applied to them.

Visibility refers to whether a method, class, or property is accessible from outside its defining context. A nested class may be declared as private, protected, or public. A private class will only be visible within the lexical outer class, while a protected class is visible both inside its lexical scope and any child classes. A public class has no restrictions and will be visible from anywhere in the codebase.

All outer class’s properties and methods are visible from nested classes, as from the perspective of the nested class, it is a member of the outer class. However, unlike some languages with nested classes, an outer class does not have direct access to a nested class’s private or protected members.

Nested classes may only be used as a return type, property type, or argument type declarations for members that have the same visibility or less. Thus returning a protected type from a public method is not allowed, but is allowed from a protected or private method.

Attempting to declare a return of a non-visible type will result in a TypeError:

class Outer {
    private class Inner {}
 
    public function getInner(): Inner {
        return new Inner();
    }
}
 
// Fatal error: Uncaught TypeError: Public method getInner cannot return private class Outer\Inner
new Outer()->getInner();

This does not prevent the programmer from returning a hidden type, only from declaring it. The programmer may choose to use an interface or public type instead:

interface FooBar {}
 
class Outer {
    private class Inner implements FooBar {}
 
    public function getInner(): FooBar {
        return new Inner();
    }
}

The visibility of a type declaration on a property must also not increase the visibility of a nested class. Thus, a public property cannot declare a private type.

class Outer {
    private class Inner implements FooBar {}
 
    public function getInner(): FooBar {
        return new Inner(); // not an error
    }
}

Nested classes do not implicitly have access to an outer class instance. This design choice avoids implicit coupling between classes and keeps nested classes simpler, facilitating potential future extensions (such as adding an explicit outer keyword) without backward compatibility issues.

However, a programmer may pass an instance of an outer class (or another nested class) to a nested class. If a class has access to the outer class, it may use the outer class’s private, protected, and public properties and methods.

class Message {
    public function __construct(private string $message, private string $from, private string $to) {}
 
    public function Serialize(): string {
        return new SerializedMessage($this)->message;
    }
 
    private class SerializedMessage {
        public string $message;
 
        public function __construct(Message $message) {
            $this->message = strlen($message->from) . $message->from . strlen($message->to) . $message->to . strlen($message->message) . $message->message;
        }
    }
}

From a resolution perspective, outer classes behave as a pseudo-namespace. Using a short name of a nested class will resolve to the nested class. To disambiguate between different classes with the same name in the namespace and the nested class, the programmer can use fully qualified names.

class Inner {}
 
abstract class Outer {
    class Inner {}
    public function foo(Inner $i); // resolves to Outer\Inner
    public function bar(\Inner $i); // resolves to global Inner
}

This applies to deeply nested classes as well:

class Outer {
    class Middle {
        class Inner {}
    }
    public function foo(Middle\Inner $i); // resolves to Outer\Middle\Inner
}

This can lead to accidentally shadowing a class in the same namespace, thus requiring the use of use statements or fully qualified names to disambiguate.

Several new methods are added to ReflectionClass to help support inspection of nested classes:

$reflection = new ReflectionClass('\a\namespace\Outer\Inner');
 
$reflection->isNestedClass(); // true
$reflection->isPublic() || $reflection->isProtected() || $reflection->isPrivate(); // true
$reflection->getName(); // \a\namespace\Outer\Inner
$reflection->getShortName(); // Inner

For non-nested classes, ReflectionClass::isNestedClass() returns false.

A future addition to ReflectionClass::getNestedClasses() may allow enumeration of nested class declarations.

Since nested classes are referenced using standard -separated names, the engine treats them like any other class name during resolution. If the outer class has not yet been loaded, PHP will attempt to autoload the nested class name, which may result in fallback behavior depending on the autoloader. Implementers are encouraged to structure autoloaders to load the outer class when a nested class is referenced.

Nested classes may be defined in the body of any class-like structure, except traits:

• in a class body
• in an anonymous class body
• in an enum body
• in an interface body

Traits are not allowed to contain nested classes and are left to a future RFC. Traits are excluded from this RFC because nested class resolution via use statements introduces ambiguities about scope and visibility. These concerns are deferred to a future RFC.

Nested classes are fully independent of their outer class’s declaration modifiers. Outer class modifiers such as abstract, final, or readonly do not implicitly cascade down or affect the nested classes defined within them.

Specifically:

• An abstract outer class can define concrete (non-abstract) nested classes. Nested classes remain instantiable, independent of the outer class’s abstractness.
• A final outer class does not force its nested classes to be final. Nested classes within a final class can be extended internally, providing flexibility within encapsulation boundaries.
• A readonly outer class can define mutable nested classes. This supports internal flexibility, allowing the outer class to maintain immutability in its external API while managing state changes internally via nested classes.

Examples:

abstract class Service {
    // Valid: Nested class is not abstract, despite the outer class being abstract.
    public class Implementation {
        public function run(): void {}
    }
}
 
// Allowed; abstract outer class does not force nested classes to be abstract.
new Service\Implementation();

readonly class ImmutableCollection {
    private array $items;
 
    public function __construct(array $items) {
        $this->items = $items;
    }
 
    public function getMutableBuilder(): Builder {
        return new Builder($this->items);
    }
 
    public class Builder {
        private array $items;
 
        public function __construct(array $items) {
            $this->items = $items;
        }
 
        public function add(mixed $item): self {
            $this->items[] = $item;
            return $this;
        }
 
        public function build(): ImmutableCollection {
            return new ImmutableCollection($this->items);
        }
    }
}

In this example, even though Builder is a mutable nested class within a readonly outer class, the outer class maintains its immutability externally, while nested classes help internally with state management or transitional operations.

It is worth exploring what an abstract nested class means and how it works. Abstract nested classes are allowed to be the parent of any class that can see them. For example, a private abstract class may only be inherited by subclasses in the same outer class. A protected abstract class may be inherited by a nested class in a subclass of the outer class or a nested class in the same outer class. However, this is not required by subclasses of the outer class.

Abstract nested classes may not be instantiated, just as abstract outer classes may not be instantiated.

class OuterParent {
    protected abstract class InnerBase {}
}
 
// Middle is allowed, does not have to implement InnerBase
class Middle extends OuterParent {}
 
// Last demonstrates extending the abstract inner class explicitly.
class Last extends OuterParent {
    private abstract class InnerExtended extends OuterParent\InnerBase {}
}

• This RFC introduces new syntax and behavior to PHP, which does not conflict with existing syntax.
• Some error messages will be updated to reflect nested classes, and tests that depend on these error messages are likely to fail.
• Tooling using AST or tokenization may need to be updated to support the new syntax.

Note: Applying visibility modifiers to class declarations is new syntax, but only valid in nested contexts. Top-level classes will continue to behave as before, and this change introduces no ambiguity in existing code.

This RFC targets the next version of PHP.

None.

None were discovered during testing, but it is possible there are unbundled extensions that may be affected.

This change introduces a new AST, and other changes that affect opcache. These changes are included as part of the PR that implements this feature.

Tooling that uses AST or tokenization may need to be updated to support the new syntax, such as syntax highlighting, static analysis, IDEs, and code generation tools.

Pending discussion.

There should be no change to any existing PHP syntax.

• Inner interfaces
• Inner traits

This RFC focuses on class and enum nesting. Interfaces and traits are excluded for now due to their unique visibility and resolution semantics, but may be considered in follow-up RFCs.

As this is a significant change to the language, a 2/3 majority is required.

To be completed.

See: https://github.com/php/php-src/pull/18207 for a proof-of-concept implementation.

• email that inspired this RFC
• RFC: Records

TBD