rfc:directory-opaque-object

Differences

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

Link to this comparison view

Next revision		Previous revision
rfc:directory-opaque-object [2024/09/14 15:30] – created girgiasrfc:directory-opaque-object [2024/10/03 15:03] (current) – Open vote girgias
Line 1: Line 1:
-====== 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   * Version: 0.1
   * Date: 2024-09-14   * Date: 2024-09-14
   * Author: Gina Peter Banyard <girgias@php.net>   * Author: Gina Peter Banyard <girgias@php.net>
-  * Status: Under Discussion+  * Status: In voting
   * Target Version: PHP 8.5   * Target Version: PHP 8.5
   * Implementation: https://github.com/php/php-src/pull/15886   * Implementation: https://github.com/php/php-src/pull/15886
Line 11: Line 11:
 ===== Introduction ===== ===== Introduction =====
  
-The <php>Directory</php> class is probably the first instance of what we now call an "opaque object". +The <php>Directory</php> class is probably the first instance of what we now call a "resource object" 
-Opaque objects are normally the result of converting resources to objects, +(and in its stricter sense an "opaque object"). 
-which in general implies, being <php>final</php>, being not serializable, +Resource/Opaque objects are usually the result of converting resources to objects, 
-not constructible via <php>new</php>, cannot be cast, and to not implement any methods.+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. However, as this class has existed since PHP 4 none of these things are formally implemented.
  
Line 21: Line 22:
 which is visible if one tries to call one of its methods. 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; +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 ===== ===== Proposal =====
Line 33: Line 34:
   * Ban serialization of it via the <php>@not-serializable</php> doc comment on the class stub   * 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   * 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 ===== ===== Backward Incompatible Changes =====
Line 50: Line 77:
 As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted. 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.+Voting started on 2024-10-03 and will end on 2024-10-17.
    
-<doodle title="Accept Change Directory class to behave like an opaque object  RFC?" auth="girgias" voteType="single" closed="true">+<doodle title="Accept Change Directory class to behave like a resource object RFC?" auth="girgias" voteType="single" closed="false">
    * Yes    * Yes
    * No    * No
Line 59: Line 86:
 ===== Future scope ===== ===== Future scope =====
  
 +  * Add support to initialize the class via <php>new</php>
 +  * Add support for cloning
  
 ===== References ===== ===== References =====
  
  
rfc/directory-opaque-object.1726327810.txt.gz · Last modified: 2024/09/14 15:30 by girgias

Page Tools