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

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 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 file_descriptor() function.

The proposal is to add the following function to PHP:

/** @param resource $stream */
function file_descriptor($stream): int {}

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.

This RFC does not contain any backwards incompatible changes.

Next minor version, i.e. PHP 8.3.

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.

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

FFI implementation: https://github.com/ppelisset/php-fileno
AFUP Forum PHP Talk (in French) describing the use case: FFI : De nouveaux horizons pour PHP - Pierre PELISSET - Forum PHP 2022