====== PHP RFC: Add file_descriptor() function ======

  * Version: 0.1
  * Date: 2023-01-16
  * Author: George Peter Banyard, <girgias@php.net>
  * Status: Under Discussion
  * Target Version: PHP 8.3
  * Implementation: [[https://github.com/php/php-src/pull/10342]]
  * First Published at: [[http://wiki.php.net/rfc/file-descriptor-function]]

===== Introduction =====

When dealing with I/O in PHP, one deals with streams as an abstraction over the file system. This abstraction is convenient in giving a uniform interface without needing to deal with the underlying system. However, sometimes one needs to deal with the file system directly via the file descriptor, for example when interacting with a USB device.

PHP supports retrieving the file descriptor of a stream within the engine, but does not expose this capability to userland. However, with the [[https://github.com/ppelisset/php-fileno|magic of FFI]] it is possible to expose the underlying file descriptor of a stream if it exists, by stubbing out the Zend engine. 

This RFC address this issue by proposing the addition of a native <php>file_descriptor()</php> function.


===== Proposal =====

The proposal is to add the following function to PHP:
<PHP>
/** @param resource $stream */
function file_descriptor($stream): int {}
</PHP>

Which returns the underlying file descriptor of a stream if it exists, or throws a ''TypeError'' if the resource is not a stream or does not have an underlying file descriptor.


===== Backward Incompatible Changes =====

This RFC does not contain any backwards incompatible changes.

===== Proposed PHP Version =====

Next minor version, i.e. PHP 8.3.

===== Proposed Voting Choices =====

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 2023-XX-XX and will end on 2023-XX-XX.
<doodle title="Accept Add file_descriptor function RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Implementation =====

GitHub pull request: https://github.com/php/php-src/pull/10342

After the project is implemented, this section should contain

  * the version(s) it was merged into
  * a link to the git commit(s)
  * a link to the PHP manual entry for the feature

===== References =====

FFI implementation: [[https://github.com/ppelisset/php-fileno]]\\
AFUP Forum PHP Talk (in French) describing the use case: [[https://www.youtube.com/watch?v=oUtJrx0ElUc|FFI : De nouveaux horizons pour PHP - Pierre PELISSET - Forum PHP 2022]]