Differences

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

--- rfc:short-and-inner-classes [2025/02/22 20:09] – created 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 new 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**, which allows for defining simple or data-oriented classes 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 serves 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**, which allows for the ability to define classes within other classes and control the use of inner classes through visibility:
+==== 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 a short class definition is as follows: a keyword ''%%class%%'', followed by the class name, then a list of properties enclosed in parentheses. Optionally, a list of traits, interfaces, and a parent class may be defined.
+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: x and y
+''%%:>%%'' communicates "inner membership," visually linking the inner class to the outer class.
-class Point(int $x, int $y);
-// a more complex 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>
-Any properties defined within the parenthesis are defined as a property on the class and are automatically ''%%public%%'' unless specified otherwise.
+=== 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.
-Default values may be provided for properties but only for properties with type hints:
+=== 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.
-With class short syntax, no behavior may be defined, yet it can still utilize traits, interfaces, and other classes.
+=== 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>
-Note that the original constructor from any parent class is overridden and not called by the short syntax.
+''%%self%%'' explicitly resolves to the current class body it is written in, just like with ''%%parent%%''. On ''%%inner%%'' classes.
-=== Empty Classes ===
+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.
-Short classes may also be empty:
+<code php>
+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>
+=== Dynamic resolution ===
+Just as with ''%%::%%'', developers may use variables to resolve inner classes, or refer to them by name directly via a string:
 <code php>
-class Point() extends BasePoint use PointTrait;
+// Using variables to dynamically instantiate inner classes:
+$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>
-=== Attributes ===
+This provides flexibility and backwards compatibility for dynamic code that may not expect an inner class.
-Attributes may also be used with short classes:
+==== 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>
-#[MyAttribute]
+class User {
-class Password(#[SensitiveParameter] string $password);
+    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);
+        }
+    }
+}
+$user = new User:>Builder()->withName('Rob')->withEmail('rob@bottled.codes')->build();
 </code>
-=== Modifiers ===
+This enables usages such as builder patterns and other helper classes to succinctly encapsulate behavior.
-Short classes support modifiers such as ''%%readonly%%'', ''%%final%%'' and ''%%abstract%%'':
+==== Visibility from outside the outer class ====
+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>
-readonly class User(int $id, string $name);
+class Outer {
+    private class Other {}
+    protected class Inner {
+        public function Foo() {
+            $bar = new Outer:>Inner(); // allowed
+            $bar = new Outer:>Other(); // allowed
+        }
+    }
+}
-final class Config(string $key, mixed $value);
+class SubOuter extends Outer {
+    public function Foo() {
+        $bar = new parent:>Inner(); // allowed to access protected inner class
+        $bar = new parent:>Other(); // Cannot access private inner class 'Outer:>Other'
+    }
+}
+</code>
-abstract class Shape(float $area);
+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>
-=== How it works ===
+=== Method return type and argument declarations ===
-Short classes are implemented as pure syntax sugar and are compiled as full class definitions.
+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.
-==== Inner Classes ====
+^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    |
-Inner classes are classes that are defined within another class.
+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 {
-    class Inner(public string $message);
+    private class Inner {}
-    private class PrivateInner {
+    public function getInner(): self:>Inner {
-        public function __construct(public string $message) {}
+        return new self:>Inner();
     }
 }
-$foo = new Outer::Inner('Hello, world!');
+// Fatal error: Uncaught TypeError: Public method getInner cannot return private class Outer:>Inner
-echo $foo->message;
+new Outer()->getInner();
-// outputs: Hello, world!
-$baz = new Outer::PrivateInner('Hello, world!');
-// Fatal error: Uncaught Error: Cannot access private inner class Outer::PrivateInner
 </code>
-Inner classes have inheritance similar to static properties, allowing you to define rich class hierarchies:
+=== Properties ===
+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>
-readonly class Point(int $x, int $y);
+class Outer {
+    private class Inner implements FooBar {}
-class Geometry {
-    public array $points;
-    protected function __construct(Point ...$points) {
-        $this->points = $points;
-    }
-    public class FromPoints extends Geometry {
+    public function getInner(): FooBar {
-        public function __construct(Point ...$points) {
+        return new self:>Inner(); // not an error
-            parent::__construct(...$points);
-        }
-    }
-    public class FromCoordinates extends Geometry {
-        public function __construct(int ...$coordinates) {
-            $points = [];
-            for ($i = 0; $i < count($coordinates); $i += 2) {
-                $points[] = new Point($coordinates[$i], $coordinates[$i + 1]);
-            }
-            parent::__construct(...$points);
-        }
     }
 }
+</code>
-class Triangle extends Geometry {
+==== Accessing outer classes ====
-    protected function __construct(public Point $p1, public Point $p2, public Point $p3) {
-        parent::__construct($p1, $p2, $p3);
+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.
-    }
+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.
+<code php>
+class Message {
+    public function __construct(private string $message, private string $from, private string $to) {}
-    public class FromPoints extends Triangle {
+    public function Serialize(): string {
-        public function __construct(Point $p1, Point $p2, Point $p3) {
+        return new Message:>SerializedMessage($this)->message;
-            parent::__construct($p1, $p2, $p3);
-        }
     }
-    public class FromCoordinates extends Triangle {
+    private class SerializedMessage {
-        public function __construct(int $x1, int $y1, int $x2, int $y2, int $x3, int $y3) {
+        public string $message;
-            parent::__construct(new Point($x1, $y1), new Point($x2, $y2), new Point($x3, $y3));
+        public function __construct(Message $message) {
+            $this->message = strlen($message->from) . $message->from . strlen($message->to) . $message->to . strlen($message->message) . $message->message;
         }
     }
 }
+</code>
-$t = new Triangle::FromCoordinates(0, 0, 1, 1, 2, 2);
+==== Reflection ====
+Several new methods are added to ''%%ReflectionClass%%'' to help support inspection of inner classes:
+<code php>
+$reflection = new ReflectionClass('\a\namespace\Outer:>Inner');
-var_dump($t instanceof Triangle); // true
+$reflection->isInnerClass(); // true
+$reflection->isPublic() || $reflection->isProtected() || $reflection->isPrivate(); // true
+$reflection->getName(); // \a\namespace\Outer:>Inner
+$reflection->getShortName(); // Outer:>Inner
 </code>
-=== Modifiers ===
+For non-inner classes, ''%%ReflectionClass::isInnerClass()%%'' returns false.
-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:
+==== Autoloading ====
-  * ''%%public%%'', ''%%private%%'', and ''%%protected%%'' apply to the visibility of the inner class.
+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.
-  * ''%%final%%'', and ''%%readonly%%'' apply to the class itself.
-Thus, an inner class with the modifier ''%%private readonly%%'' is only accessible within the class and any instances are readonly.
+==== Usage ====
-''%%static%%'' is not allowed as a modifier on an inner class because there is currently no such thing as a ''%%static%%'' class in PHP.
+Inner classes may be defined in the body of any class-like structure, including but not limited to:
-=== Visibility ===
+  * in a class body
+  * in an anonymous class body
+  * in an enum body
+  * in a trait body
+  * in an interface body
-A ''%%private%%'' or ''%%protected%%'' inner class type is only accessible within the class it is defined in (or its subclasses in the case of protected classes). This is similar to C#, so you may return a private type from a public method, but not use it as a type hint from outside the outer class:
+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>
-class Outer {
+abstract class Service {
-    private class Inner(string $message);
+    // Valid: Inner class is not abstract, despite the outer class being abstract.
+    public class Implementation {
-    public function getInner(): self::Inner {
+        public function run(): void {}
-        return new self::Inner('Hello, world!');
     }
 }
-function doSomething(Outer::Inner $inner) {
+// Allowed; abstract outer class does not force inner classes to be abstract.
-    echo $inner->message;
+new Service:>Implementation();
-}
-doSomething(new Outer()->getInner());
-// Fatal error: Private inner class Outer::Inner cannot be used in the global scope
 </code>
-You may also not instantiate a private/protected class from outside the outer class’s scope:
 <code php>
-$x = new Outer::Inner();
+readonly class ImmutableCollection {
-// Fatal error: Uncaught Error: Cannot access private inner class Outer::Inner
+    private array $items;
+    public function __construct(array $items) {
+        $this->items = $items;
+    }
+    public function getMutableBuilder(): self:>Builder {
+        return new self:>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);
+        }
+    }
+}
 </code>
-=== Inheritance ===
+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.
-Classes may not inherit from inner classes. Inner classes may inherit from other classes, including the outer class.
+==== Abstract inner classes ====
-=== Names ===
+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.
-Inner classes may not have any name that conflicts with a constant or static property of the same name.
+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 252: / 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 266: / 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 278: / 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 297: / 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