Add some details for Directory RFC

Author: Girgias

accepted/directory-opaque-object.md

@@ -1,4 +1,4 @@
-# PHP RFC: Change Directory class to behave like an opaque object 
+# PHP RFC: Change Directory class to behave like a resource object
 
 - Version: 0.1
 - Date: 2024-09-14
@@ -10,8 +10,9 @@
 
 ## Introduction
 
-The `Directory` class is probably the first instance of what we now call an "opaque object".
-Opaque objects are normally the result of converting resources to objects,
+The `Directory` class is probably the first instance of what we now call a "resource object"
+(and in its stricter sense an "opaque object").
+Resource/Opaque objects are usually the result of converting resources to objects,
 which in general implies, being `final`, being not serializable,
 not constructible via `new`, cannot be cast, and to not implement any methods.
 However, as this class has existed since PHP 4 none of these things are formally implemented.
@@ -21,7 +22,7 @@ But one can create a broken instance by just using `new Directory()`,
 which is visible if one tries to call one of its methods.
 
 As it seems likely that we will repurpose this class when converting directory resources to objects;
-we think it makes sense to already convert this class to behave like an opaque object.
+we think it makes sense to already convert this class to behave like a resource object.
 
 ## Proposal
 
@@ -33,6 +34,33 @@ We propose to make the following changes to the `Directory` class:
 - Ban serialization of it via the `@not-serializable` doc comment on the class stub
 - Ban creating dynamic properties on an instance of `Directory` via the `@strict-properties` doc comment on the class stub
 
+## Rationales
+### Preventing initialization via new
+
+The stream layer of PHP emits warnings and may result in uninitialized streams.
+Constructors must always either throw an exception, or create a valid object.
+As these semantics are not straightforward to implement when creating streams we continue to rely on `dir()`
+to create instances of this class as it does not have the above constraints.
+
+### Making the class final
+
+As this class is a wrapper around an internal stream resource,
+and cannot be properly initialized without it being returned by `dir()`.
+Extending it doesn't make any sense.
+
+### Preventing cloning
+
+As this class is a wrapper around an internal stream resource,
+and there is no capability to duplicate streams, there is no reasonable way to implement cloning.
+
+### Preventing serialization
+
+Trying to serialize (and unserialize) the state of a given file system doesn't make any sense.
+
+### Preventing the creation of dynamic properties
+
+Creating a dynamic property on an instance of this class points to a definite bug.
+
 ## Backward Incompatible Changes
 
 It will no longer be possible:
@@ -51,6 +79,8 @@ VOTING_SNIPPET
 
 ## Future scope
 
+- Add support to initialize the class via `new`
+- Add support for cloning
 
 ## References