====== PHP RFC: Change Directory class to behave like a resource object ======

  * Version: 0.1
  * Date: 2024-09-14
  * Author: Gina Peter Banyard <girgias@php.net>
  * Status: Pending Implementation
  * Target Version: PHP 8.5
  * Implementation: https://github.com/php/php-src/pull/15886
  * First Published at: https://wiki.php.net/rfc/directory-opaque-object

===== Introduction =====

The <php>Directory</php> 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 <php>final</php>, not serializable,
not constructible via <php>new</php>, cannot be cast, and does not implement any methods.
However, as this class has existed since PHP 4 none of these things are formally implemented.

Valid instances of this class are created by calling the <php>dir()</php> function.
But one can create a broken instance by just using <php>new Directory()</php>,
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 a resource object.

===== Proposal =====

We propose to make the following changes to the <php>Directory</php> class:

  * Make it <php>final</php>
  * Throw an <php>Error</php> when doing <php>new Directory()</php>
  * Prevent cloning instances of <php>Directory</php>
  * Ban serialization of it via the <php>@not-serializable</php> doc comment on the class stub
  * Ban creating dynamic properties on an instance of <php>Directory</php> via the <php>@strict-properties</php> 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 <php>dir()</php>
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 <php>dir()</php>, 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:

  * to extend the <php>Directory</php> class
  * clone, serialize, or create dynamic properties on an instance of <php>Directory</php>
  * instantiate <php>Directory</php> directly via the <php>new</php> keyword

===== Version =====

Next minor version, i.e. PHP 8.5.

===== Vote =====

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

Voting started on 2024-10-03 and will end on 2024-10-20.
 
<doodle title="Accept Change Directory class to behave like a resource object RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Future scope =====

  * Add support to initialize the class via <php>new</php>
  * Add support for cloning

===== References =====