====== PHP RFC: Change Directory class to behave like an opaque object  ======

  * Version: 0.1
  * Date: 2024-09-14
  * Author: Gina Peter Banyard <girgias@php.net>
  * Status: Under Discussion
  * 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 an "opaque object".
Opaque objects are normally the result of converting resources to objects,
which in general implies, being <php>final</php>, being not serializable,
not constructible via <php>new</php>, 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.

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 an opaque 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

===== 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-XX-XX and will end on 2024-XX-XX.
 
<doodle title="Accept Change Directory class to behave like an opaque object  RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

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


===== References =====