Differences

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

--- rfc:short-and-inner-classes [2025/03/06 21:24] – remove short syntax withinboredom
+++ rfc:short-and-inner-classes [2025/03/15 10:28] (current) – reword and clarify withinboredom
@@ Line 1: / Line 1: @@
 ====== PHP RFC: Inner Classes ======
-  * Version: 0.1
+  * Version: 0.4
   * Date: 2025-02-08
   * Author: Rob Landers, <rob@bottled.codes>
@@ Line 9: / Line 9: @@
 ===== Introduction =====
-This RFC proposes a significant enhancement to the language: **Inner Classes**. This feature aims to introduce a new level of encapsulation and organization within PHP applications.
+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.
-Inner Classes enable the definition of classes within other classes, providing fine-grained visibility control and fostering better modularization.
+**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.
-By adopting these enhancements, PHP can offer developers more powerful tools to write clean, efficient, and well-structured code, ultimately improving the overall developer experience and code quality.
+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. Inner classes may only be nested one level deep, may not be a parent class, and may not be declared ''%%abstract%%'':
+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>
@@ Line 30: / Line 32: @@
 }
-$foo = new Outer::Inner('Hello, world!');
+$foo = new Outer:>Inner('Hello, world!');
 echo $foo->message;
 // outputs: Hello, world!
-$baz = new Outer::PrivateInner('Hello, world!');
+$baz = new Outer:>PrivateInner('Hello, world!');
-// Fatal error: Uncaught Error: Cannot access private inner class Outer::PrivateInner
+// Fatal error: Class 'Outer:>PrivateInner' is private
 </code>
-=== Modifiers ===
+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 support modifiers such as ''%%public%%'', ''%%protected%%'', ''%%private%%'', ''%%final%%'' and ''%%readonly%%''. When using these as modifiers on an inner class, there are some intuitive rules:
+==== Declaration Syntax ====
-  * ''%%public%%'', ''%%private%%'', and ''%%protected%%'' apply to the **visibility** of the inner class.
+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%%''.
-  * ''%%final%%'', and ''%%readonly%%'' apply **to the class itself**.
-  * ''%%static%%'' is **not allowed** as a modifier since PHP does not support static classes and isn’t a property.
-  * ''%%abstract%%'' is not allowed as an inner class **cannot** be parent classes.
-=== Visibility Rules ===
+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.
-Private and protected inner classes are only instantiatable within their outer class (or subclasses for protected) and may not be used as //type declarations// outside their outer class.
+<code php>
+class Outer {
+    private class Inner {}
+    protected readonly class ReadOnlyInner {}
+    public abstract class AbstractInner {}
+    public final class FinalInner {}
+}
+</code>
-For example, you may return a private inner class from any method inside that same inner class or the outer class, but you may not use it as a type declaration in a function outside the outer class:
+If an inner class is not defined as ''%%private%%'', ''%%protected%%'', or ''%%public%%'', it is assumed to be ''%%public%%''.
+==== Syntax rationale ====
+The ''%%:>%%'' syntax was selected after evaluating alternatives:
+  * 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.
+''%%:>%%'' communicates "inner membership," visually linking the inner class to the outer class.
+==== Binding ====
+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 Box {
+class Outer {
-  private class Point {
+    class OuterInner {}
-    public function __construct(public int $x, public int $y) {}
-  }
-  private self::Point $center;
-  public function __construct() {
-    $this->center = new self::Point(0, 0);
-  }
-  public function getCenter(): self::Point {
-    return $this->center;
-  }
-  public function setCenter(self::Point $center) {
-    $this->center = $center;
-  }
 }
-$box = new Box();
+interface Foo {
-$center = $box->getCenter();
+    class FooInner {}
-$center->x = 10;
+}
-$box->setCenter($center);
-var_dump($box);
+trait Bar {
+    class BarInner {}
+}
+class All extends Outer implements Foo {
+    use Bar;
+    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>
-Outputs:
+=== static resolution ===
-<code>
+The ''%%static%%'' keyword is **not** supported to resolve inner classes. Attempting to do so results in an error, depending on where it is used:
-object(Box)#1 (1) {
-  ["center":"Box":private]=>
+<code php>
-  object(Box::Point)#2 (2) {
+class Outer {
-    ["x"]=>
+    class Inner {}
-    int(10)
-    ["y"]=>
+    // Fatal error: Cannot use the static modifier on a parameter
-    int(0)
+    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>
-However, if we try to use it outside the outer class as a type declaration:
+This is to prevent casual LSP violations of inheritance and to maintain the strong binding of inner classes.
+=== parent resolution ===
+The ''%%parent%%'' keyword is supported to resolve inner classes. Which parent it resolves to depends on the context:
 <code php>
-function mutateBox(Box::Point $point): Box::Point {
+class Foo {
-    $point->x = 10;
+    class Bar {}
 }
-$center = mutateBox($center);
+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>
-We receive the following error:
+''%%parent%%'' explicitly resolves to the parent class of the current class body it is written in and helps with writing more concise code.
-<code>
+=== self resolution ===
-PHP Fatal error:  Private inner class Box::Point cannot be used in the global scope
+The ''%%self%%'' keyword is supported to resolve inner classes. Which ''%%self%%'' it resolves to depends on the context:
+<code php>
+class Outer {
+  class Middle {
+    class Other {}
+    // extends Outer:>Middle:>Other
+    class Inner extends self:>Other {
+        public function foo(): self {} // returns Outer:>Middle:>Inner
+    }
+  }
+}
 </code>
-This gives a great deal of control to developers, preventing accidental misuse of inner classes. Developers may have the inner class implement an interface so that the programmer must code to the interface, allowing large projects to enforce a consistent API.
+''%%self%%'' explicitly resolves to the current class body it is written in, just like with ''%%parent%%''. On ''%%inner%%'' classes.
-=== Inheritance ===
+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.
-Inner classes have inheritance similar to static properties; this allows you to redefine an inner class in a subclass, allowing rich hierarchies.
+<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>
-readonly class Point(int $x, int $y);
+// Using variables to dynamically instantiate inner classes:
+$outer = "Outer";
+$inner = "Inner";
+$instance = new $outer:>$inner();
-class Geometry {
+// Instantiating inner class dynamically via a fully qualified class string:
-    public array $points;
+$dynamicClassName = "Outer:>Inner";
-    protected function __construct(Point ...$points) {
+$instance = new $dynamicClassName();
-        $this->points = $points;
+</code>
+This provides flexibility and backwards compatibility for dynamic code that may not expect an inner class.
+==== 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>
+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 class FromPoints extends Geometry {
+    public readonly final class Builder {
-        public function __construct(Point ...$points) {
+        public function __construct(public private(set) string|null $name = null, public private(set) string|null $email = null) {}
-            parent::__construct(...$points);
+        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);
         }
     }
+}
-    public class FromCoordinates extends Geometry {
-        public function __construct(int ...$coordinates) {
+$user = new User:>Builder()->withName('Rob')->withEmail('rob@bottled.codes')->build();
-            $points = [];
+</code>
-            for ($i = 0; $i < count($coordinates); $i += 2) {
-                $points[] = new Point($coordinates[$i], $coordinates[$i + 1]);
+This enables usages such as builder patterns and other helper classes to succinctly encapsulate behavior.
-            }
-            parent::__construct(...$points);
+==== 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>
+class Outer {
+    private class Other {}
+    protected class Inner {
+        public function Foo() {
+            $bar = new Outer:>Inner(); // allowed
+            $bar = new Outer:>Other(); // allowed
         }
     }
 }
-class Triangle extends Geometry {
+class SubOuter extends Outer {
-    protected function __construct(public Point $p1, public Point $p2, public Point $p3) {
+    public function Foo() {
-        parent::__construct($p1, $p2, $p3);
+        $bar = new parent:>Inner(); // allowed to access protected inner class
+        $bar = new parent:>Other(); // Cannot access private inner class 'Outer:>Other'
     }
+}
+</code>
+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>
+=== Method return type and argument declarations ===
+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 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    |
+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 Inner {}
-    public class FromPoints extends Triangle {
+    public function getInner(): self:>Inner {
-        public function __construct(Point $p1, Point $p2, Point $p3) {
+        return new self:>Inner();
-            parent::__construct($p1, $p2, $p3);
+    }
-        }
+}
+// Fatal error: Uncaught TypeError: Public method getInner cannot return private class Outer:>Inner
+new Outer()->getInner();
+</code>
+=== 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>
+class Outer {
+    private class Inner implements FooBar {}
+    public function getInner(): FooBar {
+        return new self:>Inner(); // not an error
+    }
+}
+</code>
+==== Accessing outer classes ====
+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 function Serialize(): string {
+        return new Message:>SerializedMessage($this)->message;
     }
-    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 ====
-var_dump($t instanceof Triangle); // true
+Several new methods are added to ''%%ReflectionClass%%'' to help support inspection of inner classes:
-var_dump($t instanceof Geometry); // true
-var_dump($t instanceof Triangle::FromCoordinates); // true
+<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>
-However, no classes may not inherit from inner classes, but inner classes may inherit from other classes, including the outer class.
+For non-inner classes, ''%%ReflectionClass::isInnerClass()%%'' returns false.
-It’s important to note that inheritance for inner classes does not violate the Liskov Substitution Principle (LSP). LSP states that objects of a superclass should be replaceable with objects of a subclass without affecting the correctness of the program.
+==== Autoloading ====
-**Visibility Rules**: Private and protected inner classes are only instantiable within their outer class (or subclasses for protected) and cannot be used as type declarations outside their outer class. This encapsulation ensures that the inner class’s implementation details remain within their intended scope.
+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.
-**Inheritance**: Inner classes can inherit from other classes, including the outer class, but cannot be used as parent classes. This restriction is primarily about maintaining clear scope boundaries and encapsulation, rather than preventing LSP violations. Inner classes behave like any other class with respect to inheritance and polymorphism within their allowed scope.
+==== Usage ====
-=== Names ===
+Inner classes may be defined in the body of any class-like structure, including but not limited to:
-Inner classes may not have any name that conflicts with a constant or static property of the same name.
+  * 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>
-class Foo {
+abstract class Service {
-    const Bar = 'bar';
+    // Valid: Inner class is not abstract, despite the outer class being abstract.
-    public class Bar {}
+    public class Implementation {
+        public function run(): void {}
-    // Fatal error: Uncaught Error: Cannot redeclare Foo::Bar
+    }
 }
-class Foo {
+// Allowed; abstract outer class does not force inner classes to be abstract.
-    static $Bar = 'bar';
+new Service:>Implementation();
-    public class Bar {}
+</code>
-    // Fatal error: Uncaught Error: Cannot redeclare Foo::$Bar
+<code php>
+readonly class ImmutableCollection {
+    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>
+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.
+==== Abstract inner classes ====
+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 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 {}
 }
 </code>
@@ Line 213: / 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 ====
 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 229: / Line 483: @@
 ===== Future Scope =====
-TBD.
+  * Inner enums
+  * Inner interfaces
+  * Inner traits
+  * ''%%Outer%%'' keyword for easily accessing outer classes
 ===== Proposed Voting Choices =====
@@ Line 238: / Line 495: @@
 ===== 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 =====

Differences

Page Tools