[DOC-CVS] [doc-en] master: ext/ssh2: Fix ssh2_sftp_* return types to include false (realpath, readlink, stat, lstat) (#5640)

[email protected] (Sören Wünsch via GitHub) Mon, 29 Jun 2026 18:08:19 +0000
Newsgroups	php.doc.cvs
Message-ID	<[email protected]>
Author: Sören Wünsch (Soean)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-29T20:08:17+02:00

Commit: https://github.com/php/doc-en/commit/cad275c0c1bac225cc295e2ee52ecf2564b6fcda
Raw diff: https://github.com/php/doc-en/commit/cad275c0c1bac225cc295e2ee52ecf2564b6fcda.diff

ext/ssh2: Fix ssh2_sftp_* return types to include false (realpath, readlink, stat, lstat) (#5640)

* Fix ssh2_sftp_realpath() return type (string|false)

ssh2_sftp_realpath() can return false on failure (invalid resource, disconnected session, or a failed realpath resolution), but the manual documented the return type as string only.

* Fix ssh2_sftp readlink/stat/lstat return types (add false)

ssh2_sftp_readlink(), ssh2_sftp_stat() and ssh2_sftp_lstat() return false on failure (invalid resource, disconnected session, or a failed libssh2 call), but were documented as string/array only. Update the method synopsis and Return Values accordingly.

Co-authored-by: Louis-Arnaud <[email protected]>

Changed paths:
  M  reference/ssh2/functions/ssh2-sftp-lstat.xml
  M  reference/ssh2/functions/ssh2-sftp-readlink.xml
  M  reference/ssh2/functions/ssh2-sftp-realpath.xml
  M  reference/ssh2/functions/ssh2-sftp-stat.xml


Diff:

diff --git a/reference/ssh2/functions/ssh2-sftp-lstat.xml b/reference/ssh2/functions/ssh2-sftp-lstat.xml
index 92b78e7cb372..c4543a9ad51f 100644
--- a/reference/ssh2/functions/ssh2-sftp-lstat.xml
+++ b/reference/ssh2/functions/ssh2-sftp-lstat.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-sftp-lstat">
+<refentry xml:id="function.ssh2-sftp-lstat" xmlns="http://docbook.org/ns/docbook" >
  <refnamediv>
   <refname>ssh2_sftp_lstat</refname>
   <refpurpose>Stat a symbolic link</refpurpose>
@@ -9,7 +9,7 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>array</type><methodname>ssh2_sftp_lstat</methodname>
+   <type class="union"><type>array</type><type>false</type></type><methodname>ssh2_sftp_lstat</methodname>
    <methodparam><type>resource</type><parameter>sftp</parameter></methodparam>
    <methodparam><type>string</type><parameter>path</parameter></methodparam>
   </methodsynopsis>
@@ -49,6 +49,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
+   Returns an array of statistics for the given symbolic link on success&return.falseforfailure;.
    See the documentation for <function>stat</function> for details on the
    values which may be returned.
   </simpara>
diff --git a/reference/ssh2/functions/ssh2-sftp-readlink.xml b/reference/ssh2/functions/ssh2-sftp-readlink.xml
index 1a34e5661ac7..6f66e16929a4 100644
--- a/reference/ssh2/functions/ssh2-sftp-readlink.xml
+++ b/reference/ssh2/functions/ssh2-sftp-readlink.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-sftp-readlink">
+<refentry xml:id="function.ssh2-sftp-readlink" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ssh2_sftp_readlink</refname>
   <refpurpose>Return the target of a symbolic link</refpurpose>
@@ -9,7 +9,7 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>string</type><methodname>ssh2_sftp_readlink</methodname>
+   <type class="union"><type>string</type><type>false</type></type><methodname>ssh2_sftp_readlink</methodname>
    <methodparam><type>resource</type><parameter>sftp</parameter></methodparam>
    <methodparam><type>string</type><parameter>link</parameter></methodparam>
   </methodsynopsis>
@@ -43,7 +43,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the target of the symbolic <parameter>link</parameter>.
+   Returns the target of the symbolic <parameter>link</parameter>&return.falseforfailure;.
   </simpara>
  </refsect1>
 
diff --git a/reference/ssh2/functions/ssh2-sftp-realpath.xml b/reference/ssh2/functions/ssh2-sftp-realpath.xml
index dd77a64d6346..cf75d3b0041b 100644
--- a/reference/ssh2/functions/ssh2-sftp-realpath.xml
+++ b/reference/ssh2/functions/ssh2-sftp-realpath.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-sftp-realpath">
+<refentry xml:id="function.ssh2-sftp-realpath" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ssh2_sftp_realpath</refname>
   <refpurpose>Resolve the realpath of a provided path string</refpurpose>
@@ -9,7 +9,7 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>string</type><methodname>ssh2_sftp_realpath</methodname>
+   <type class="union"><type>string</type><type>false</type></type><methodname>ssh2_sftp_realpath</methodname>
    <methodparam><type>resource</type><parameter>sftp</parameter></methodparam>
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   </methodsynopsis>
@@ -43,7 +43,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Returns the real path as a string.
+   Returns the real path as a string&return.falseforfailure;.
   </simpara>
  </refsect1>
 
diff --git a/reference/ssh2/functions/ssh2-sftp-stat.xml b/reference/ssh2/functions/ssh2-sftp-stat.xml
index 1c4756122fde..7c42d5c41028 100644
--- a/reference/ssh2/functions/ssh2-sftp-stat.xml
+++ b/reference/ssh2/functions/ssh2-sftp-stat.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.ssh2-sftp-stat">
+<refentry xml:id="function.ssh2-sftp-stat" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>ssh2_sftp_stat</refname>
   <refpurpose>Stat a file on a remote filesystem</refpurpose>
@@ -9,7 +9,7 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>array</type><methodname>ssh2_sftp_stat</methodname>
+   <type class="union"><type>array</type><type>false</type></type><methodname>ssh2_sftp_stat</methodname>
    <methodparam><type>resource</type><parameter>sftp</parameter></methodparam>
    <methodparam><type>string</type><parameter>path</parameter></methodparam>
   </methodsynopsis>
@@ -47,6 +47,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
+   Returns an array of statistics for the given file on success&return.falseforfailure;.
    See the documentation for <function>stat</function> for details on the
    values which may be returned.
   </simpara>