[RFC]: Add file_descriptor() function to retrieve the file descriptor of a PHP Stream

ext/standard/basic_functions.stub.php

@@ -2642,6 +2642,9 @@ function fread($stream, int $length): string|false {}
  */
 function fopen(string $filename, string $mode, bool $use_include_path = false, $context = null) {}
 
+/** @param resource $stream */
+function file_descriptor($stream): int {}
+
 /**
  * @param resource $stream
  * @return array<int, mixed>|int|false|null

ext/standard/file.c

@@ -864,6 +864,32 @@ PHP_FUNCTION(pclose)
 }
 /* }}} */
 
+PHP_FUNCTION(file_descriptor)
+{
+	zval *zsrc;
+	php_stream *stream;
+	php_socket_t fileno;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_RESOURCE(zsrc)
+	ZEND_PARSE_PARAMETERS_END();
+
+	php_stream_from_zval(stream, zsrc);
+
+	/* TODO Should support streams that can be cast with PHP_STREAM_AS_FD_FOR_SELECT ? */
+	/* get the fd.
+	 * NB: Most other code will NOT use the PHP_STREAM_CAST_INTERNAL flag when casting.
+	 * It is only used here so that the buffered data warning is not displayed.
+	 */
+    if (php_stream_can_cast(stream, PHP_STREAM_AS_FD | PHP_STREAM_CAST_INTERNAL) == FAILURE) {
+		zend_argument_type_error(1, "cannot represent as a file descriptor");
+		RETURN_THROWS();
+    }
+    php_stream_cast(stream, PHP_STREAM_AS_FD | PHP_STREAM_CAST_INTERNAL, (void*)&fileno, true);
+
+    RETURN_LONG(fileno);
+}
+
 /* {{{ Test for end-of-file on a file pointer */
 PHPAPI PHP_FUNCTION(feof)
 {

ext/standard/tests/file/file_descriptor_basic.phpt

@@ -0,0 +1,26 @@
+--TEST--
+Test file_descriptor() function: basic functionality
+--FILE--
+<?php
+echo "*** Testing fileno() : basic functionality ***\n";
+$tmpFile1 = __DIR__ . '/fileno.tmp1';
+$file = fopen($tmpFile1, 'wb');
+fclose($file);
+
+$file = fopen($tmpFile1, 'rb');
+var_dump(file_descriptor($file));
+
+var_dump(file_descriptor(STDOUT));
+
+echo "Done";
+?>
+--CLEAN--
+<?php
+$tmpFile1 = __DIR__ . '/fileno.tmp1';
+unlink($tmpFile1);
+?>
+--EXPECTF--
+*** Testing fileno() : basic functionality ***
+int(%d)
+int(1)
+Done

ext/standard/tests/file/file_descriptor_non_castable_stream.phpt

@@ -0,0 +1,44 @@
+--TEST--
+Test file_descriptor() function: retrieve file descriptor on TCP socket
+--EXTENSIONS--
+pcntl
+posix
+--SKIPIF--
+<?php
+require __DIR__ . '/../http/server.inc'; http_server_skipif();
+?>
+--INI--
+allow_url_fopen=1
+--FILE--
+<?php
+
+require __DIR__ . '/../http/server.inc';
+
+$responses = array(
+    "data://text/plain,HTTP/1.0 200 Ok\r\nSome: Header\r\nSome: Header\r\n\r\nBody",
+);
+
+['pid' => $pid, 'uri' => $uri] = http_server($responses, $output);
+
+/* Note: the warning is bogus in this case as no data actually gets lost,
+ * but this checks that stream casting works */
+$handle = fopen($uri, 'r');
+$fd = file_descriptor($handle);
+var_dump($fd);
+var_dump(fread($handle, 20));
+fclose($handle);
+
+$socket = stream_socket_client('tcp://example.com:80', timeout: 0.5);
+$fds = file_descriptor($socket);
+var_dump($fds);
+fclose($socket);
+
+var_dump($fd == $fds);
+
+http_server_kill($pid);
+?>
+--EXPECTF--
+int(%d)
+string(4) "Body"
+int(%d)
+bool(true)

ext/standard/tests/file/file_descriptor_non_castable_user_stream.phpt

@@ -0,0 +1,79 @@
+--TEST--
+Test file_descriptor() function: error on uncastable user stream
+--FILE--
+<?php
+
+// TODO Improve by mimicking tests from GH 10173 PR
+class DummyStreamWrapper
+{
+    /** @var resource|null */
+    public $context;
+
+    /** @var resource|null */
+    public $handle;
+
+    public function stream_cast(int $castAs)
+    {
+        return false;
+    }
+
+    public function stream_close(): void { }
+
+    public function stream_open(string $path, string $mode, int $options = 0, ?string &$openedPath = null): bool
+    {
+        return true;
+    }
+
+    public function stream_read(int $count)
+    {
+        return 0;
+    }
+
+    public function stream_seek(int $offset, int $whence = SEEK_SET): bool
+    {
+        return true;
+    }
+
+    public function stream_set_option(int $option, int $arg1, ?int $arg2): bool
+    {
+        return false;
+    }
+
+    public function stream_stat()
+    {
+        return [];
+    }
+
+    public function stream_tell()
+    {
+        return [];
+    }
+
+    public function stream_truncate(int $newSize): bool
+    {
+        return true;
+    }
+
+    public function stream_write(string $data) { }
+
+
+    public function unlink(string $path): bool
+    {
+        return false;
+    }
+}
+stream_wrapper_register('custom', DummyStreamWrapper::class);
+
+$fp = fopen("custom://myvar", "r+");
+try {
+    var_dump(file_descriptor($fp));
+} catch (\TypeError $e) {
+    echo $e->getMessage(), PHP_EOL;
+}
+fclose($fp);
+
+echo "Done";
+?>
+--EXPECT--
+file_descriptor(): Argument #1 ($stream) cannot represent as a file descriptor
+Done