Differences

This shows you the differences between two versions of the page.

--- rfc:short-and-inner-classes [2025/02/22 20:30] – reword some sections withinboredom
+++ rfc:short-and-inner-classes [2025/03/15 10:28] (current) – reword and clarify withinboredom
@@ Line 1: / Line 1: @@
-====== PHP RFC: Inner Classes with Short Syntax ======
+====== PHP RFC: Inner Classes ======
-  * Version: 0.1
+  * Version: 0.4
   * Date: 2025-02-08
   * Author: Rob Landers, <rob@bottled.codes>
-  * Status: Draft (or Under Discussion or Accepted or Declined)
+  * Status: Under Discussion (Accepted or Declined)
   * First Published at: http://wiki.php.net/rfc/short-and-inner-classes
 ===== Introduction =====
-PHP has steadily evolved to enhance developer productivity and expressiveness, introducing features such as typed properties, constructor property promotion, and first-class callable syntax. However, defining simple data structures and organizing classes remains verbose.
+This RFC proposes a significant enhancement to the language: **Inner Classes**. Inner classes enable the definition of classes within other classes, introducing a new level of encapsulation and organization within PHP applications.
-This RFC proposes two related enhancements to PHP:
+**Inner Classes** allows for the ability to define classes within other classes and control the use of inner classes through visibility. Many languages allow the encapsulation of behavior through inner classes (sometimes called **nested classes**), such as Java, C#, and many others.
-**Short class syntax**, allowing simple or data-oriented classes to be defined in a single line:
+PHP developers currently rely heavily on annotations (e.g., @internal) or naming conventions to indicate encapsulation of Data Transfer Objects (DTOs) and related internal classes. These approaches offer limited enforcement, causing potential misuse or unintended coupling.
+This RFC introduces Inner Classes to clearly communicate and enforce boundaries around encapsulated classes, facilitating well-known design patterns (e.g., Builder, DTO, serialization patterns) with native language support. This reduces boilerplate, enhances clarity, and ensures internal types remain truly internal.
+===== Proposal =====
+Inner classes allow defining classes within other classes, following standard visibility rules. This allows developers to declare a class as ''%%private%%'' or ''%%protected%%'' and restrict its usage to the outer class. They are accessed via a new operator: ''%%:>%%'' which is a mixture of ''%%->%%'' and ''%%::%%''.
 <code php>
-class Point(int $x, int $y);
+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!');
+// Fatal error: Class 'Outer:>PrivateInner' is private
 </code>
-This syntax acts as a shorthand for defining classes with constructor property promotion, reducing boilerplate while maintaining clarity.
+Inner classes are just regular class definitions with a couple additional features. That means, except where otherwise noted, "how would inner classes work in situation X?" can be answered with "the same as any other class/object."
-**Inner classes**, enabling the definition of classes within other classes with visibility control:
+==== Declaration Syntax ====
+Declaring an inner class is just like declaring any other class. You can define ''%%readonly%%'', ''%%final%%'', and ''%%abstract%%'' inner classes -- or combinations, for example. However, when defining an inner class, you may also define it as ''%%private%%'', ''%%protected%%'', or ''%%public%%''.
+If an inner 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.
 <code php>
-class Foo {
+class Outer {
-    public class Bar(public string $message);
+    private class Inner {}
+    protected readonly class ReadOnlyInner {}
+    public abstract class AbstractInner {}
+    public final class FinalInner {}
 }
 </code>
-===== Proposal =====
+If an inner class is not defined as ''%%private%%'', ''%%protected%%'', or ''%%public%%'', it is assumed to be ''%%public%%''.
-==== Short Class Syntax ====
+==== Syntax rationale ====
-The proposed syntax for defining a short class consists of the class keyword, followed by the class name, and a list of properties in parentheses. Optionally, traits, interfaces, and a parent class can be specified.
+The ''%%:>%%'' syntax was selected after evaluating alternatives:
-<code php>
+  * Using ''%%::%%'' was cumbersome and visually ambiguous due to existing static resolution syntax.
+  * Using ''%%\%%'' or ''%%\\%%'' was rejected due to potential conflicts with namespaces and escaping, causing confusion.
-// a simple class with two public properties
+''%%:>%%'' communicates "inner membership," visually linking the inner class to the outer class.
-class Point(int $x, int $y);
-// A readonly class with a parent class, interface, and traits
+==== Binding ====
-readonly class Vector(int $x, int $y) extends BaseVector implements JsonSerializable use PointTrait, Evolvable;
-</code>
-This is equivalent to the following full class definition:
+Inner classes are explicitly bound to their outer classes and are intentionally not inherited through subclassing, traits, or interfaces. This prevents ambiguity or complexity arising from inheriting tightly bound encapsulated logic.
 <code php>
-class Point {
+class Outer {
-    public function __construct(public int $x, public int $y) {}
+    class OuterInner {}
+}
+interface Foo {
+    class FooInner {}
+}
+trait Bar {
+    class BarInner {}
 }
-readonly public class Vector extends BaseVector implements JsonSerializable {
+class All extends Outer implements Foo {
-    use PointTrait, Evolvable;
+    use Bar;
-    public function __construct(public int $x, public int $y) {}
+    public function does_not_work() {
+        new self:>OuterInner(); // Fatal error: Class 'All:>OuterInner' not found
+        new self:>FooInner(); // Fatal error: Class 'All:>FooInner' not found
+        new self:>BarInner(); // Fatal error: Class 'All:>BarInner' not found
+        new parent:>OuterInner(); // This does work because it resolves to Outer:>OuterInner
+    }
 }
 </code>
-Properties inside parentheses are automatically declared as class properties and default to public unless explicitly specified:
+=== static resolution ===
+The ''%%static%%'' keyword is **not** supported to resolve inner classes. Attempting to do so results in an error, depending on where it is used:
 <code php>
-// declare $shapes as a private property
+class Outer {
-class Geometry(private $shapes) use GeometryTrait;
+    class Inner {}
+    // Fatal error: Cannot use the static modifier on a parameter
+    public function foo(static:>Inner $bar) {}
+    // Parse error: syntax error, unexpected token ":>", expecting ";" or "{"
+    public function bar(): static:>Inner {}
+    // Fatal error: Cannot use "static" as class name, as it is reserved
+    class Baz extends static:>Inner {}
+    public function foobar() {
+        return new static:>Inner(); // Fatal error: Cannot use the static modifier on an inner class
+    }
+}
 </code>
-=== Default Values ===
+This is to prevent casual LSP violations of inheritance and to maintain the strong binding of inner classes.
-Properties with type hints may have default values:
+=== parent resolution ===
+The ''%%parent%%'' keyword is supported to resolve inner classes. Which parent it resolves to depends on the context:
 <code php>
-class Point(int $x = 0, int $y = 0);
+class Foo {
+    class Bar {}
+}
+class Baz extends Foo {
+    // parent:>Bar resolves to Foo:>Bar
+    class Bar extends parent:>Bar {
+        // inside the class body, parent refers to Foo:>Bar
+        public function doSomething(): parent {}
+    }
+}
 </code>
-=== Inheritance and Behavior ===
+''%%parent%%'' explicitly resolves to the parent class of the current class body it is written in and helps with writing more concise code.
-Short classes can extend other classes, implement interfaces, and use traits, but they cannot define additional methods. The parent class constructor is overridden and not automatically called.
+=== self resolution ===
+The ''%%self%%'' keyword is supported to resolve inner classes. Which ''%%self%%'' it resolves to depends on the context:
 <code php>
-class Point(int $x, int $y) extends BasePoint implements JsonSerializable use PointTrait, Evolvable;
+class Outer {
+  class Middle {
+    class Other {}
+    // extends Outer:>Middle:>Other
+    class Inner extends self:>Other {
+        public function foo(): self {} // returns Outer:>Middle:>Inner
+    }
+  }
+}
 </code>
-=== Empty Classes ===
+''%%self%%'' explicitly resolves to the current class body it is written in, just like with ''%%parent%%''. On ''%%inner%%'' classes.
-Short classes may be empty:
+When using self inside a class body to refer to an inner class, if the inner class is not found in the current class, it will fail with an error.
 <code php>
-class Point() extends BasePoint use PointTrait;
+class OuterParent {
+    class Inner {}
+    class Other {}
+}
+class MiddleChild extends OuterParent {
+    // Fatal Error: cannot find class MiddleChild:>InnerParent
+    class Inner extends self:>InnerParent {}
+}
+class OuterChild extends OuterParent {
+    class Inner {}
+    public function foo() {
+        $inner = new self:>Inner(); // resolves to OuterChild:>Inner
+        $inner = new parent:>Inner(); // resolves to OuterParent:>Inner
+        $inner = new self:>Other(); // Fatal Error: cannot find class OuterChild:>Other
+        $inner = new parent:>Other(); // resolves to OuterParent:>Other
+    }
+}
 </code>
-=== Attributes ===
+=== Dynamic resolution ===
-Attributes can be used with short classes:
+Just as with ''%%::%%'', developers may use variables to resolve inner classes, or refer to them by name directly via a string:
 <code php>
-#[MyAttribute]
+// Using variables to dynamically instantiate inner classes:
-class Password(#[SensitiveParameter] string $password);
+$outer = "Outer";
+$inner = "Inner";
+$instance = new $outer:>$inner();
+// Instantiating inner class dynamically via a fully qualified class string:
+$dynamicClassName = "Outer:>Inner";
+$instance = new $dynamicClassName();
 </code>
-=== Modifiers ===
+This provides flexibility and backwards compatibility for dynamic code that may not expect an inner class.
-Short classes support readonly, final, and abstract:
+==== Visibility from inner classes ====
+Inner classes have access to their outer class’s private and protected methods, properties, and inner classes. However, they do not have access to their siblings’ private and protected methods, properties, and inner classes.
 <code php>
-readonly class User(int $id, string $name);
+class User {
+    public private(set) string $name;
+    public private(set) string $email;
+    private function __construct(self:>Builder $builder) {
+        $this->name = $builder->name;
+        $this->email = $builder->email;
+    }
+    public readonly final class Builder {
+        public function __construct(public private(set) string|null $name = null, public private(set) string|null $email = null) {}
+        public function withEmail(string $email): self {
+            return new self($this->name, $email);
+        }
+        public function withName(string $name): self {
+            return new self($name, $this->email);
+        }
+        public function build(): User {
+            return new User($this);
+        }
+    }
+}
-final class Config(string $key, mixed $value);
+$user = new User:>Builder()->withName('Rob')->withEmail('rob@bottled.codes')->build();
-abstract class Shape(float $area);
 </code>
-=== How it works ===
+This enables usages such as builder patterns and other helper classes to succinctly encapsulate behavior.
-Short classes are purely syntactic sugar and compile into standard class definitions.
-==== Inner Classes ====
+==== Visibility from outside the outer class ====
-Inner classes allow defining classes within other classes, following visibility rules:
+Inner classes are not visible outside their outer class unless they are public. Protected classes may be used and accessed from within their child classes.
 <code php>
 class Outer {
-    class Inner(public string $message);
+    private class Other {}
+    protected class Inner {
-    private class PrivateInner {
+        public function Foo() {
-        public function __construct(public string $message) {}
+            $bar = new Outer:>Inner(); // allowed
+            $bar = new Outer:>Other(); // allowed
+        }
     }
 }
-$foo = new Outer::Inner('Hello, world!');
+class SubOuter extends Outer {
-echo $foo->message;
+    public function Foo() {
-// outputs: Hello, world!
+        $bar = new parent:>Inner(); // allowed to access protected inner class
-$baz = new Outer::PrivateInner('Hello, world!');
+        $bar = new parent:>Other(); // Cannot access private inner class 'Outer:>Other'
-// Fatal error: Uncaught Error: Cannot access private inner class Outer::PrivateInner
+    }
+}
 </code>
-=== Modifiers ===
+Attempting to instantiate a private or protected inner class outside its outer class will result in a fatal error:
+<code php>
+new Outer:>Inner(); // Cannot access protected inner class 'Outer:>Inner'
+</code>
-Inner classes support modifiers such as ''%%public%%'', ''%%protected%%'', ''%%private%%'', ''%%final%%'' and ''%%readonly%%''. When using these as modifiers on an inner class, there are some intuitive rules:
+=== Method return type and argument declarations ===
-  * ''%%public%%'', ''%%private%%'', and ''%%protected%%'' apply to the visibility of the inner class.
+Inner classes may only be used as a return type or argument declarations for methods and functions that have the same visibility or lesser. Thus returning a ''%%protected%%'' class type from a ''%%public%%'' method is not allowed, but is allowed from a ''%%protected%%'' or ''%%private%%'' method.
-  * ''%%final%%'', and ''%%readonly%%'' apply to the class itself.
-  * ''%%static%%'' is not allowed as a modifier since PHP does not support static classes.
-  * ''%%abstract%%'' is not allowed as an inner class cannot be parent classes.
-=== Visibility Rules ===
+^Inner Class Visibility^Method Visibility^Allowed^
+|''%%public%%''        |''%%public%%''   |Yes    |
+|''%%public%%''        |''%%protected%%''|Yes    |
+|''%%public%%''        |''%%private%%''  |Yes    |
+|''%%protected%%''     |''%%public%%''   |No     |
+|''%%protected%%''     |''%%protected%%''|Yes    |
+|''%%protected%%''     |''%%private%%''  |Yes    |
+|''%%private%%''       |''%%public%%''   |No     |
+|''%%private%%''       |''%%protected%%''|No     |
+|''%%private%%''       |''%%private%%''  |Yes    |
-Private and protected inner classes are only accessible within their outer class (or subclasses for protected):
+Methods and functions outside the outer class are considered public from the perspective of an inner class. Attempting to declare a return of a non-visible type will result in a ''%%TypeError%%'':
 <code php>
 class Outer {
-    private class PrivateInner(string $message);
+    private class Inner {}
-    public function getInner(): self::PrivateInner {
+    public function getInner(): self:>Inner {
-        return new self::PrivateInner('Hello, world!');
+        return new self:>Inner();
     }
 }
-// using a private inner class from outside the outer class, as a type hint is forbidden
+// Fatal error: Uncaught TypeError: Public method getInner cannot return private class Outer:>Inner
-function doSomething(Outer::PrivateInner $inner) {
+new Outer()->getInner();
-    echo $inner->message;
-}
-// this is ok:
-$inner = new Outer()->getInner();
-// but this is not:
-doSomething($inner);
-// Fatal error: Private inner class Outer::Inner cannot be used in the global scope
 </code>
-Just like with other languages that support inner classes, it is better to return an interface or a base class from a method instead of exposing a private/protected class.
+=== Properties ===
-You may also not instantiate a private/protected class from outside the outer class’s scope:
+The visibility of a type declaration on a property must also not increase the visibility of an inner class. Thus, a public property cannot declare a private type.
+This gives a great deal of control to developers, preventing accidental misuse of inner classes. However, this **does not** preclude developers from returning a private/protected inner class, only from using them as a type declaration. The developer can use an interface or abstract class type declaration, or use a broader type such as ''%%object%%'', ''%%mixed%%'', or nothing at all:
 <code php>
-$x = new Outer::PrivateInner();
+class Outer {
-// Fatal error: Uncaught Error: Cannot access private inner class Outer::Inner
+    private class Inner implements FooBar {}
+    public function getInner(): FooBar {
+        return new self:>Inner(); // not an error
+    }
+}
 </code>
-=== Inheritance ===
+==== Accessing outer classes ====
-Inner classes have inheritance similar to static properties; this allows you to redefine an inner class in a subclass, allowing rich hierarchies.
+Inner classes do not implicitly have access to an outer class instance. This design choice avoids implicit coupling between classes and keeps inner classes simpler, facilitating potential future extensions (such as adding an explicit outer keyword) without backward compatibility issues.
-<code php>
+Passing an outer instance explicitly remains an available option for accessing protected/private methods or properties. Thus inner classes may access outer class private/protected methods and properties if given an instance.
-readonly class Point(int $x, int $y);
-class Geometry {
+<code php>
-    public array $points;
+class Message {
-    protected function __construct(Point ...$points) {
+    public function __construct(private string $message, private string $from, private string $to) {}
-        $this->points = $points;
-    }
-    public class FromPoints extends Geometry {
+    public function Serialize(): string {
-        public function __construct(Point ...$points) {
+        return new Message:>SerializedMessage($this)->message;
-            parent::__construct(...$points);
-        }
     }
-    public class FromCoordinates extends Geometry {
+    private class SerializedMessage {
-        public function __construct(int ...$coordinates) {
+        public string $message;
-            $points = [];
-            for ($i = 0; $i < count($coordinates); $i += 2) {
+        public function __construct(Message $message) {
-                $points[] = new Point($coordinates[$i], $coordinates[$i + 1]);
+            $this->message = strlen($message->from) . $message->from . strlen($message->to) . $message->to . strlen($message->message) . $message->message;
-            }
-            parent::__construct(...$points);
         }
     }
 }
+</code>
-class Triangle extends Geometry {
+==== Reflection ====
-    protected function __construct(public Point $p1, public Point $p2, public Point $p3) {
-        parent::__construct($p1, $p2, $p3);
+Several new methods are added to ''%%ReflectionClass%%'' to help support inspection of inner classes:
+<code php>
+$reflection = new ReflectionClass('\a\namespace\Outer:>Inner');
+$reflection->isInnerClass(); // true
+$reflection->isPublic() || $reflection->isProtected() || $reflection->isPrivate(); // true
+$reflection->getName(); // \a\namespace\Outer:>Inner
+$reflection->getShortName(); // Outer:>Inner
+</code>
+For non-inner classes, ''%%ReflectionClass::isInnerClass()%%'' returns false.
+==== Autoloading ====
+Inner classes are never autoloaded, only their outermost class is autoloaded. If the outermost class does not exist, then their inner classes do not exist.
+==== Usage ====
+Inner classes may be defined in the body of any class-like structure, including but not limited to:
+  * in a class body
+  * in an anonymous class body
+  * in an enum body
+  * in a trait body
+  * in an interface body
+Note: While traits and interfaces may define inner classes, classes using these traits or implementing these interfaces do not inherit their inner classes. Inner classes remain strictly scoped and bound to their defining context only.
+==== Outer class effects ====
+Inner 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 inner classes defined within them.
+Specifically:
+  * An abstract outer class can define concrete (non-abstract) inner classes. Inner classes remain instantiable, independent of the outer class’s abstractness.
+  * A final outer class does not force its inner classes to be final. Inner classes within a final class can be extended internally, providing flexibility within encapsulation boundaries.
+  * A readonly outer class can define mutable inner classes. This supports internal flexibility, allowing the outer class to maintain immutability in its external API while managing state changes internally via inner classes.
+Examples:
+<code php>
+abstract class Service {
+    // Valid: Inner class is not abstract, despite the outer class being abstract.
+    public class Implementation {
+        public function run(): void {}
     }
+}
-    public class FromPoints extends Triangle {
-        public function __construct(Point $p1, Point $p2, Point $p3) {
+// Allowed; abstract outer class does not force inner classes to be abstract.
-            parent::__construct($p1, $p2, $p3);
+new Service:>Implementation();
-        }
+</code>
+<code php>
+readonly class ImmutableCollection {
+    private array $items;
+    public function __construct(array $items) {
+        $this->items = $items;
     }
-    public class FromCoordinates extends Triangle {
+    public function getMutableBuilder(): self:>Builder {
-        public function __construct(int $x1, int $y1, int $x2, int $y2, int $x3, int $y3) {
+        return new self:>Builder($this->items);
-            parent::__construct(new Point($x1, $y1), new Point($x2, $y2), new Point($x3, $y3));
-        }
     }
-}
-$t = new Triangle::FromCoordinates(0, 0, 1, 1, 2, 2);
+    public class Builder {
+        private array $items;
-var_dump($t instanceof Triangle); // true
+        public function __construct(array $items) {
-var_dump($t instanceof Geometry); // true
+            $this->items = $items;
-var_dump($t instanceof Triangle::FromCoordinates); // true
+        }
+        public function add(mixed $item): self {
+            $this->items[] = $item;
+            return $this;
+        }
+        public function build(): ImmutableCollection {
+            return new ImmutableCollection($this->items);
+        }
+    }
+}
 </code>
-However, no classes may not inherit from inner classes, but inner classes may inherit from other classes, including the outer class.
+In this example, even though ImmutableBuilder is a mutable inner class within a readonly outer class, the outer class maintains its immutability externally, while inner classes help internally with state management or transitional operations.
-=== Names ===
+==== Abstract inner classes ====
-Inner classes may not have any name that conflicts with a constant or static property of the same name.
+It is worth exploring what an ''%%abstract%%'' inner class means and how it works. Abstract inner 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 an inner class in a subclass of the outer class or an inner class in the same outer class. However, this is not required by subclasses of the outer class.
+Abstract inner classes may not be instantiated, just as abstract outer classes may not be instantiated.
 <code php>
-class Foo {
+class OuterParent {
-    const Bar = 'bar';
+    protected abstract class InnerBase {}
-    class Bar(public string $message);
-    // Fatal error: Uncaught Error: Cannot redeclare Foo::Bar
 }
-class Foo {
+// Middle is allowed, does not have to implement InnerBase
-    static $Bar = 'bar';
+class Middle extends OuterParent {}
-    class Bar(public string $message);
+// Last demonstrates extending the abstract inner class explicitly.
-    // Fatal error: Uncaught Error: Cannot redeclare Foo::$Bar
+class Last extends OuterParent {
+    private abstract class InnerExtended extends OuterParent:>InnerBase {}
 }
 </code>
@@ Line 257: / Line 447: @@
 ===== Backward Incompatible Changes =====
-This RFC introduces new syntax and behavior to PHP, which does not conflict with existing syntax. However, tooling utilizing AST or tokenization may need to be updated to support the new syntax.
+  * This RFC introduces new syntax and behavior to PHP, which does not conflict with existing syntax.
+  * Some error messages will be updated to reflect inner 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.
 ===== Proposed PHP Version(s) =====
@@ Line 271: / Line 463: @@
 ==== To Existing Extensions ====
-Extensions accepting class names may need to be updated to support ''%%::%%'' in class names. None were discovered during testing, but it is possible there are extensions that may be affected.
+Extensions accepting class names may need to be updated to support ''%%:>%%'' in class names. None were discovered during testing, but it is possible there are unbundled extensions that may be affected.
 ==== To Opcache ====
-Most of the changes are in compilation and AST, so the impact to opcache is minimal.
+This change introduces a new opcode, AST, and other changes that affect opcache. These changes are included as part of the PR that implements this feature.
+==== To Tooling ====
+Tooling that uses AST or tokenization may need to be updated to support the new syntax, such as syntax highlighting, static analysis, and code generation tools.
 ===== Open Issues =====
@@ Line 283: / Line 479: @@
 ===== Unaffected PHP Functionality =====
-There should be no change to existing PHP functionality.
+There should be no change to any existing PHP syntax.
 ===== Future Scope =====
-  * inner enums
+  * Inner enums
+  * Inner interfaces
+  * Inner traits
+  * ''%%Outer%%'' keyword for easily accessing outer classes
 ===== Proposed Voting Choices =====
+As this is a significant change to the language, a 2/3 majority is required.
 ===== Patches and Tests =====
-A complete implementation is available [[https://github.com/php/php-src/compare/master...bottledcode:php-src:rfc/short-class2?expand=1|on GitHub]].
+To be completed.
 ===== Implementation =====
@@ Line 302: / Line 503: @@
 ===== References =====
-Links to external references, discussions or RFCs
+  * [[https://externals.io/message/125975#125977|email that inspired this RFC]]
+  * [[https://wiki.php.net/rfc/records|RFC: Records]]
 ===== Rejected Features =====
-Keep this updated with features that were discussed on the mail lists.
+TBD

Differences

Page Tools