vendor/phpseclib/phpseclib/phpseclib/Net/SFTP.php line 441

Open in your IDE?
  1. <?php
  3. /**
  4.  * Pure-PHP implementation of SFTP.
  5.  *
  6.  * PHP version 5
  7.  *
  8.  * Currently only supports SFTPv2 and v3, which, according to wikipedia.org, "is the most widely used version,
  9.  * implemented by the popular OpenSSH SFTP server".  If you want SFTPv4/5/6 support, provide me with access
  10.  * to an SFTPv4/5/6 server.
  11.  *
  12.  * The API for this library is modeled after the API from PHP's {@link http://php.net/book.ftp FTP extension}.
  13.  *
  14.  * Here's a short example of how to use this library:
  15.  * <code>
  16.  * <?php
  17.  *    include 'vendor/autoload.php';
  18.  *
  19.  *    $sftp = new \phpseclib3\Net\SFTP('www.domain.tld');
  20.  *    if (!$sftp->login('username', 'password')) {
  21.  *        exit('Login Failed');
  22.  *    }
  23.  *
  24.  *    echo $sftp->pwd() . "\r\n";
  25.  *    $sftp->put('filename.ext', 'hello, world!');
  26.  *    print_r($sftp->nlist());
  27.  * ?>
  28.  * </code>
  29.  *
  30.  * @category  Net
  31.  * @package   SFTP
  32.  * @author    Jim Wigginton <terrafrost@php.net>
  33.  * @copyright 2009 Jim Wigginton
  34.  * @license   http://www.opensource.org/licenses/mit-license.html  MIT License
  35.  * @link      http://phpseclib.sourceforge.net
  36.  */
  38. namespace phpseclib3\Net;
  40. use phpseclib3\Exception\FileNotFoundException;
  41. use phpseclib3\Common\Functions\Strings;
  42. use phpseclib3\Crypt\Common\AsymmetricKey;
  43. use phpseclib3\System\SSH\Agent;
  45. /**
  46.  * Pure-PHP implementations of SFTP.
  47.  *
  48.  * @package SFTP
  49.  * @author  Jim Wigginton <terrafrost@php.net>
  50.  * @access  public
  51.  */
  52. class SFTP extends SSH2
  53. {
  54.     /**
  55.      * SFTP channel constant
  56.      *
  57.      * \phpseclib3\Net\SSH2::exec() uses 0 and \phpseclib3\Net\SSH2::read() / \phpseclib3\Net\SSH2::write() use 1.
  58.      *
  59.      * @see \phpseclib3\Net\SSH2::send_channel_packet()
  60.      * @see \phpseclib3\Net\SSH2::get_channel_packet()
  61.      * @access private
  62.      */
  63.     const CHANNEL = 0x100;
  65.     /**
  66.      * Reads data from a local file.
  67.      *
  68.      * @access public
  69.      * @see \phpseclib3\Net\SFTP::put()
  70.      */
  71.     const SOURCE_LOCAL_FILE = 1;
  72.     /**
  73.      * Reads data from a string.
  74.      *
  75.      * @access public
  76.      * @see \phpseclib3\Net\SFTP::put()
  77.      */
  78.     // this value isn't really used anymore but i'm keeping it reserved for historical reasons
  79.     const SOURCE_STRING = 2;
  80.     /**
  81.      * Reads data from callback:
  82.      * function callback($length) returns string to proceed, null for EOF
  83.      *
  84.      * @access public
  85.      * @see \phpseclib3\Net\SFTP::put()
  86.      */
  87.     const SOURCE_CALLBACK = 16;
  88.     /**
  89.      * Resumes an upload
  90.      *
  91.      * @access public
  92.      * @see \phpseclib3\Net\SFTP::put()
  93.      */
  94.     const RESUME = 4;
  95.     /**
  96.      * Append a local file to an already existing remote file
  97.      *
  98.      * @access public
  99.      * @see \phpseclib3\Net\SFTP::put()
  100.      */
  101.     const RESUME_START = 8;
  103.     /**
  104.      * Packet Types
  105.      *
  106.      * @see self::__construct()
  107.      * @var array
  108.      * @access private
  109.      */
  110.     private $packet_types = [];
  112.     /**
  113.      * Status Codes
  114.      *
  115.      * @see self::__construct()
  116.      * @var array
  117.      * @access private
  118.      */
  119.     private $status_codes = [];
  121.     /**
  122.      * The Request ID
  123.      *
  124.      * The request ID exists in the off chance that a packet is sent out-of-order.  Of course, this library doesn't support
  125.      * concurrent actions, so it's somewhat academic, here.
  126.      *
  127.      * @var boolean
  128.      * @see self::_send_sftp_packet()
  129.      * @access private
  130.      */
  131.     private $use_request_id = false;
  133.     /**
  134.      * The Packet Type
  135.      *
  136.      * The request ID exists in the off chance that a packet is sent out-of-order.  Of course, this library doesn't support
  137.      * concurrent actions, so it's somewhat academic, here.
  138.      *
  139.      * @var int
  140.      * @see self::_get_sftp_packet()
  141.      * @access private
  142.      */
  143.     private $packet_type = -1;
  145.     /**
  146.      * Packet Buffer
  147.      *
  148.      * @var string
  149.      * @see self::_get_sftp_packet()
  150.      * @access private
  151.      */
  152.     private $packet_buffer = '';
  154.     /**
  155.      * Extensions supported by the server
  156.      *
  157.      * @var array
  158.      * @see self::_initChannel()
  159.      * @access private
  160.      */
  161.     private $extensions = [];
  163.     /**
  164.      * Server SFTP version
  165.      *
  166.      * @var int
  167.      * @see self::_initChannel()
  168.      * @access private
  169.      */
  170.     private $version;
  172.     /**
  173.      * Current working directory
  174.      *
  175.      * @var string
  176.      * @see self::realpath()
  177.      * @see self::chdir()
  178.      * @access private
  179.      */
  180.     private $pwd = false;
  182.     /**
  183.      * Packet Type Log
  184.      *
  185.      * @see self::getLog()
  186.      * @var array
  187.      * @access private
  188.      */
  189.     private $packet_type_log = [];
  191.     /**
  192.      * Packet Log
  193.      *
  194.      * @see self::getLog()
  195.      * @var array
  196.      * @access private
  197.      */
  198.     private $packet_log = [];
  200.     /**
  201.      * Error information
  202.      *
  203.      * @see self::getSFTPErrors()
  204.      * @see self::getLastSFTPError()
  205.      * @var array
  206.      * @access private
  207.      */
  208.     private $sftp_errors = [];
  210.     /**
  211.      * Stat Cache
  212.      *
  213.      * Rather than always having to open a directory and close it immediately there after to see if a file is a directory
  214.      * we'll cache the results.
  215.      *
  216.      * @see self::_update_stat_cache()
  217.      * @see self::_remove_from_stat_cache()
  218.      * @see self::_query_stat_cache()
  219.      * @var array
  220.      * @access private
  221.      */
  222.     private $stat_cache = [];
  224.     /**
  225.      * Max SFTP Packet Size
  226.      *
  227.      * @see self::__construct()
  228.      * @see self::get()
  229.      * @var array
  230.      * @access private
  231.      */
  232.     private $max_sftp_packet;
  234.     /**
  235.      * Stat Cache Flag
  236.      *
  237.      * @see self::disableStatCache()
  238.      * @see self::enableStatCache()
  239.      * @var bool
  240.      * @access private
  241.      */
  242.     private $use_stat_cache = true;
  244.     /**
  245.      * Sort Options
  246.      *
  247.      * @see self::_comparator()
  248.      * @see self::setListOrder()
  249.      * @var array
  250.      * @access private
  251.      */
  252.     protected $sortOptions = [];
  254.     /**
  255.      * Canonicalization Flag
  256.      *
  257.      * Determines whether or not paths should be canonicalized before being
  258.      * passed on to the remote server.
  259.      *
  260.      * @see self::enablePathCanonicalization()
  261.      * @see self::disablePathCanonicalization()
  262.      * @see self::realpath()
  263.      * @var bool
  264.      * @access private
  265.      */
  266.     private $canonicalize_paths = true;
  268.     /**
  269.      * Request Buffers
  270.      *
  271.      * @see self::_get_sftp_packet()
  272.      * @var array
  273.      * @access private
  274.      */
  275.     var $requestBuffer = array();
  277.     /**
  278.      * Preserve timestamps on file downloads / uploads
  279.      *
  280.      * @see self::get()
  281.      * @see self::put()
  282.      * @var bool
  283.      * @access private
  284.      */
  285.     var $preserveTime = false;
  287.     /**
  288.      * Default Constructor.
  289.      *
  290.      * Connects to an SFTP server
  291.      *
  292.      * @param string $host
  293.      * @param int $port
  294.      * @param int $timeout
  295.      * @return \phpseclib3\Net\SFTP
  296.      * @access public
  297.      */
  298.     public function __construct($host, $port = 22, $timeout = 10)
  299.     {
  300.         parent::__construct($host, $port, $timeout);
  302.         $this->max_sftp_packet = 1 << 15;
  304.         $this->packet_types = [
  305.             1  => 'NET_SFTP_INIT',
  306.             2  => 'NET_SFTP_VERSION',
  307.             /* the format of SSH_FXP_OPEN changed between SFTPv4 and SFTPv5+:
  308.                    SFTPv5+: http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.1.1
  309.                pre-SFTPv5 : http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-6.3 */
  310.             3  => 'NET_SFTP_OPEN',
  311.             4  => 'NET_SFTP_CLOSE',
  312.             5  => 'NET_SFTP_READ',
  313.             6  => 'NET_SFTP_WRITE',
  314.             7  => 'NET_SFTP_LSTAT',
  315.             9  => 'NET_SFTP_SETSTAT',
  316.             11 => 'NET_SFTP_OPENDIR',
  317.             12 => 'NET_SFTP_READDIR',
  318.             13 => 'NET_SFTP_REMOVE',
  319.             14 => 'NET_SFTP_MKDIR',
  320.             15 => 'NET_SFTP_RMDIR',
  321.             16 => 'NET_SFTP_REALPATH',
  322.             17 => 'NET_SFTP_STAT',
  323.             /* the format of SSH_FXP_RENAME changed between SFTPv4 and SFTPv5+:
  324.                    SFTPv5+: http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.3
  325.                pre-SFTPv5 : http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-6.5 */
  326.             18 => 'NET_SFTP_RENAME',
  327.             19 => 'NET_SFTP_READLINK',
  328.             20 => 'NET_SFTP_SYMLINK',
  330.             101=> 'NET_SFTP_STATUS',
  331.             102=> 'NET_SFTP_HANDLE',
  332.             /* the format of SSH_FXP_NAME changed between SFTPv3 and SFTPv4+:
  333.                    SFTPv4+: http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-9.4
  334.                pre-SFTPv4 : http://tools.ietf.org/html/draft-ietf-secsh-filexfer-02#section-7 */
  335.             103=> 'NET_SFTP_DATA',
  336.             104=> 'NET_SFTP_NAME',
  337.             105=> 'NET_SFTP_ATTRS',
  339.             200=> 'NET_SFTP_EXTENDED'
  340.         ];
  341.         $this->status_codes = [
  342.             0 => 'NET_SFTP_STATUS_OK',
  343.             1 => 'NET_SFTP_STATUS_EOF',
  344.             2 => 'NET_SFTP_STATUS_NO_SUCH_FILE',
  345.             3 => 'NET_SFTP_STATUS_PERMISSION_DENIED',
  346.             4 => 'NET_SFTP_STATUS_FAILURE',
  347.             5 => 'NET_SFTP_STATUS_BAD_MESSAGE',
  348.             6 => 'NET_SFTP_STATUS_NO_CONNECTION',
  349.             7 => 'NET_SFTP_STATUS_CONNECTION_LOST',
  350.             8 => 'NET_SFTP_STATUS_OP_UNSUPPORTED',
  351.             9 => 'NET_SFTP_STATUS_INVALID_HANDLE',
  352.             10 => 'NET_SFTP_STATUS_NO_SUCH_PATH',
  353.             11 => 'NET_SFTP_STATUS_FILE_ALREADY_EXISTS',
  354.             12 => 'NET_SFTP_STATUS_WRITE_PROTECT',
  355.             13 => 'NET_SFTP_STATUS_NO_MEDIA',
  356.             14 => 'NET_SFTP_STATUS_NO_SPACE_ON_FILESYSTEM',
  357.             15 => 'NET_SFTP_STATUS_QUOTA_EXCEEDED',
  358.             16 => 'NET_SFTP_STATUS_UNKNOWN_PRINCIPAL',
  359.             17 => 'NET_SFTP_STATUS_LOCK_CONFLICT',
  360.             18 => 'NET_SFTP_STATUS_DIR_NOT_EMPTY',
  361.             19 => 'NET_SFTP_STATUS_NOT_A_DIRECTORY',
  362.             20 => 'NET_SFTP_STATUS_INVALID_FILENAME',
  363.             21 => 'NET_SFTP_STATUS_LINK_LOOP',
  364.             22 => 'NET_SFTP_STATUS_CANNOT_DELETE',
  365.             23 => 'NET_SFTP_STATUS_INVALID_PARAMETER',
  366.             24 => 'NET_SFTP_STATUS_FILE_IS_A_DIRECTORY',
  367.             25 => 'NET_SFTP_STATUS_BYTE_RANGE_LOCK_CONFLICT',
  368.             26 => 'NET_SFTP_STATUS_BYTE_RANGE_LOCK_REFUSED',
  369.             27 => 'NET_SFTP_STATUS_DELETE_PENDING',
  370.             28 => 'NET_SFTP_STATUS_FILE_CORRUPT',
  371.             29 => 'NET_SFTP_STATUS_OWNER_INVALID',
  372.             30 => 'NET_SFTP_STATUS_GROUP_INVALID',
  373.             31 => 'NET_SFTP_STATUS_NO_MATCHING_BYTE_RANGE_LOCK'
  374.         ];
  375.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-7.1
  376.         // the order, in this case, matters quite a lot - see \phpseclib3\Net\SFTP::_parseAttributes() to understand why
  377.         $this->attributes = [
  378.             0x00000001 => 'NET_SFTP_ATTR_SIZE',
  379.             0x00000002 => 'NET_SFTP_ATTR_UIDGID', // defined in SFTPv3, removed in SFTPv4+
  380.             0x00000004 => 'NET_SFTP_ATTR_PERMISSIONS',
  381.             0x00000008 => 'NET_SFTP_ATTR_ACCESSTIME',
  382.             // 0x80000000 will yield a floating point on 32-bit systems and converting floating points to integers
  383.             // yields inconsistent behavior depending on how php is compiled.  so we left shift -1 (which, in
  384.             // two's compliment, consists of all 1 bits) by 31.  on 64-bit systems this'll yield 0xFFFFFFFF80000000.
  385.             // that's not a problem, however, and 'anded' and a 32-bit number, as all the leading 1 bits are ignored.
  386.             (-1 << 31) & 0xFFFFFFFF => 'NET_SFTP_ATTR_EXTENDED'
  387.         ];
  388.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-6.3
  389.         // the flag definitions change somewhat in SFTPv5+.  if SFTPv5+ support is added to this library, maybe name
  390.         // the array for that $this->open5_flags and similarly alter the constant names.
  391.         $this->open_flags = [
  392.             0x00000001 => 'NET_SFTP_OPEN_READ',
  393.             0x00000002 => 'NET_SFTP_OPEN_WRITE',
  394.             0x00000004 => 'NET_SFTP_OPEN_APPEND',
  395.             0x00000008 => 'NET_SFTP_OPEN_CREATE',
  396.             0x00000010 => 'NET_SFTP_OPEN_TRUNCATE',
  397.             0x00000020 => 'NET_SFTP_OPEN_EXCL'
  398.         ];
  399.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-5.2
  400.         // see \phpseclib3\Net\SFTP::_parseLongname() for an explanation
  401.         $this->file_types = [
  402.             1 => 'NET_SFTP_TYPE_REGULAR',
  403.             2 => 'NET_SFTP_TYPE_DIRECTORY',
  404.             3 => 'NET_SFTP_TYPE_SYMLINK',
  405.             4 => 'NET_SFTP_TYPE_SPECIAL',
  406.             5 => 'NET_SFTP_TYPE_UNKNOWN',
  407.             // the following types were first defined for use in SFTPv5+
  408.             // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-05#section-5.2
  409.             6 => 'NET_SFTP_TYPE_SOCKET',
  410.             7 => 'NET_SFTP_TYPE_CHAR_DEVICE',
  411.             8 => 'NET_SFTP_TYPE_BLOCK_DEVICE',
  412.             9 => 'NET_SFTP_TYPE_FIFO'
  413.         ];
  414.         $this->define_array(
  415.             $this->packet_types,
  416.             $this->status_codes,
  417.             $this->attributes,
  418.             $this->open_flags,
  419.             $this->file_types
  420.         );
  422.         if (!defined('NET_SFTP_QUEUE_SIZE')) {
  423.             define('NET_SFTP_QUEUE_SIZE', 32);
  424.         }
  425.         if (!defined('NET_SFTP_UPLOAD_QUEUE_SIZE')) {
  426.             define('NET_SFTP_UPLOAD_QUEUE_SIZE', 1024);
  427.         }
  428.     }
  430.     /**
  431.      * Login
  432.      *
  433.      * @param string $username
  434.      * @param string|AsymmetricKey|array[]|Agent|null ...$args
  435.      * @throws \UnexpectedValueException on receipt of unexpected packets
  436.      * @return bool
  437.      * @access public
  438.      */
  439.     public function login($username, ...$args)
  440.     {
  441.         if (!parent::login(...func_get_args())) {
  442.             return false;
  443.         }
  445.         $this->window_size_server_to_client[self::CHANNEL] = $this->window_size;
  447.         $packet = Strings::packSSH2(
  448.             'CsN3',
  449.             NET_SSH2_MSG_CHANNEL_OPEN,
  450.             'session',
  451.             self::CHANNEL,
  452.             $this->window_size,
  453.             0x4000
  454.         );
  456.         $this->send_binary_packet($packet);
  458.         $this->channel_status[self::CHANNEL] = NET_SSH2_MSG_CHANNEL_OPEN;
  460.         $response = $this->get_channel_packet(self::CHANNEL, true);
  461.         if ($response === false) {
  462.             return false;
  463.         }
  465.         $packet = Strings::packSSH2(
  466.             'CNsbs',
  467.             NET_SSH2_MSG_CHANNEL_REQUEST,
  468.             $this->server_channels[self::CHANNEL],
  469.             'subsystem',
  470.             true,
  471.             'sftp'
  472.         );
  473.         $this->send_binary_packet($packet);
  475.         $this->channel_status[self::CHANNEL] = NET_SSH2_MSG_CHANNEL_REQUEST;
  477.         $response = $this->get_channel_packet(self::CHANNEL, true);
  478.         if ($response === false) {
  479.             // from PuTTY's psftp.exe
  480.             $command = "test -x /usr/lib/sftp-server && exec /usr/lib/sftp-server\n" .
  481.                        "test -x /usr/local/lib/sftp-server && exec /usr/local/lib/sftp-server\n" .
  482.                        "exec sftp-server";
  483.             // we don't do $this->exec($command, false) because exec() operates on a different channel and plus the SSH_MSG_CHANNEL_OPEN that exec() does
  484.             // is redundant
  485.             $packet = Strings::packSSH2(
  486.                 'CNsCs',
  487.                 NET_SSH2_MSG_CHANNEL_REQUEST,
  488.                 $this->server_channels[self::CHANNEL],
  489.                 'exec',
  490.                 1,
  491.                 $command
  492.             );
  493.             $this->send_binary_packet($packet);
  495.             $this->channel_status[self::CHANNEL] = NET_SSH2_MSG_CHANNEL_REQUEST;
  497.             $response = $this->get_channel_packet(self::CHANNEL, true);
  498.             if ($response === false) {
  499.                 return false;
  500.             }
  501.         }
  503.         $this->channel_status[self::CHANNEL] = NET_SSH2_MSG_CHANNEL_DATA;
  505.         if (!$this->send_sftp_packet(NET_SFTP_INIT, "\0\0\0\3")) {
  506.             return false;
  507.         }
  509.         $response = $this->get_sftp_packet();
  510.         if ($this->packet_type != NET_SFTP_VERSION) {
  511.             throw new \UnexpectedValueException('Expected NET_SFTP_VERSION. '
  512.                                               . 'Got packet type: ' . $this->packet_type);
  513.         }
  515.         list($this->version) = Strings::unpackSSH2('N', $response);
  516.         while (!empty($response)) {
  517.             list($key, $value) = Strings::unpackSSH2('ss', $response);
  518.             $this->extensions[$key] = $value;
  519.         }
  521.         /*
  522.          SFTPv4+ defines a 'newline' extension.  SFTPv3 seems to have unofficial support for it via 'newline@vandyke.com',
  523.          however, I'm not sure what 'newline@vandyke.com' is supposed to do (the fact that it's unofficial means that it's
  524.          not in the official SFTPv3 specs) and 'newline@vandyke.com' / 'newline' are likely not drop-in substitutes for
  525.          one another due to the fact that 'newline' comes with a SSH_FXF_TEXT bitmask whereas it seems unlikely that
  526.          'newline@vandyke.com' would.
  527.         */
  528.         /*
  529.         if (isset($this->extensions['newline@vandyke.com'])) {
  530.             $this->extensions['newline'] = $this->extensions['newline@vandyke.com'];
  531.             unset($this->extensions['newline@vandyke.com']);
  532.         }
  533.         */
  535.         $this->use_request_id = true;
  537.         /*
  538.          A Note on SFTPv4/5/6 support:
  539.          <http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-5.1> states the following:
  541.          "If the client wishes to interoperate with servers that support noncontiguous version
  542.           numbers it SHOULD send '3'"
  544.          Given that the server only sends its version number after the client has already done so, the above
  545.          seems to be suggesting that v3 should be the default version.  This makes sense given that v3 is the
  546.          most popular.
  548.          <http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-5.5> states the following;
  550.          "If the server did not send the "versions" extension, or the version-from-list was not included, the
  551.           server MAY send a status response describing the failure, but MUST then close the channel without
  552.           processing any further requests."
  554.          So what do you do if you have a client whose initial SSH_FXP_INIT packet says it implements v3 and
  555.          a server whose initial SSH_FXP_VERSION reply says it implements v4 and only v4?  If it only implements
  556.          v4, the "versions" extension is likely not going to have been sent so version re-negotiation as discussed
  557.          in draft-ietf-secsh-filexfer-13 would be quite impossible.  As such, what \phpseclib3\Net\SFTP would do is close the
  558.          channel and reopen it with a new and updated SSH_FXP_INIT packet.
  559.         */
  560.         switch ($this->version) {
  561.             case 2:
  562.             case 3:
  563.                 break;
  564.             default:
  565.                 return false;
  566.         }
  568.         $this->pwd = $this->realpath('.');
  570.         $this->update_stat_cache($this->pwd, []);
  572.         return true;
  573.     }
  575.     /**
  576.      * Disable the stat cache
  577.      *
  578.      * @access public
  579.      */
  580.     function disableStatCache()
  581.     {
  582.         $this->use_stat_cache = false;
  583.     }
  585.     /**
  586.      * Enable the stat cache
  587.      *
  588.      * @access public
  589.      */
  590.     public function enableStatCache()
  591.     {
  592.         $this->use_stat_cache = true;
  593.     }
  595.     /**
  596.      * Clear the stat cache
  597.      *
  598.      * @access public
  599.      */
  600.     public function clearStatCache()
  601.     {
  602.         $this->stat_cache = [];
  603.     }
  605.     /**
  606.      * Enable path canonicalization
  607.      *
  608.      * @access public
  609.      */
  610.     public function enablePathCanonicalization()
  611.     {
  612.         $this->canonicalize_paths = true;
  613.     }
  615.     /**
  616.      * Enable path canonicalization
  617.      *
  618.      * @access public
  619.      */
  620.     public function disablePathCanonicalization()
  621.     {
  622.         $this->canonicalize_paths = false;
  623.     }
  625.     /**
  626.      * Returns the current directory name
  627.      *
  628.      * @return mixed
  629.      * @access public
  630.      */
  631.     public function pwd()
  632.     {
  633.         return $this->pwd;
  634.     }
  636.     /**
  637.      * Logs errors
  638.      *
  639.      * @param string $response
  640.      * @param int $status
  641.      * @access private
  642.      */
  643.     private function logError($response, $status = -1)
  644.     {
  645.         if ($status == -1) {
  646.             list($status) = Strings::unpackSSH2('N', $response);
  647.         }
  649.         list($error) = $this->status_codes[$status];
  651.         if ($this->version > 2) {
  652.             list($message) = Strings::unpackSSH2('s', $response);
  653.             $this->sftp_errors[] = "$error: $message";
  654.         } else {
  655.             $this->sftp_errors[] = $error;
  656.         }
  657.     }
  659.     /**
  660.      * Canonicalize the Server-Side Path Name
  661.      *
  662.      * SFTP doesn't provide a mechanism by which the current working directory can be changed, so we'll emulate it.  Returns
  663.      * the absolute (canonicalized) path.
  664.      *
  665.      * If canonicalize_paths has been disabled using disablePathCanonicalization(), $path is returned as-is.
  666.      *
  667.      * @see self::chdir()
  668.      * @see self::disablePathCanonicalization()
  669.      * @param string $path
  670.      * @throws \UnexpectedValueException on receipt of unexpected packets
  671.      * @return mixed
  672.      * @access public
  673.      */
  674.     public function realpath($path)
  675.     {
  676.         if (!$this->canonicalize_paths) {
  677.             return $path;
  678.         }
  680.         if ($this->pwd === false) {
  681.             // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.9
  682.             if (!$this->send_sftp_packet(NET_SFTP_REALPATH, Strings::packSSH2('s', $path))) {
  683.                 return false;
  684.             }
  686.             $response = $this->get_sftp_packet();
  687.             switch ($this->packet_type) {
  688.                 case NET_SFTP_NAME:
  689.                     // although SSH_FXP_NAME is implemented differently in SFTPv3 than it is in SFTPv4+, the following
  690.                     // should work on all SFTP versions since the only part of the SSH_FXP_NAME packet the following looks
  691.                     // at is the first part and that part is defined the same in SFTP versions 3 through 6.
  692.                     list(, $filename) = Strings::unpackSSH2('Ns', $response);
  693.                     return $filename;
  694.                 case NET_SFTP_STATUS:
  695.                     $this->logError($response);
  696.                     return false;
  697.                 default:
  698.                     throw new \UnexpectedValueException('Expected NET_SFTP_NAME or NET_SFTP_STATUS. '
  699.                                                       . 'Got packet type: ' . $this->packet_type);
  700.             }
  701.         }
  703.         if (!strlen($path) || $path[0] != '/') {
  704.             $path = $this->pwd . '/' . $path;
  705.         }
  707.         $path = explode('/', $path);
  708.         $new = [];
  709.         foreach ($path as $dir) {
  710.             if (!strlen($dir)) {
  711.                 continue;
  712.             }
  713.             switch ($dir) {
  714.                 case '..':
  715.                     array_pop($new);
  716.                 case '.':
  717.                     break;
  718.                 default:
  719.                     $new[] = $dir;
  720.             }
  721.         }
  723.         return '/' . implode('/', $new);
  724.     }
  726.     /**
  727.      * Changes the current directory
  728.      *
  729.      * @param string $dir
  730.      * @throws \UnexpectedValueException on receipt of unexpected packets
  731.      * @return bool
  732.      * @access public
  733.      */
  734.     public function chdir($dir)
  735.     {
  736.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  737.             return false;
  738.         }
  740.         // assume current dir if $dir is empty
  741.         if ($dir === '') {
  742.             $dir = './';
  743.         // suffix a slash if needed
  744.         } elseif ($dir[strlen($dir) - 1] != '/') {
  745.             $dir.= '/';
  746.         }
  748.         $dir = $this->realpath($dir);
  750.         // confirm that $dir is, in fact, a valid directory
  751.         if ($this->use_stat_cache && is_array($this->query_stat_cache($dir))) {
  752.             $this->pwd = $dir;
  753.             return true;
  754.         }
  756.         // we could do a stat on the alleged $dir to see if it's a directory but that doesn't tell us
  757.         // the currently logged in user has the appropriate permissions or not. maybe you could see if
  758.         // the file's uid / gid match the currently logged in user's uid / gid but how there's no easy
  759.         // way to get those with SFTP
  761.         if (!$this->send_sftp_packet(NET_SFTP_OPENDIR, Strings::packSSH2('s', $dir))) {
  762.             return false;
  763.         }
  765.         // see \phpseclib3\Net\SFTP::nlist() for a more thorough explanation of the following
  766.         $response = $this->get_sftp_packet();
  767.         switch ($this->packet_type) {
  768.             case NET_SFTP_HANDLE:
  769.                 $handle = substr($response, 4);
  770.                 break;
  771.             case NET_SFTP_STATUS:
  772.                 $this->logError($response);
  773.                 return false;
  774.             default:
  775.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS' .
  776.                                                     'Got packet type: ' . $this->packet_type);
  777.         }
  779.         if (!$this->close_handle($handle)) {
  780.             return false;
  781.         }
  783.         $this->update_stat_cache($dir, []);
  785.         $this->pwd = $dir;
  786.         return true;
  787.     }
  789.     /**
  790.      * Returns a list of files in the given directory
  791.      *
  792.      * @param string $dir
  793.      * @param bool $recursive
  794.      * @return mixed
  795.      * @access public
  796.      */
  797.     public function nlist($dir = '.', $recursive = false)
  798.     {
  799.         return $this->nlist_helper($dir, $recursive, '');
  800.     }
  802.     /**
  803.      * Helper method for nlist
  804.      *
  805.      * @param string $dir
  806.      * @param bool $recursive
  807.      * @param string $relativeDir
  808.      * @return mixed
  809.      * @access private
  810.      */
  811.     private function nlist_helper($dir, $recursive, $relativeDir)
  812.     {
  813.         $files = $this->readlist($dir, false);
  815.         if (!$recursive || $files === false) {
  816.             return $files;
  817.         }
  819.         $result = [];
  820.         foreach ($files as $value) {
  821.             if ($value == '.' || $value == '..') {
  822.                 $result[] = $relativeDir . $value;
  823.                 continue;
  824.             }
  825.             if (is_array($this->query_stat_cache($this->realpath($dir . '/' . $value)))) {
  826.                 $temp = $this->nlist_helper($dir . '/' . $value, true, $relativeDir . $value . '/');
  827.                 $temp = is_array($temp) ? $temp : [];
  828.                 $result = array_merge($result, $temp);
  829.             } else {
  830.                 $result[] = $relativeDir . $value;
  831.             }
  832.         }
  834.         return $result;
  835.     }
  837.     /**
  838.      * Returns a detailed list of files in the given directory
  839.      *
  840.      * @param string $dir
  841.      * @param bool $recursive
  842.      * @return mixed
  843.      * @access public
  844.      */
  845.     public function rawlist($dir = '.', $recursive = false)
  846.     {
  847.         $files = $this->readlist($dir, true);
  848.         if (!$recursive || $files === false) {
  849.             return $files;
  850.         }
  852.         static $depth = 0;
  854.         foreach ($files as $key => $value) {
  855.             if ($depth != 0 && $key == '..') {
  856.                 unset($files[$key]);
  857.                 continue;
  858.             }
  859.             $is_directory = false;
  860.             if ($key != '.' && $key != '..') {
  861.                 if ($this->use_stat_cache) {
  862.                     $is_directory = is_array($this->query_stat_cache($this->realpath($dir . '/' . $key)));
  863.                 } else {
  864.                     $stat = $this->lstat($dir . '/' . $key);
  865.                     $is_directory = $stat && $stat['type'] === NET_SFTP_TYPE_DIRECTORY;
  866.                 }
  867.             }
  869.             if ($is_directory) {
  870.                 $depth++;
  871.                 $files[$key] = $this->rawlist($dir . '/' . $key, true);
  872.                 $depth--;
  873.             } else {
  874.                 $files[$key] = (object) $value;
  875.             }
  876.         }
  878.         return $files;
  879.     }
  881.     /**
  882.      * Reads a list, be it detailed or not, of files in the given directory
  883.      *
  884.      * @param string $dir
  885.      * @param bool $raw
  886.      * @return mixed
  887.      * @throws \UnexpectedValueException on receipt of unexpected packets
  888.      * @access private
  889.      */
  890.     private function readlist($dir, $raw = true)
  891.     {
  892.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  893.             return false;
  894.         }
  896.         $dir = $this->realpath($dir . '/');
  897.         if ($dir === false) {
  898.             return false;
  899.         }
  901.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.1.2
  902.         if (!$this->send_sftp_packet(NET_SFTP_OPENDIR, Strings::packSSH2('s', $dir))) {
  903.             return false;
  904.         }
  906.         $response = $this->get_sftp_packet();
  907.         switch ($this->packet_type) {
  908.             case NET_SFTP_HANDLE:
  909.                 // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-9.2
  910.                 // since 'handle' is the last field in the SSH_FXP_HANDLE packet, we'll just remove the first four bytes that
  911.                 // represent the length of the string and leave it at that
  912.                 $handle = substr($response, 4);
  913.                 break;
  914.             case NET_SFTP_STATUS:
  915.                 // presumably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  916.                 $this->logError($response);
  917.                 return false;
  918.             default:
  919.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS. '
  920.                                                   . 'Got packet type: ' . $this->packet_type);
  921.         }
  923.         $this->update_stat_cache($dir, []);
  925.         $contents = [];
  926.         while (true) {
  927.             // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.2.2
  928.             // why multiple SSH_FXP_READDIR packets would be sent when the response to a single one can span arbitrarily many
  929.             // SSH_MSG_CHANNEL_DATA messages is not known to me.
  930.             if (!$this->send_sftp_packet(NET_SFTP_READDIR, Strings::packSSH2('s', $handle))) {
  931.                 return false;
  932.             }
  934.             $response = $this->get_sftp_packet();
  935.             switch ($this->packet_type) {
  936.                 case NET_SFTP_NAME:
  937.                     list($count) = Strings::unpackSSH2('N', $response);
  938.                     for ($i = 0; $i < $count; $i++) {
  939.                         list($shortname, $longname) = Strings::unpackSSH2('ss', $response);
  940.                         $attributes = $this->parseAttributes($response);
  941.                         if (!isset($attributes['type'])) {
  942.                             $fileType = $this->parseLongname($longname);
  943.                             if ($fileType) {
  944.                                 $attributes['type'] = $fileType;
  945.                             }
  946.                         }
  947.                         $contents[$shortname] = $attributes + ['filename' => $shortname];
  949.                         if (isset($attributes['type']) && $attributes['type'] == NET_SFTP_TYPE_DIRECTORY && ($shortname != '.' && $shortname != '..')) {
  950.                             $this->update_stat_cache($dir . '/' . $shortname, []);
  951.                         } else {
  952.                             if ($shortname == '..') {
  953.                                 $temp = $this->realpath($dir . '/..') . '/.';
  954.                             } else {
  955.                                 $temp = $dir . '/' . $shortname;
  956.                             }
  957.                             $this->update_stat_cache($temp, (object) ['lstat' => $attributes]);
  958.                         }
  959.                         // SFTPv6 has an optional boolean end-of-list field, but we'll ignore that, since the
  960.                         // final SSH_FXP_STATUS packet should tell us that, already.
  961.                     }
  962.                     break;
  963.                 case NET_SFTP_STATUS:
  964.                     list($status) = Strings::unpackSSH2('N', $response);
  965.                     if ($status != NET_SFTP_STATUS_EOF) {
  966.                         $this->logError($response, $status);
  967.                         return false;
  968.                     }
  969.                     break 2;
  970.                 default:
  971.                     throw new \UnexpectedValueException('Expected NET_SFTP_NAME or NET_SFTP_STATUS. '
  972.                                                       . 'Got packet type: ' . $this->packet_type);
  973.             }
  974.         }
  976.         if (!$this->close_handle($handle)) {
  977.             return false;
  978.         }
  980.         if (count($this->sortOptions)) {
  981.             uasort($contents, [&$this, 'comparator']);
  982.         }
  984.         return $raw ? $contents : array_map('strval', array_keys($contents));
  985.     }
  987.     /**
  988.      * Compares two rawlist entries using parameters set by setListOrder()
  989.      *
  990.      * Intended for use with uasort()
  991.      *
  992.      * @param array $a
  993.      * @param array $b
  994.      * @return int
  995.      * @access private
  996.      */
  997.     private function comparator($a, $b)
  998.     {
  999.         switch (true) {
  1000.             case $a['filename'] === '.' || $b['filename'] === '.':
  1001.                 if ($a['filename'] === $b['filename']) {
  1002.                     return 0;
  1003.                 }
  1004.                 return $a['filename'] === '.' ? -1 : 1;
  1005.             case $a['filename'] === '..' || $b['filename'] === '..':
  1006.                 if ($a['filename'] === $b['filename']) {
  1007.                     return 0;
  1008.                 }
  1009.                 return $a['filename'] === '..' ? -1 : 1;
  1010.             case isset($a['type']) && $a['type'] === NET_SFTP_TYPE_DIRECTORY:
  1011.                 if (!isset($b['type'])) {
  1012.                     return 1;
  1013.                 }
  1014.                 if ($b['type'] !== $a['type']) {
  1015.                     return -1;
  1016.                 }
  1017.                 break;
  1018.             case isset($b['type']) && $b['type'] === NET_SFTP_TYPE_DIRECTORY:
  1019.                 return 1;
  1020.         }
  1021.         foreach ($this->sortOptions as $sort => $order) {
  1022.             if (!isset($a[$sort]) || !isset($b[$sort])) {
  1023.                 if (isset($a[$sort])) {
  1024.                     return -1;
  1025.                 }
  1026.                 if (isset($b[$sort])) {
  1027.                     return 1;
  1028.                 }
  1029.                 return 0;
  1030.             }
  1031.             switch ($sort) {
  1032.                 case 'filename':
  1033.                     $result = strcasecmp($a['filename'], $b['filename']);
  1034.                     if ($result) {
  1035.                         return $order === SORT_DESC ? -$result : $result;
  1036.                     }
  1037.                     break;
  1038.                 case 'mode':
  1039.                     $a[$sort]&= 07777;
  1040.                     $b[$sort]&= 07777;
  1041.                 default:
  1042.                     if ($a[$sort] === $b[$sort]) {
  1043.                         break;
  1044.                     }
  1045.                     return $order === SORT_ASC ? $a[$sort] - $b[$sort] : $b[$sort] - $a[$sort];
  1046.             }
  1047.         }
  1048.     }
  1050.     /**
  1051.      * Defines how nlist() and rawlist() will be sorted - if at all.
  1052.      *
  1053.      * If sorting is enabled directories and files will be sorted independently with
  1054.      * directories appearing before files in the resultant array that is returned.
  1055.      *
  1056.      * Any parameter returned by stat is a valid sort parameter for this function.
  1057.      * Filename comparisons are case insensitive.
  1058.      *
  1059.      * Examples:
  1060.      *
  1061.      * $sftp->setListOrder('filename', SORT_ASC);
  1062.      * $sftp->setListOrder('size', SORT_DESC, 'filename', SORT_ASC);
  1063.      * $sftp->setListOrder(true);
  1064.      *    Separates directories from files but doesn't do any sorting beyond that
  1065.      * $sftp->setListOrder();
  1066.      *    Don't do any sort of sorting
  1067.      *
  1068.      * @param string[] ...$args
  1069.      * @access public
  1070.      */
  1071.     public function setListOrder(...$args)
  1072.     {
  1073.         $this->sortOptions = [];
  1074.         if (empty($args)) {
  1075.             return;
  1076.         }
  1077.         $len = count($args) & 0x7FFFFFFE;
  1078.         for ($i = 0; $i < $len; $i+=2) {
  1079.             $this->sortOptions[$args[$i]] = $args[$i + 1];
  1080.         }
  1081.         if (!count($this->sortOptions)) {
  1082.             $this->sortOptions = ['bogus' => true];
  1083.         }
  1084.     }
  1086.     /**
  1087.      * Save files / directories to cache
  1088.      *
  1089.      * @param string $path
  1090.      * @param mixed $value
  1091.      * @access private
  1092.      */
  1093.     private function update_stat_cache($path, $value)
  1094.     {
  1095.         if ($this->use_stat_cache === false) {
  1096.             return;
  1097.         }
  1099.         // preg_replace('#^/|/(?=/)|/$#', '', $dir) == str_replace('//', '/', trim($path, '/'))
  1100.         $dirs = explode('/', preg_replace('#^/|/(?=/)|/$#', '', $path));
  1102.         $temp = &$this->stat_cache;
  1103.         $max = count($dirs) - 1;
  1104.         foreach ($dirs as $i => $dir) {
  1105.             // if $temp is an object that means one of two things.
  1106.             //  1. a file was deleted and changed to a directory behind phpseclib's back
  1107.             //  2. it's a symlink. when lstat is done it's unclear what it's a symlink to
  1108.             if (is_object($temp)) {
  1109.                 $temp = [];
  1110.             }
  1111.             if (!isset($temp[$dir])) {
  1112.                 $temp[$dir] = [];
  1113.             }
  1114.             if ($i === $max) {
  1115.                 if (is_object($temp[$dir]) && is_object($value)) {
  1116.                     if (!isset($value->stat) && isset($temp[$dir]->stat)) {
  1117.                         $value->stat = $temp[$dir]->stat;
  1118.                     }
  1119.                     if (!isset($value->lstat) && isset($temp[$dir]->lstat)) {
  1120.                         $value->lstat = $temp[$dir]->lstat;
  1121.                     }
  1122.                 }
  1123.                 $temp[$dir] = $value;
  1124.                 break;
  1125.             }
  1126.             $temp = &$temp[$dir];
  1127.         }
  1128.     }
  1130.     /**
  1131.      * Remove files / directories from cache
  1132.      *
  1133.      * @param string $path
  1134.      * @return bool
  1135.      * @access private
  1136.      */
  1137.     private function remove_from_stat_cache($path)
  1138.     {
  1139.         $dirs = explode('/', preg_replace('#^/|/(?=/)|/$#', '', $path));
  1141.         $temp = &$this->stat_cache;
  1142.         $max = count($dirs) - 1;
  1143.         foreach ($dirs as $i => $dir) {
  1144.             if (!is_array($temp)) {
  1145.                 return false;
  1146.             }
  1147.             if ($i === $max) {
  1148.                 unset($temp[$dir]);
  1149.                 return true;
  1150.             }
  1151.             if (!isset($temp[$dir])) {
  1152.                 return false;
  1153.             }
  1154.             $temp = &$temp[$dir];
  1155.         }
  1156.     }
  1158.     /**
  1159.      * Checks cache for path
  1160.      *
  1161.      * Mainly used by file_exists
  1162.      *
  1163.      * @param string $path
  1164.      * @return mixed
  1165.      * @access private
  1166.      */
  1167.     private function query_stat_cache($path)
  1168.     {
  1169.         $dirs = explode('/', preg_replace('#^/|/(?=/)|/$#', '', $path));
  1171.         $temp = &$this->stat_cache;
  1172.         foreach ($dirs as $dir) {
  1173.             if (!is_array($temp)) {
  1174.                 return null;
  1175.             }
  1176.             if (!isset($temp[$dir])) {
  1177.                 return null;
  1178.             }
  1179.             $temp = &$temp[$dir];
  1180.         }
  1181.         return $temp;
  1182.     }
  1184.     /**
  1185.      * Returns general information about a file.
  1186.      *
  1187.      * Returns an array on success and false otherwise.
  1188.      *
  1189.      * @param string $filename
  1190.      * @return mixed
  1191.      * @access public
  1192.      */
  1193.     public function stat($filename)
  1194.     {
  1195.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1196.             return false;
  1197.         }
  1199.         $filename = $this->realpath($filename);
  1200.         if ($filename === false) {
  1201.             return false;
  1202.         }
  1204.         if ($this->use_stat_cache) {
  1205.             $result = $this->query_stat_cache($filename);
  1206.             if (is_array($result) && isset($result['.']) && isset($result['.']->stat)) {
  1207.                 return $result['.']->stat;
  1208.             }
  1209.             if (is_object($result) && isset($result->stat)) {
  1210.                 return $result->stat;
  1211.             }
  1212.         }
  1214.         $stat = $this->stat_helper($filename, NET_SFTP_STAT);
  1215.         if ($stat === false) {
  1216.             $this->remove_from_stat_cache($filename);
  1217.             return false;
  1218.         }
  1219.         if (isset($stat['type'])) {
  1220.             if ($stat['type'] == NET_SFTP_TYPE_DIRECTORY) {
  1221.                 $filename.= '/.';
  1222.             }
  1223.             $this->update_stat_cache($filename, (object) ['stat' => $stat]);
  1224.             return $stat;
  1225.         }
  1227.         $pwd = $this->pwd;
  1228.         $stat['type'] = $this->chdir($filename) ?
  1229.             NET_SFTP_TYPE_DIRECTORY :
  1230.             NET_SFTP_TYPE_REGULAR;
  1231.         $this->pwd = $pwd;
  1233.         if ($stat['type'] == NET_SFTP_TYPE_DIRECTORY) {
  1234.             $filename.= '/.';
  1235.         }
  1236.         $this->update_stat_cache($filename, (object) ['stat' => $stat]);
  1238.         return $stat;
  1239.     }
  1241.     /**
  1242.      * Returns general information about a file or symbolic link.
  1243.      *
  1244.      * Returns an array on success and false otherwise.
  1245.      *
  1246.      * @param string $filename
  1247.      * @return mixed
  1248.      * @access public
  1249.      */
  1250.     public function lstat($filename)
  1251.     {
  1252.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1253.             return false;
  1254.         }
  1256.         $filename = $this->realpath($filename);
  1257.         if ($filename === false) {
  1258.             return false;
  1259.         }
  1261.         if ($this->use_stat_cache) {
  1262.             $result = $this->query_stat_cache($filename);
  1263.             if (is_array($result) && isset($result['.']) && isset($result['.']->lstat)) {
  1264.                 return $result['.']->lstat;
  1265.             }
  1266.             if (is_object($result) && isset($result->lstat)) {
  1267.                 return $result->lstat;
  1268.             }
  1269.         }
  1271.         $lstat = $this->stat_helper($filename, NET_SFTP_LSTAT);
  1272.         if ($lstat === false) {
  1273.             $this->remove_from_stat_cache($filename);
  1274.             return false;
  1275.         }
  1276.         if (isset($lstat['type'])) {
  1277.             if ($lstat['type'] == NET_SFTP_TYPE_DIRECTORY) {
  1278.                 $filename.= '/.';
  1279.             }
  1280.             $this->update_stat_cache($filename, (object) ['lstat' => $lstat]);
  1281.             return $lstat;
  1282.         }
  1284.         $stat = $this->stat_helper($filename, NET_SFTP_STAT);
  1286.         if ($lstat != $stat) {
  1287.             $lstat = array_merge($lstat, ['type' => NET_SFTP_TYPE_SYMLINK]);
  1288.             $this->update_stat_cache($filename, (object) ['lstat' => $lstat]);
  1289.             return $stat;
  1290.         }
  1292.         $pwd = $this->pwd;
  1293.         $lstat['type'] = $this->chdir($filename) ?
  1294.             NET_SFTP_TYPE_DIRECTORY :
  1295.             NET_SFTP_TYPE_REGULAR;
  1296.         $this->pwd = $pwd;
  1298.         if ($lstat['type'] == NET_SFTP_TYPE_DIRECTORY) {
  1299.             $filename.= '/.';
  1300.         }
  1301.         $this->update_stat_cache($filename, (object) ['lstat' => $lstat]);
  1303.         return $lstat;
  1304.     }
  1306.     /**
  1307.      * Returns general information about a file or symbolic link
  1308.      *
  1309.      * Determines information without calling \phpseclib3\Net\SFTP::realpath().
  1310.      * The second parameter can be either NET_SFTP_STAT or NET_SFTP_LSTAT.
  1311.      *
  1312.      * @param string $filename
  1313.      * @param int $type
  1314.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1315.      * @return mixed
  1316.      * @access private
  1317.      */
  1318.     private function stat_helper($filename, $type)
  1319.     {
  1320.         // SFTPv4+ adds an additional 32-bit integer field - flags - to the following:
  1321.         $packet = Strings::packSSH2('s', $filename);
  1322.         if (!$this->send_sftp_packet($type, $packet)) {
  1323.             return false;
  1324.         }
  1326.         $response = $this->get_sftp_packet();
  1327.         switch ($this->packet_type) {
  1328.             case NET_SFTP_ATTRS:
  1329.                 return $this->parseAttributes($response);
  1330.             case NET_SFTP_STATUS:
  1331.                 $this->logError($response);
  1332.                 return false;
  1333.         }
  1335.         throw new \UnexpectedValueException('Expected NET_SFTP_ATTRS or NET_SFTP_STATUS. '
  1336.                                           . 'Got packet type: ' . $this->packet_type);
  1337.     }
  1339.     /**
  1340.      * Truncates a file to a given length
  1341.      *
  1342.      * @param string $filename
  1343.      * @param int $new_size
  1344.      * @return bool
  1345.      * @access public
  1346.      */
  1347.     public function truncate($filename, $new_size)
  1348.     {
  1349.         $attr = pack('N3', NET_SFTP_ATTR_SIZE, $new_size / 4294967296, $new_size); // 4294967296 == 0x100000000 == 1<<32
  1351.         return $this->setstat($filename, $attr, false);
  1352.     }
  1354.     /**
  1355.      * Sets access and modification time of file.
  1356.      *
  1357.      * If the file does not exist, it will be created.
  1358.      *
  1359.      * @param string $filename
  1360.      * @param int $time
  1361.      * @param int $atime
  1362.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1363.      * @return bool
  1364.      * @access public
  1365.      */
  1366.     public function touch($filename, $time = null, $atime = null)
  1367.     {
  1368.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1369.             return false;
  1370.         }
  1372.         $filename = $this->realpath($filename);
  1373.         if ($filename === false) {
  1374.             return false;
  1375.         }
  1377.         if (!isset($time)) {
  1378.             $time = time();
  1379.         }
  1380.         if (!isset($atime)) {
  1381.             $atime = $time;
  1382.         }
  1384.         $flags = NET_SFTP_OPEN_WRITE | NET_SFTP_OPEN_CREATE | NET_SFTP_OPEN_EXCL;
  1385.         $attr = pack('N3', NET_SFTP_ATTR_ACCESSTIME, $time, $atime);
  1386.         $packet = Strings::packSSH2('sN', $filename, $flags) . $attr;
  1387.         if (!$this->send_sftp_packet(NET_SFTP_OPEN, $packet)) {
  1388.             return false;
  1389.         }
  1391.         $response = $this->get_sftp_packet();
  1392.         switch ($this->packet_type) {
  1393.             case NET_SFTP_HANDLE:
  1394.                 return $this->close_handle(substr($response, 4));
  1395.             case NET_SFTP_STATUS:
  1396.                 $this->logError($response);
  1397.                 break;
  1398.             default:
  1399.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS. '
  1400.                                                   . 'Got packet type: ' . $this->packet_type);
  1401.         }
  1403.         return $this->setstat($filename, $attr, false);
  1404.     }
  1406.     /**
  1407.      * Changes file or directory owner
  1408.      *
  1409.      * Returns true on success or false on error.
  1410.      *
  1411.      * @param string $filename
  1412.      * @param int $uid
  1413.      * @param bool $recursive
  1414.      * @return bool
  1415.      * @access public
  1416.      */
  1417.     public function chown($filename, $uid, $recursive = false)
  1418.     {
  1419.         // quoting from <http://www.kernel.org/doc/man-pages/online/pages/man2/chown.2.html>,
  1420.         // "if the owner or group is specified as -1, then that ID is not changed"
  1421.         $attr = pack('N3', NET_SFTP_ATTR_UIDGID, $uid, -1);
  1423.         return $this->setstat($filename, $attr, $recursive);
  1424.     }
  1426.     /**
  1427.      * Changes file or directory group
  1428.      *
  1429.      * Returns true on success or false on error.
  1430.      *
  1431.      * @param string $filename
  1432.      * @param int $gid
  1433.      * @param bool $recursive
  1434.      * @return bool
  1435.      * @access public
  1436.      */
  1437.     public function chgrp($filename, $gid, $recursive = false)
  1438.     {
  1439.         $attr = pack('N3', NET_SFTP_ATTR_UIDGID, -1, $gid);
  1441.         return $this->setstat($filename, $attr, $recursive);
  1442.     }
  1444.     /**
  1445.      * Set permissions on a file.
  1446.      *
  1447.      * Returns the new file permissions on success or false on error.
  1448.      * If $recursive is true than this just returns true or false.
  1449.      *
  1450.      * @param int $mode
  1451.      * @param string $filename
  1452.      * @param bool $recursive
  1453.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1454.      * @return mixed
  1455.      * @access public
  1456.      */
  1457.     public function chmod($mode, $filename, $recursive = false)
  1458.     {
  1459.         if (is_string($mode) && is_int($filename)) {
  1460.             $temp = $mode;
  1461.             $mode = $filename;
  1462.             $filename = $temp;
  1463.         }
  1465.         $attr = pack('N2', NET_SFTP_ATTR_PERMISSIONS, $mode & 07777);
  1466.         if (!$this->setstat($filename, $attr, $recursive)) {
  1467.             return false;
  1468.         }
  1469.         if ($recursive) {
  1470.             return true;
  1471.         }
  1473.         $filename = $this->realpath($filename);
  1474.         // rather than return what the permissions *should* be, we'll return what they actually are.  this will also
  1475.         // tell us if the file actually exists.
  1476.         // incidentally, SFTPv4+ adds an additional 32-bit integer field - flags - to the following:
  1477.         $packet = pack('Na*', strlen($filename), $filename);
  1478.         if (!$this->send_sftp_packet(NET_SFTP_STAT, $packet)) {
  1479.             return false;
  1480.         }
  1482.         $response = $this->get_sftp_packet();
  1483.         switch ($this->packet_type) {
  1484.             case NET_SFTP_ATTRS:
  1485.                 $attrs = $this->parseAttributes($response);
  1486.                 return $attrs['mode'];
  1487.             case NET_SFTP_STATUS:
  1488.                 $this->logError($response);
  1489.                 return false;
  1490.         }
  1492.         throw new \UnexpectedValueException('Expected NET_SFTP_ATTRS or NET_SFTP_STATUS. '
  1493.                                           . 'Got packet type: ' . $this->packet_type);
  1494.     }
  1496.     /**
  1497.      * Sets information about a file
  1498.      *
  1499.      * @param string $filename
  1500.      * @param string $attr
  1501.      * @param bool $recursive
  1502.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1503.      * @return bool
  1504.      * @access private
  1505.      */
  1506.     private function setstat($filename, $attr, $recursive)
  1507.     {
  1508.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1509.             return false;
  1510.         }
  1512.         $filename = $this->realpath($filename);
  1513.         if ($filename === false) {
  1514.             return false;
  1515.         }
  1517.         $this->remove_from_stat_cache($filename);
  1519.         if ($recursive) {
  1520.             $i = 0;
  1521.             $result = $this->setstat_recursive($filename, $attr, $i);
  1522.             $this->read_put_responses($i);
  1523.             return $result;
  1524.         }
  1526.         // SFTPv4+ has an additional byte field - type - that would need to be sent, as well. setting it to
  1527.         // SSH_FILEXFER_TYPE_UNKNOWN might work. if not, we'd have to do an SSH_FXP_STAT before doing an SSH_FXP_SETSTAT.
  1528.         if (!$this->send_sftp_packet(NET_SFTP_SETSTAT, Strings::packSSH2('s', $filename) . $attr)) {
  1529.             return false;
  1530.         }
  1532.         /*
  1533.          "Because some systems must use separate system calls to set various attributes, it is possible that a failure
  1534.           response will be returned, but yet some of the attributes may be have been successfully modified.  If possible,
  1535.           servers SHOULD avoid this situation; however, clients MUST be aware that this is possible."
  1537.           -- http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.6
  1538.         */
  1539.         $response = $this->get_sftp_packet();
  1540.         if ($this->packet_type != NET_SFTP_STATUS) {
  1541.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  1542.                                               . 'Got packet type: ' . $this->packet_type);
  1543.         }
  1545.         list($status) = Strings::unpackSSH2('N', $response);
  1546.         if ($status != NET_SFTP_STATUS_OK) {
  1547.             $this->logError($response, $status);
  1548.             return false;
  1549.         }
  1551.         return true;
  1552.     }
  1554.     /**
  1555.      * Recursively sets information on directories on the SFTP server
  1556.      *
  1557.      * Minimizes directory lookups and SSH_FXP_STATUS requests for speed.
  1558.      *
  1559.      * @param string $path
  1560.      * @param string $attr
  1561.      * @param int $i
  1562.      * @return bool
  1563.      * @access private
  1564.      */
  1565.     private function setstat_recursive($path, $attr, &$i)
  1566.     {
  1567.         if (!$this->read_put_responses($i)) {
  1568.             return false;
  1569.         }
  1570.         $i = 0;
  1571.         $entries = $this->readlist($path, true);
  1573.         if ($entries === false) {
  1574.             return $this->setstat($path, $attr, false);
  1575.         }
  1577.         // normally $entries would have at least . and .. but it might not if the directories
  1578.         // permissions didn't allow reading
  1579.         if (empty($entries)) {
  1580.             return false;
  1581.         }
  1583.         unset($entries['.'], $entries['..']);
  1584.         foreach ($entries as $filename => $props) {
  1585.             if (!isset($props['type'])) {
  1586.                 return false;
  1587.             }
  1589.             $temp = $path . '/' . $filename;
  1590.             if ($props['type'] == NET_SFTP_TYPE_DIRECTORY) {
  1591.                 if (!$this->setstat_recursive($temp, $attr, $i)) {
  1592.                     return false;
  1593.                 }
  1594.             } else {
  1595.                 if (!$this->send_sftp_packet(NET_SFTP_SETSTAT, Strings::packSSH2('s', $temp) . $attr)) {
  1596.                     return false;
  1597.                 }
  1599.                 $i++;
  1601.                 if ($i >= NET_SFTP_QUEUE_SIZE) {
  1602.                     if (!$this->read_put_responses($i)) {
  1603.                         return false;
  1604.                     }
  1605.                     $i = 0;
  1606.                 }
  1607.             }
  1608.         }
  1610.         if (!$this->send_sftp_packet(NET_SFTP_SETSTAT, Strings::packSSH2('s', $path) . $attr)) {
  1611.             return false;
  1612.         }
  1614.         $i++;
  1616.         if ($i >= NET_SFTP_QUEUE_SIZE) {
  1617.             if (!$this->read_put_responses($i)) {
  1618.                 return false;
  1619.             }
  1620.             $i = 0;
  1621.         }
  1623.         return true;
  1624.     }
  1626.     /**
  1627.      * Return the target of a symbolic link
  1628.      *
  1629.      * @param string $link
  1630.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1631.      * @return mixed
  1632.      * @access public
  1633.      */
  1634.     public function readlink($link)
  1635.     {
  1636.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1637.             return false;
  1638.         }
  1640.         $link = $this->realpath($link);
  1642.         if (!$this->send_sftp_packet(NET_SFTP_READLINK, Strings::packSSH2('s', $link))) {
  1643.             return false;
  1644.         }
  1646.         $response = $this->get_sftp_packet();
  1647.         switch ($this->packet_type) {
  1648.             case NET_SFTP_NAME:
  1649.                 break;
  1650.             case NET_SFTP_STATUS:
  1651.                 $this->logError($response);
  1652.                 return false;
  1653.             default:
  1654.                 throw new \UnexpectedValueException('Expected NET_SFTP_NAME or NET_SFTP_STATUS. '
  1655.                                                   . 'Got packet type: ' . $this->packet_type);
  1656.         }
  1658.         list($count) = Strings::unpackSSH2('N', $response);
  1659.         // the file isn't a symlink
  1660.         if (!$count) {
  1661.             return false;
  1662.         }
  1664.         list($filename) = Strings::unpackSSH2('s', $response);
  1666.         return $filename;
  1667.     }
  1669.     /**
  1670.      * Create a symlink
  1671.      *
  1672.      * symlink() creates a symbolic link to the existing target with the specified name link.
  1673.      *
  1674.      * @param string $target
  1675.      * @param string $link
  1676.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1677.      * @return bool
  1678.      * @access public
  1679.      */
  1680.     public function symlink($target, $link)
  1681.     {
  1682.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1683.             return false;
  1684.         }
  1686.         //$target = $this->realpath($target);
  1687.         $link = $this->realpath($link);
  1689.         $packet = Strings::packSSH2('ss', $target, $link);
  1690.         if (!$this->send_sftp_packet(NET_SFTP_SYMLINK, $packet)) {
  1691.             return false;
  1692.         }
  1694.         $response = $this->get_sftp_packet();
  1695.         if ($this->packet_type != NET_SFTP_STATUS) {
  1696.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  1697.                                               . 'Got packet type: ' . $this->packet_type);
  1698.         }
  1700.         list($status) = Strings::unpackSSH2('N', $response);
  1701.         if ($status != NET_SFTP_STATUS_OK) {
  1702.             $this->logError($response, $status);
  1703.             return false;
  1704.         }
  1706.         return true;
  1707.     }
  1709.     /**
  1710.      * Creates a directory.
  1711.      *
  1712.      * @param string $dir
  1713.      * @param int $mode
  1714.      * @param bool $recursive
  1715.      * @return bool
  1716.      * @access public
  1717.      */
  1718.     public function mkdir($dir, $mode = -1, $recursive = false)
  1719.     {
  1720.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1721.             return false;
  1722.         }
  1724.         $dir = $this->realpath($dir);
  1726.         if ($recursive) {
  1727.             $dirs = explode('/', preg_replace('#/(?=/)|/$#', '', $dir));
  1728.             if (empty($dirs[0])) {
  1729.                 array_shift($dirs);
  1730.                 $dirs[0] = '/' . $dirs[0];
  1731.             }
  1732.             for ($i = 0; $i < count($dirs); $i++) {
  1733.                 $temp = array_slice($dirs, 0, $i + 1);
  1734.                 $temp = implode('/', $temp);
  1735.                 $result = $this->mkdir_helper($temp, $mode);
  1736.             }
  1737.             return $result;
  1738.         }
  1740.         return $this->mkdir_helper($dir, $mode);
  1741.     }
  1743.     /**
  1744.      * Helper function for directory creation
  1745.      *
  1746.      * @param string $dir
  1747.      * @param int $mode
  1748.      * @return bool
  1749.      * @access private
  1750.      */
  1751.     private function mkdir_helper($dir, $mode)
  1752.     {
  1753.         // send SSH_FXP_MKDIR without any attributes (that's what the \0\0\0\0 is doing)
  1754.         if (!$this->send_sftp_packet(NET_SFTP_MKDIR, Strings::packSSH2('s', $dir) . "\0\0\0\0")) {
  1755.             return false;
  1756.         }
  1758.         $response = $this->get_sftp_packet();
  1759.         if ($this->packet_type != NET_SFTP_STATUS) {
  1760.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  1761.                                               . 'Got packet type: ' . $this->packet_type);
  1762.         }
  1764.         list($status) = Strings::unpackSSH2('N', $response);
  1765.         if ($status != NET_SFTP_STATUS_OK) {
  1766.             $this->logError($response, $status);
  1767.             return false;
  1768.         }
  1770.         if ($mode !== -1) {
  1771.             $this->chmod($mode, $dir);
  1772.         }
  1774.         return true;
  1775.     }
  1777.     /**
  1778.      * Removes a directory.
  1779.      *
  1780.      * @param string $dir
  1781.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1782.      * @return bool
  1783.      * @access public
  1784.      */
  1785.     public function rmdir($dir)
  1786.     {
  1787.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1788.             return false;
  1789.         }
  1791.         $dir = $this->realpath($dir);
  1792.         if ($dir === false) {
  1793.             return false;
  1794.         }
  1796.         if (!$this->send_sftp_packet(NET_SFTP_RMDIR, Strings::packSSH2('s', $dir))) {
  1797.             return false;
  1798.         }
  1800.         $response = $this->get_sftp_packet();
  1801.         if ($this->packet_type != NET_SFTP_STATUS) {
  1802.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  1803.                                               . 'Got packet type: ' . $this->packet_type);
  1804.         }
  1806.         list($status) = Strings::unpackSSH2('N', $response);
  1807.         if ($status != NET_SFTP_STATUS_OK) {
  1808.             // presumably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED?
  1809.             $this->logError($response, $status);
  1810.             return false;
  1811.         }
  1813.         $this->remove_from_stat_cache($dir);
  1814.         // the following will do a soft delete, which would be useful if you deleted a file
  1815.         // and then tried to do a stat on the deleted file. the above, in contrast, does
  1816.         // a hard delete
  1817.         //$this->update_stat_cache($dir, false);
  1819.         return true;
  1820.     }
  1822.     /**
  1823.      * Uploads a file to the SFTP server.
  1824.      *
  1825.      * By default, \phpseclib3\Net\SFTP::put() does not read from the local filesystem.  $data is dumped directly into $remote_file.
  1826.      * So, for example, if you set $data to 'filename.ext' and then do \phpseclib3\Net\SFTP::get(), you will get a file, twelve bytes
  1827.      * long, containing 'filename.ext' as its contents.
  1828.      *
  1829.      * Setting $mode to self::SOURCE_LOCAL_FILE will change the above behavior.  With self::SOURCE_LOCAL_FILE, $remote_file will
  1830.      * contain as many bytes as filename.ext does on your local filesystem.  If your filename.ext is 1MB then that is how
  1831.      * large $remote_file will be, as well.
  1832.      *
  1833.      * Setting $mode to self::SOURCE_CALLBACK will use $data as callback function, which gets only one parameter -- number of bytes to return, and returns a string if there is some data or null if there is no more data
  1834.      *
  1835.      * If $data is a resource then it'll be used as a resource instead.
  1836.      *
  1837.      * Currently, only binary mode is supported.  As such, if the line endings need to be adjusted, you will need to take
  1838.      * care of that, yourself.
  1839.      *
  1840.      * $mode can take an additional two parameters - self::RESUME and self::RESUME_START. These are bitwise AND'd with
  1841.      * $mode. So if you want to resume upload of a 300mb file on the local file system you'd set $mode to the following:
  1842.      *
  1843.      * self::SOURCE_LOCAL_FILE | self::RESUME
  1844.      *
  1845.      * If you wanted to simply append the full contents of a local file to the full contents of a remote file you'd replace
  1846.      * self::RESUME with self::RESUME_START.
  1847.      *
  1848.      * If $mode & (self::RESUME | self::RESUME_START) then self::RESUME_START will be assumed.
  1849.      *
  1850.      * $start and $local_start give you more fine grained control over this process and take precident over self::RESUME
  1851.      * when they're non-negative. ie. $start could let you write at the end of a file (like self::RESUME) or in the middle
  1852.      * of one. $local_start could let you start your reading from the end of a file (like self::RESUME_START) or in the
  1853.      * middle of one.
  1854.      *
  1855.      * Setting $local_start to > 0 or $mode | self::RESUME_START doesn't do anything unless $mode | self::SOURCE_LOCAL_FILE.
  1856.      *
  1857.      * {@internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().}
  1858.      *
  1859.      * @param string $remote_file
  1860.      * @param string|resource $data
  1861.      * @param int $mode
  1862.      * @param int $start
  1863.      * @param int $local_start
  1864.      * @param callable|null $progressCallback
  1865.      * @throws \UnexpectedValueException on receipt of unexpected packets
  1866.      * @throws \BadFunctionCallException if you're uploading via a callback and the callback function is invalid
  1867.      * @throws \phpseclib3\Exception\FileNotFoundException if you're uploading via a file and the file doesn't exist
  1868.      * @return bool
  1869.      * @access public
  1870.      */
  1871.     public function put($remote_file, $data, $mode = self::SOURCE_STRING, $start = -1, $local_start = -1, $progressCallback = null)
  1872.     {
  1873.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  1874.             return false;
  1875.         }
  1877.         $remote_file = $this->realpath($remote_file);
  1878.         if ($remote_file === false) {
  1879.             return false;
  1880.         }
  1882.         $flags = NET_SFTP_OPEN_WRITE | NET_SFTP_OPEN_CREATE;
  1883.         // according to the SFTP specs, NET_SFTP_OPEN_APPEND should "force all writes to append data at the end of the file."
  1884.         // in practice, it doesn't seem to do that.
  1885.         //$flags|= ($mode & self::RESUME) ? NET_SFTP_OPEN_APPEND : NET_SFTP_OPEN_TRUNCATE;
  1887.         if ($start >= 0) {
  1888.             $offset = $start;
  1889.         } elseif ($mode & self::RESUME) {
  1890.             // if NET_SFTP_OPEN_APPEND worked as it should _size() wouldn't need to be called
  1891.             $size = $this->stat($remote_file)['size'];
  1892.             $offset = $size !== false ? $size : 0;
  1893.         } else {
  1894.             $offset = 0;
  1895.             $flags|= NET_SFTP_OPEN_TRUNCATE;
  1896.         }
  1898.         $this->remove_from_stat_cache($remote_file);
  1900.         $packet = Strings::packSSH2('sNN', $remote_file, $flags, 0);
  1901.         if (!$this->send_sftp_packet(NET_SFTP_OPEN, $packet)) {
  1902.             return false;
  1903.         }
  1905.         $response = $this->get_sftp_packet();
  1906.         switch ($this->packet_type) {
  1907.             case NET_SFTP_HANDLE:
  1908.                 $handle = substr($response, 4);
  1909.                 break;
  1910.             case NET_SFTP_STATUS:
  1911.                 $this->logError($response);
  1912.                 return false;
  1913.             default:
  1914.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS. '
  1915.                                                   . 'Got packet type: ' . $this->packet_type);
  1916.         }
  1918.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.2.3
  1919.         $dataCallback = false;
  1920.         switch (true) {
  1921.             case $mode & self::SOURCE_CALLBACK:
  1922.                 if (!is_callable($data)) {
  1923.                     throw new \BadFunctionCallException("\$data should be is_callable() if you specify SOURCE_CALLBACK flag");
  1924.                 }
  1925.                 $dataCallback = $data;
  1926.                 // do nothing
  1927.                 break;
  1928.             case is_resource($data):
  1929.                 $mode = $mode & ~self::SOURCE_LOCAL_FILE;
  1930.                 $info = stream_get_meta_data($data);
  1931.                 if ($info['wrapper_type'] == 'PHP' && $info['stream_type'] == 'Input') {
  1932.                     $fp = fopen('php://memory', 'w+');
  1933.                     stream_copy_to_stream($data, $fp);
  1934.                     rewind($fp);
  1935.                 } else {
  1936.                     $fp = $data;
  1937.                 }
  1938.                 break;
  1939.             case $mode & self::SOURCE_LOCAL_FILE:
  1940.                 if (!is_file($data)) {
  1941.                     throw new FileNotFoundException("$data is not a valid file");
  1942.                 }
  1943.                 $fp = @fopen($data, 'rb');
  1944.                 if (!$fp) {
  1945.                     return false;
  1946.                 }
  1947.         }
  1949.         if (isset($fp)) {
  1950.             $stat = fstat($fp);
  1951.             $size = !empty($stat) ? $stat['size'] : 0;
  1953.             if ($local_start >= 0) {
  1954.                 fseek($fp, $local_start);
  1955.                 $size-= $local_start;
  1956.             }
  1957.         } elseif ($dataCallback) {
  1958.             $size = 0;
  1959.         } else {
  1960.             $size = strlen($data);
  1961.         }
  1963.         $sent = 0;
  1964.         $size = $size < 0 ? ($size & 0x7FFFFFFF) + 0x80000000 : $size;
  1966.         $sftp_packet_size = $this->max_sftp_packet;
  1967.         // make the SFTP packet be exactly the SFTP packet size by including the bytes in the NET_SFTP_WRITE packets "header"
  1968.         $sftp_packet_size-= strlen($handle) + 25;
  1969.         $i = $j = 0;
  1970.         while ($dataCallback || ($size === 0 || $sent < $size)) {
  1971.             if ($dataCallback) {
  1972.                 $temp = $dataCallback($sftp_packet_size);
  1973.                 if (is_null($temp)) {
  1974.                     break;
  1975.                 }
  1976.             } else {
  1977.                 $temp = isset($fp) ? fread($fp, $sftp_packet_size) : substr($data, $sent, $sftp_packet_size);
  1978.                 if ($temp === false || $temp === '') {
  1979.                     break;
  1980.                 }
  1981.             }
  1983.             $subtemp = $offset + $sent;
  1984.             $packet = pack('Na*N3a*', strlen($handle), $handle, $subtemp / 4294967296, $subtemp, strlen($temp), $temp);
  1985.             if (!$this->send_sftp_packet(NET_SFTP_WRITE, $packet, $j)) {
  1986.                 if ($mode & self::SOURCE_LOCAL_FILE) {
  1987.                     fclose($fp);
  1988.                 }
  1989.                 return false;
  1990.             }
  1991.             $sent+= strlen($temp);
  1992.             if (is_callable($progressCallback)) {
  1993.                 $progressCallback($sent);
  1994.             }
  1996.             $i++;
  1997.             $j++;
  1998.             if ($i == NET_SFTP_UPLOAD_QUEUE_SIZE) {
  1999.                 if (!$this->read_put_responses($i)) {
  2000.                     $i = 0;
  2001.                     break;
  2002.                 }
  2003.                 $i = 0;
  2004.             }
  2005.         }
  2007.         if (!$this->read_put_responses($i)) {
  2008.             if ($mode & self::SOURCE_LOCAL_FILE) {
  2009.                 fclose($fp);
  2010.             }
  2011.             $this->close_handle($handle);
  2012.             return false;
  2013.         }
  2015.         if ($mode & self::SOURCE_LOCAL_FILE) {
  2016.             if ($this->preserveTime) {
  2017.                 $stat = fstat($fp);
  2018.                 $this->touch($remote_file, $stat['mtime'], $stat['atime']);
  2019.             }
  2021.             if (isset($fp) && is_resource($fp)) {
  2022.                 fclose($fp);
  2023.             }
  2024.         }
  2026.         return $this->close_handle($handle);
  2027.     }
  2029.     /**
  2030.      * Reads multiple successive SSH_FXP_WRITE responses
  2031.      *
  2032.      * Sending an SSH_FXP_WRITE packet and immediately reading its response isn't as efficient as blindly sending out $i
  2033.      * SSH_FXP_WRITEs, in succession, and then reading $i responses.
  2034.      *
  2035.      * @param int $i
  2036.      * @return bool
  2037.      * @throws \UnexpectedValueException on receipt of unexpected packets
  2038.      * @access private
  2039.      */
  2040.     private function read_put_responses($i)
  2041.     {
  2042.         while ($i--) {
  2043.             $response = $this->get_sftp_packet();
  2044.             if ($this->packet_type != NET_SFTP_STATUS) {
  2045.                 throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  2046.                                                   . 'Got packet type: ' . $this->packet_type);
  2047.             }
  2049.             list($status) = Strings::unpackSSH2('N', $response);
  2050.             if ($status != NET_SFTP_STATUS_OK) {
  2051.                 $this->logError($response, $status);
  2052.                 break;
  2053.             }
  2054.         }
  2056.         return $i < 0;
  2057.     }
  2059.     /**
  2060.      * Close handle
  2061.      *
  2062.      * @param string $handle
  2063.      * @return bool
  2064.      * @throws \UnexpectedValueException on receipt of unexpected packets
  2065.      * @access private
  2066.      */
  2067.     private function close_handle($handle)
  2068.     {
  2069.         if (!$this->send_sftp_packet(NET_SFTP_CLOSE, pack('Na*', strlen($handle), $handle))) {
  2070.             return false;
  2071.         }
  2073.         // "The client MUST release all resources associated with the handle regardless of the status."
  2074.         //  -- http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.1.3
  2075.         $response = $this->get_sftp_packet();
  2076.         if ($this->packet_type != NET_SFTP_STATUS) {
  2077.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  2078.                                               . 'Got packet type: ' . $this->packet_type);
  2079.         }
  2081.         list($status) = Strings::unpackSSH2('N', $response);
  2082.         if ($status != NET_SFTP_STATUS_OK) {
  2083.             $this->logError($response, $status);
  2084.             return false;
  2085.         }
  2087.         return true;
  2088.     }
  2090.     /**
  2091.      * Downloads a file from the SFTP server.
  2092.      *
  2093.      * Returns a string containing the contents of $remote_file if $local_file is left undefined or a boolean false if
  2094.      * the operation was unsuccessful.  If $local_file is defined, returns true or false depending on the success of the
  2095.      * operation.
  2096.      *
  2097.      * $offset and $length can be used to download files in chunks.
  2098.      *
  2099.      * @param string $remote_file
  2100.      * @param string|bool|resource|callable $local_file
  2101.      * @param int $offset
  2102.      * @param int $length
  2103.      * @param callable|null $progressCallback
  2104.      * @throws \UnexpectedValueException on receipt of unexpected packets
  2105.      * @return mixed
  2106.      * @access public
  2107.      */
  2108.     public function get($remote_file, $local_file = false, $offset = 0, $length = -1, $progressCallback = null)
  2109.     {
  2110.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  2111.             return false;
  2112.         }
  2114.         $remote_file = $this->realpath($remote_file);
  2115.         if ($remote_file === false) {
  2116.             return false;
  2117.         }
  2119.         $packet = pack('Na*N2', strlen($remote_file), $remote_file, NET_SFTP_OPEN_READ, 0);
  2120.         if (!$this->send_sftp_packet(NET_SFTP_OPEN, $packet)) {
  2121.             return false;
  2122.         }
  2124.         $response = $this->get_sftp_packet();
  2125.         switch ($this->packet_type) {
  2126.             case NET_SFTP_HANDLE:
  2127.                 $handle = substr($response, 4);
  2128.                 break;
  2129.             case NET_SFTP_STATUS: // presumably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  2130.                 $this->logError($response);
  2131.                 return false;
  2132.             default:
  2133.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS. '
  2134.                                                   . 'Got packet type: ' . $this->packet_type);
  2135.         }
  2137.         if (is_resource($local_file)) {
  2138.             $fp = $local_file;
  2139.             $stat = fstat($fp);
  2140.             $res_offset = $stat['size'];
  2141.         } else {
  2142.             $res_offset = 0;
  2143.             if ($local_file !== false && !is_callable($local_file)) {
  2144.                 $fp = fopen($local_file, 'wb');
  2145.                 if (!$fp) {
  2146.                     return false;
  2147.                 }
  2148.             } else {
  2149.                 $content = '';
  2150.             }
  2151.         }
  2153.         $fclose_check = $local_file !== false && !is_callable($local_file) && !is_resource($local_file);
  2155.         $start = $offset;
  2156.         $read = 0;
  2157.         while (true) {
  2158.             $i = 0;
  2160.             while ($i < NET_SFTP_QUEUE_SIZE && ($length < 0 || $read < $length)) {
  2161.                 $tempoffset = $start + $read;
  2163.                 $packet_size = $length > 0 ? min($this->max_sftp_packet, $length - $read) : $this->max_sftp_packet;
  2165.                 $packet = Strings::packSSH2('sN3', $handle, $tempoffset / 4294967296, $tempoffset, $packet_size);
  2166.                 if (!$this->send_sftp_packet(NET_SFTP_READ, $packet, $i)) {
  2167.                     if ($fclose_check) {
  2168.                         fclose($fp);
  2169.                     }
  2170.                     return false;
  2171.                 }
  2172.                 $packet = null;
  2173.                 $read+= $packet_size;
  2174.                 $i++;
  2175.             }
  2177.             if (!$i) {
  2178.                 break;
  2179.             }
  2181.             $packets_sent = $i - 1;
  2183.             $clear_responses = false;
  2184.             while ($i > 0) {
  2185.                 $i--;
  2187.                 if ($clear_responses) {
  2188.                     $this->get_sftp_packet($packets_sent - $i);
  2189.                     continue;
  2190.                 } else {
  2191.                     $response = $this->get_sftp_packet($packets_sent - $i);
  2192.                 }
  2194.                 switch ($this->packet_type) {
  2195.                     case NET_SFTP_DATA:
  2196.                         $temp = substr($response, 4);
  2197.                         $offset+= strlen($temp);
  2198.                         if ($local_file === false) {
  2199.                             $content.= $temp;
  2200.                         } elseif (is_callable($local_file)) {
  2201.                             $local_file($temp);
  2202.                         } else {
  2203.                             fputs($fp, $temp);
  2204.                         }
  2205.                         if (is_callable($progressCallback)) {
  2206.                             call_user_func($progressCallback, $offset);
  2207.                         }
  2208.                         $temp = null;
  2209.                         break;
  2210.                     case NET_SFTP_STATUS:
  2211.                         // could, in theory, return false if !strlen($content) but we'll hold off for the time being
  2212.                         $this->logError($response);
  2213.                         $clear_responses = true; // don't break out of the loop yet, so we can read the remaining responses
  2214.                         break;
  2215.                     default:
  2216.                         if ($fclose_check) {
  2217.                             fclose($fp);
  2218.                         }
  2219.                         throw new \UnexpectedValueException('Expected NET_SFTP_DATA or NET_SFTP_STATUS. '
  2220.                                                           . 'Got packet type: ' . $this->packet_type);
  2221.                 }
  2222.                 $response = null;
  2223.             }
  2225.             if ($clear_responses) {
  2226.                 break;
  2227.             }
  2228.         }
  2230.         if ($length > 0 && $length <= $offset - $start) {
  2231.             if ($local_file === false) {
  2232.                 $content = substr($content, 0, $length);
  2233.             } else {
  2234.                 ftruncate($fp, $length + $res_offset);
  2235.             }
  2236.         }
  2238.         if ($fclose_check) {
  2239.             fclose($fp);
  2241.             if ($this->preserveTime) {
  2242.                 $stat = $this->stat($remote_file);
  2243.                 touch($local_file, $stat['mtime'], $stat['atime']);
  2244.             }
  2245.         }
  2247.         if (!$this->close_handle($handle)) {
  2248.             return false;
  2249.         }
  2251.         // if $content isn't set that means a file was written to
  2252.         return isset($content) ? $content : true;
  2253.     }
  2255.     /**
  2256.      * Deletes a file on the SFTP server.
  2257.      *
  2258.      * @param string $path
  2259.      * @param bool $recursive
  2260.      * @return bool
  2261.      * @throws \UnexpectedValueException on receipt of unexpected packets
  2262.      * @access public
  2263.      */
  2264.     public function delete($path, $recursive = true)
  2265.     {
  2266.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  2267.             return false;
  2268.         }
  2270.         if (is_object($path)) {
  2271.             // It's an object. Cast it as string before we check anything else.
  2272.             $path = (string) $path;
  2273.         }
  2275.         if (!is_string($path) || $path == '') {
  2276.             return false;
  2277.         }
  2279.         $path = $this->realpath($path);
  2280.         if ($path === false) {
  2281.             return false;
  2282.         }
  2284.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.3
  2285.         if (!$this->send_sftp_packet(NET_SFTP_REMOVE, pack('Na*', strlen($path), $path))) {
  2286.             return false;
  2287.         }
  2289.         $response = $this->get_sftp_packet();
  2290.         if ($this->packet_type != NET_SFTP_STATUS) {
  2291.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  2292.                                               . 'Got packet type: ' . $this->packet_type);
  2293.         }
  2295.         // if $status isn't SSH_FX_OK it's probably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  2296.         list($status) = Strings::unpackSSH2('N', $response);
  2297.         if ($status != NET_SFTP_STATUS_OK) {
  2298.             $this->logError($response, $status);
  2299.             if (!$recursive) {
  2300.                 return false;
  2301.             }
  2303.             $i = 0;
  2304.             $result = $this->delete_recursive($path, $i);
  2305.             $this->read_put_responses($i);
  2306.             return $result;
  2307.         }
  2309.         $this->remove_from_stat_cache($path);
  2311.         return true;
  2312.     }
  2314.     /**
  2315.      * Recursively deletes directories on the SFTP server
  2316.      *
  2317.      * Minimizes directory lookups and SSH_FXP_STATUS requests for speed.
  2318.      *
  2319.      * @param string $path
  2320.      * @param int $i
  2321.      * @return bool
  2322.      * @access private
  2323.      */
  2324.     private function delete_recursive($path, &$i)
  2325.     {
  2326.         if (!$this->read_put_responses($i)) {
  2327.             return false;
  2328.         }
  2329.         $i = 0;
  2330.         $entries = $this->readlist($path, true);
  2332.         // normally $entries would have at least . and .. but it might not if the directories
  2333.         // permissions didn't allow reading
  2334.         if (empty($entries)) {
  2335.             return false;
  2336.         }
  2338.         unset($entries['.'], $entries['..']);
  2339.         foreach ($entries as $filename => $props) {
  2340.             if (!isset($props['type'])) {
  2341.                 return false;
  2342.             }
  2344.             $temp = $path . '/' . $filename;
  2345.             if ($props['type'] == NET_SFTP_TYPE_DIRECTORY) {
  2346.                 if (!$this->delete_recursive($temp, $i)) {
  2347.                     return false;
  2348.                 }
  2349.             } else {
  2350.                 if (!$this->send_sftp_packet(NET_SFTP_REMOVE, Strings::packSSH2('s', $temp))) {
  2351.                     return false;
  2352.                 }
  2353.                 $this->remove_from_stat_cache($temp);
  2355.                 $i++;
  2357.                 if ($i >= NET_SFTP_QUEUE_SIZE) {
  2358.                     if (!$this->read_put_responses($i)) {
  2359.                         return false;
  2360.                     }
  2361.                     $i = 0;
  2362.                 }
  2363.             }
  2364.         }
  2366.         if (!$this->send_sftp_packet(NET_SFTP_RMDIR, Strings::packSSH2('s', $path))) {
  2367.             return false;
  2368.         }
  2369.         $this->remove_from_stat_cache($path);
  2371.         $i++;
  2373.         if ($i >= NET_SFTP_QUEUE_SIZE) {
  2374.             if (!$this->read_put_responses($i)) {
  2375.                 return false;
  2376.             }
  2377.             $i = 0;
  2378.         }
  2380.         return true;
  2381.     }
  2383.     /**
  2384.      * Checks whether a file or directory exists
  2385.      *
  2386.      * @param string $path
  2387.      * @return bool
  2388.      * @access public
  2389.      */
  2390.     public function file_exists($path)
  2391.     {
  2392.         if ($this->use_stat_cache) {
  2393.             $path = $this->realpath($path);
  2395.             $result = $this->query_stat_cache($path);
  2397.             if (isset($result)) {
  2398.                 // return true if $result is an array or if it's an stdClass object
  2399.                 return $result !== false;
  2400.             }
  2401.         }
  2403.         return $this->stat($path) !== false;
  2404.     }
  2406.     /**
  2407.      * Tells whether the filename is a directory
  2408.      *
  2409.      * @param string $path
  2410.      * @return bool
  2411.      * @access public
  2412.      */
  2413.     public function is_dir($path)
  2414.     {
  2415.         $result = $this->get_stat_cache_prop($path, 'type');
  2416.         if ($result === false) {
  2417.             return false;
  2418.         }
  2419.         return $result === NET_SFTP_TYPE_DIRECTORY;
  2420.     }
  2422.     /**
  2423.      * Tells whether the filename is a regular file
  2424.      *
  2425.      * @param string $path
  2426.      * @return bool
  2427.      * @access public
  2428.      */
  2429.     public function is_file($path)
  2430.     {
  2431.         $result = $this->get_stat_cache_prop($path, 'type');
  2432.         if ($result === false) {
  2433.             return false;
  2434.         }
  2435.         return $result === NET_SFTP_TYPE_REGULAR;
  2436.     }
  2438.     /**
  2439.      * Tells whether the filename is a symbolic link
  2440.      *
  2441.      * @param string $path
  2442.      * @return bool
  2443.      * @access public
  2444.      */
  2445.     public function is_link($path)
  2446.     {
  2447.         $result = $this->get_lstat_cache_prop($path, 'type');
  2448.         if ($result === false) {
  2449.             return false;
  2450.         }
  2451.         return $result === NET_SFTP_TYPE_SYMLINK;
  2452.     }
  2454.     /**
  2455.      * Tells whether a file exists and is readable
  2456.      *
  2457.      * @param string $path
  2458.      * @return bool
  2459.      * @access public
  2460.      */
  2461.     public function is_readable($path)
  2462.     {
  2463.         $packet = Strings::packSSH2('sNN', $this->realpath($path), NET_SFTP_OPEN_READ, 0);
  2464.         if (!$this->send_sftp_packet(NET_SFTP_OPEN, $packet)) {
  2465.             return false;
  2466.         }
  2468.         $response = $this->get_sftp_packet();
  2469.         switch ($this->packet_type) {
  2470.             case NET_SFTP_HANDLE:
  2471.                 return true;
  2472.             case NET_SFTP_STATUS: // presumably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  2473.                 return false;
  2474.             default:
  2475.                 throw new \UnexpectedValueException('Expected NET_SFTP_HANDLE or NET_SFTP_STATUS. '
  2476.                                                   . 'Got packet type: ' . $this->packet_type);
  2477.         }
  2478.     }
  2480.     /**
  2481.      * Tells whether the filename is writable
  2482.      *
  2483.      * @param string $path
  2484.      * @return bool
  2485.      * @access public
  2486.      */
  2487.     public function is_writable($path)
  2488.     {
  2489.         $packet = Strings::packSSH2('sNN', $this->realpath($path), NET_SFTP_OPEN_WRITE, 0);
  2490.         if (!$this->send_sftp_packet(NET_SFTP_OPEN, $packet)) {
  2491.             return false;
  2492.         }
  2494.         $response = $this->get_sftp_packet();
  2495.         switch ($this->packet_type) {
  2496.             case NET_SFTP_HANDLE:
  2497.                 return true;
  2498.             case NET_SFTP_STATUS: // presumably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  2499.                 return false;
  2500.             default:
  2501.                 throw new \UnexpectedValueException('Expected SSH_FXP_HANDLE or SSH_FXP_STATUS. '
  2502.                                                   . 'Got packet type: ' . $this->packet_type);
  2503.         }
  2504.     }
  2506.     /**
  2507.      * Tells whether the filename is writeable
  2508.      *
  2509.      * Alias of is_writable
  2510.      *
  2511.      * @param string $path
  2512.      * @return bool
  2513.      * @access public
  2514.      */
  2515.     public function is_writeable($path)
  2516.     {
  2517.         return $this->is_writable($path);
  2518.     }
  2520.     /**
  2521.      * Gets last access time of file
  2522.      *
  2523.      * @param string $path
  2524.      * @return mixed
  2525.      * @access public
  2526.      */
  2527.     public function fileatime($path)
  2528.     {
  2529.         return $this->get_stat_cache_prop($path, 'atime');
  2530.     }
  2532.     /**
  2533.      * Gets file modification time
  2534.      *
  2535.      * @param string $path
  2536.      * @return mixed
  2537.      * @access public
  2538.      */
  2539.     public function filemtime($path)
  2540.     {
  2541.         return $this->get_stat_cache_prop($path, 'mtime');
  2542.     }
  2544.     /**
  2545.      * Gets file permissions
  2546.      *
  2547.      * @param string $path
  2548.      * @return mixed
  2549.      * @access public
  2550.      */
  2551.     public function fileperms($path)
  2552.     {
  2553.         return $this->get_stat_cache_prop($path, 'mode');
  2554.     }
  2556.     /**
  2557.      * Gets file owner
  2558.      *
  2559.      * @param string $path
  2560.      * @return mixed
  2561.      * @access public
  2562.      */
  2563.     public function fileowner($path)
  2564.     {
  2565.         return $this->get_stat_cache_prop($path, 'uid');
  2566.     }
  2568.     /**
  2569.      * Gets file group
  2570.      *
  2571.      * @param string $path
  2572.      * @return mixed
  2573.      * @access public
  2574.      */
  2575.     public function filegroup($path)
  2576.     {
  2577.         return $this->get_stat_cache_prop($path, 'gid');
  2578.     }
  2580.     /**
  2581.      * Gets file size
  2582.      *
  2583.      * @param string $path
  2584.      * @return mixed
  2585.      * @access public
  2586.      */
  2587.     public function filesize($path)
  2588.     {
  2589.         return $this->get_stat_cache_prop($path, 'size');
  2590.     }
  2592.     /**
  2593.      * Gets file type
  2594.      *
  2595.      * @param string $path
  2596.      * @return mixed
  2597.      * @access public
  2598.      */
  2599.     public function filetype($path)
  2600.     {
  2601.         $type = $this->get_stat_cache_prop($path, 'type');
  2602.         if ($type === false) {
  2603.             return false;
  2604.         }
  2606.         switch ($type) {
  2607.             case NET_SFTP_TYPE_BLOCK_DEVICE:
  2608.                 return 'block';
  2609.             case NET_SFTP_TYPE_CHAR_DEVICE:
  2610.                 return 'char';
  2611.             case NET_SFTP_TYPE_DIRECTORY:
  2612.                 return 'dir';
  2613.             case NET_SFTP_TYPE_FIFO:
  2614.                 return 'fifo';
  2615.             case NET_SFTP_TYPE_REGULAR:
  2616.                 return 'file';
  2617.             case NET_SFTP_TYPE_SYMLINK:
  2618.                 return 'link';
  2619.             default:
  2620.                 return false;
  2621.         }
  2622.     }
  2624.     /**
  2625.      * Return a stat properity
  2626.      *
  2627.      * Uses cache if appropriate.
  2628.      *
  2629.      * @param string $path
  2630.      * @param string $prop
  2631.      * @return mixed
  2632.      * @access private
  2633.      */
  2634.     private function get_stat_cache_prop($path, $prop)
  2635.     {
  2636.         return $this->get_xstat_cache_prop($path, $prop, 'stat');
  2637.     }
  2639.     /**
  2640.      * Return an lstat properity
  2641.      *
  2642.      * Uses cache if appropriate.
  2643.      *
  2644.      * @param string $path
  2645.      * @param string $prop
  2646.      * @return mixed
  2647.      * @access private
  2648.      */
  2649.     private function get_lstat_cache_prop($path, $prop)
  2650.     {
  2651.         return $this->get_xstat_cache_prop($path, $prop, 'lstat');
  2652.     }
  2654.     /**
  2655.      * Return a stat or lstat properity
  2656.      *
  2657.      * Uses cache if appropriate.
  2658.      *
  2659.      * @param string $path
  2660.      * @param string $prop
  2661.      * @param string $type
  2662.      * @return mixed
  2663.      * @access private
  2664.      */
  2665.     private function get_xstat_cache_prop($path, $prop, $type)
  2666.     {
  2667.         if ($this->use_stat_cache) {
  2668.             $path = $this->realpath($path);
  2670.             $result = $this->query_stat_cache($path);
  2672.             if (is_object($result) && isset($result->$type)) {
  2673.                 return $result->{$type}[$prop];
  2674.             }
  2675.         }
  2677.         $result = $this->$type($path);
  2679.         if ($result === false || !isset($result[$prop])) {
  2680.             return false;
  2681.         }
  2683.         return $result[$prop];
  2684.     }
  2686.     /**
  2687.      * Renames a file or a directory on the SFTP server
  2688.      *
  2689.      * @param string $oldname
  2690.      * @param string $newname
  2691.      * @return bool
  2692.      * @throws \UnexpectedValueException on receipt of unexpected packets
  2693.      * @access public
  2694.      */
  2695.     public function rename($oldname, $newname)
  2696.     {
  2697.         if (!($this->bitmap & SSH2::MASK_LOGIN)) {
  2698.             return false;
  2699.         }
  2701.         $oldname = $this->realpath($oldname);
  2702.         $newname = $this->realpath($newname);
  2703.         if ($oldname === false || $newname === false) {
  2704.             return false;
  2705.         }
  2707.         // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#section-8.3
  2708.         $packet = Strings::packSSH2('ss', $oldname, $newname);
  2709.         if (!$this->send_sftp_packet(NET_SFTP_RENAME, $packet)) {
  2710.             return false;
  2711.         }
  2713.         $response = $this->get_sftp_packet();
  2714.         if ($this->packet_type != NET_SFTP_STATUS) {
  2715.             throw new \UnexpectedValueException('Expected NET_SFTP_STATUS. '
  2716.                                               . 'Got packet type: ' . $this->packet_type);
  2717.         }
  2719.         // if $status isn't SSH_FX_OK it's probably SSH_FX_NO_SUCH_FILE or SSH_FX_PERMISSION_DENIED
  2720.         list($status) = Strings::unpackSSH2('N', $response);
  2721.         if ($status != NET_SFTP_STATUS_OK) {
  2722.             $this->logError($response, $status);
  2723.             return false;
  2724.         }
  2726.         // don't move the stat cache entry over since this operation could very well change the
  2727.         // atime and mtime attributes
  2728.         //$this->update_stat_cache($newname, $this->query_stat_cache($oldname));
  2729.         $this->remove_from_stat_cache($oldname);
  2730.         $this->remove_from_stat_cache($newname);
  2732.         return true;
  2733.     }
  2735.     /**
  2736.      * Parse Attributes
  2737.      *
  2738.      * See '7.  File Attributes' of draft-ietf-secsh-filexfer-13 for more info.
  2739.      *
  2740.      * @param string $response
  2741.      * @return array
  2742.      * @access private
  2743.      */
  2744.     protected function parseAttributes(&$response)
  2745.     {
  2746.         $attr = [];
  2747.         list($flags) = Strings::unpackSSH2('N', $response);
  2749.         // SFTPv4+ have a type field (a byte) that follows the above flag field
  2750.         foreach ($this->attributes as $key => $value) {
  2751.             switch ($flags & $key) {
  2752.                 case NET_SFTP_ATTR_SIZE: // 0x00000001
  2753.                     // The size attribute is defined as an unsigned 64-bit integer.
  2754.                     // The following will use floats on 32-bit platforms, if necessary.
  2755.                     // As can be seen in the BigInteger class, floats are generally
  2756.                     // IEEE 754 binary64 "double precision" on such platforms and
  2757.                     // as such can represent integers of at least 2^50 without loss
  2758.                     // of precision. Interpreted in filesize, 2^50 bytes = 1024 TiB.
  2759.                     list($upper, $size) = Strings::unpackSSH2('NN', $response);
  2760.                     $attr['size'] = $upper ? 4294967296 * $upper : 0;
  2761.                     $attr['size']+= $size < 0 ? ($size & 0x7FFFFFFF) + 0x80000000 : $size;
  2762.                     break;
  2763.                 case NET_SFTP_ATTR_UIDGID: // 0x00000002 (SFTPv3 only)
  2764.                     list($attr['uid'], $attr['gid']) = Strings::unpackSSH2('NN', $response);
  2765.                     break;
  2766.                 case NET_SFTP_ATTR_PERMISSIONS: // 0x00000004
  2767.                     list($attr['mode']) = Strings::unpackSSH2('N', $response);
  2768.                     $fileType = $this->parseMode($attr['mode']);
  2769.                     if ($fileType !== false) {
  2770.                         $attr+= ['type' => $fileType];
  2771.                     }
  2772.                     break;
  2773.                 case NET_SFTP_ATTR_ACCESSTIME: // 0x00000008
  2774.                     list($attr['atime'], $attr['mtime']) = Strings::unpackSSH2('NN', $response);
  2775.                     break;
  2776.                 case NET_SFTP_ATTR_EXTENDED: // 0x80000000
  2777.                     list($count) = Strings::unpackSSH2('N', $response);
  2778.                     for ($i = 0; $i < $count; $i++) {
  2779.                         list($key, $value) = Strings::unpackSSH2('ss', $response);
  2780.                         $attr[$key] = $value;
  2781.                     }
  2782.             }
  2783.         }
  2784.         return $attr;
  2785.     }
  2787.     /**
  2788.      * Attempt to identify the file type
  2789.      *
  2790.      * Quoting the SFTP RFC, "Implementations MUST NOT send bits that are not defined" but they seem to anyway
  2791.      *
  2792.      * @param int $mode
  2793.      * @return int
  2794.      * @access private
  2795.      */
  2796.     private function parseMode($mode)
  2797.     {
  2798.         // values come from http://lxr.free-electrons.com/source/include/uapi/linux/stat.h#L12
  2799.         // see, also, http://linux.die.net/man/2/stat
  2800.         switch ($mode & 0170000) {// ie. 1111 0000 0000 0000
  2801.             case 0000000: // no file type specified - figure out the file type using alternative means
  2802.                 return false;
  2803.             case 0040000:
  2804.                 return NET_SFTP_TYPE_DIRECTORY;
  2805.             case 0100000:
  2806.                 return NET_SFTP_TYPE_REGULAR;
  2807.             case 0120000:
  2808.                 return NET_SFTP_TYPE_SYMLINK;
  2809.             // new types introduced in SFTPv5+
  2810.             // http://tools.ietf.org/html/draft-ietf-secsh-filexfer-05#section-5.2
  2811.             case 0010000: // named pipe (fifo)
  2812.                 return NET_SFTP_TYPE_FIFO;
  2813.             case 0020000: // character special
  2814.                 return NET_SFTP_TYPE_CHAR_DEVICE;
  2815.             case 0060000: // block special
  2816.                 return NET_SFTP_TYPE_BLOCK_DEVICE;
  2817.             case 0140000: // socket
  2818.                 return NET_SFTP_TYPE_SOCKET;
  2819.             case 0160000: // whiteout
  2820.                 // "SPECIAL should be used for files that are of
  2821.                 //  a known type which cannot be expressed in the protocol"
  2822.                 return NET_SFTP_TYPE_SPECIAL;
  2823.             default:
  2824.                 return NET_SFTP_TYPE_UNKNOWN;
  2825.         }
  2826.     }
  2828.     /**
  2829.      * Parse Longname
  2830.      *
  2831.      * SFTPv3 doesn't provide any easy way of identifying a file type.  You could try to open
  2832.      * a file as a directory and see if an error is returned or you could try to parse the
  2833.      * SFTPv3-specific longname field of the SSH_FXP_NAME packet.  That's what this function does.
  2834.      * The result is returned using the
  2835.      * {@link http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-5.2 SFTPv4 type constants}.
  2836.      *
  2837.      * If the longname is in an unrecognized format bool(false) is returned.
  2838.      *
  2839.      * @param string $longname
  2840.      * @return mixed
  2841.      * @access private
  2842.      */
  2843.     private function parseLongname($longname)
  2844.     {
  2845.         // http://en.wikipedia.org/wiki/Unix_file_types
  2846.         // http://en.wikipedia.org/wiki/Filesystem_permissions#Notation_of_traditional_Unix_permissions
  2847.         if (preg_match('#^[^/]([r-][w-][xstST-]){3}#', $longname)) {
  2848.             switch ($longname[0]) {
  2849.                 case '-':
  2850.                     return NET_SFTP_TYPE_REGULAR;
  2851.                 case 'd':
  2852.                     return NET_SFTP_TYPE_DIRECTORY;
  2853.                 case 'l':
  2854.                     return NET_SFTP_TYPE_SYMLINK;
  2855.                 default:
  2856.                     return NET_SFTP_TYPE_SPECIAL;
  2857.             }
  2858.         }
  2860.         return false;
  2861.     }
  2863.     /**
  2864.      * Sends SFTP Packets
  2865.      *
  2866.      * See '6. General Packet Format' of draft-ietf-secsh-filexfer-13 for more info.
  2867.      *
  2868.      * @param int $type
  2869.      * @param string $data
  2870.      * @param int $request_id
  2871.      * @see self::_get_sftp_packet()
  2872.      * @see self::send_channel_packet()
  2873.      * @return bool
  2874.      * @access private
  2875.      */
  2876.     private function send_sftp_packet($type, $data, $request_id = 1)
  2877.     {
  2878.         // in SSH2.php the timeout is cumulative per function call. eg. exec() will
  2879.         // timeout after 10s. but for SFTP.php it's cumulative per packet
  2880.         $this->curTimeout = $this->timeout;
  2882.         $packet = $this->use_request_id ?
  2883.             pack('NCNa*', strlen($data) + 5, $type, $request_id, $data) :
  2884.             pack('NCa*',  strlen($data) + 1, $type, $data);
  2886.         $start = microtime(true);
  2887.         $result = $this->send_channel_packet(self::CHANNEL, $packet);
  2888.         $stop = microtime(true);
  2890.         if (defined('NET_SFTP_LOGGING')) {
  2891.             $packet_type = '-> ' . $this->packet_types[$type] .
  2892.                            ' (' . round($stop - $start, 4) . 's)';
  2893.             if (NET_SFTP_LOGGING == self::LOG_REALTIME) {
  2894.                 switch (PHP_SAPI) {
  2895.                     case 'cli':
  2896.                         $start = $stop = "\r\n";
  2897.                         break;
  2898.                     default:
  2899.                         $start = '<pre>';
  2900.                         $stop = '</pre>';
  2901.                 }
  2902.                 echo $start . $this->format_log([$data], [$packet_type]) . $stop;
  2903.                 @flush();
  2904.                 @ob_flush();
  2905.             } else {
  2906.                 $this->packet_type_log[] = $packet_type;
  2907.                 if (NET_SFTP_LOGGING == self::LOG_COMPLEX) {
  2908.                     $this->packet_log[] = $data;
  2909.                 }
  2910.             }
  2911.         }
  2913.         return $result;
  2914.     }
  2916.     /**
  2917.      * Resets a connection for re-use
  2918.      *
  2919.      * @param int $reason
  2920.      * @access private
  2921.      */
  2922.     protected function reset_connection($reason)
  2923.     {
  2924.         parent::reset_connection($reason);
  2925.         $this->use_request_id = false;
  2926.         $this->pwd = false;
  2927.         $this->requestBuffer = [];
  2928.     }
  2930.     /**
  2931.      * Receives SFTP Packets
  2932.      *
  2933.      * See '6. General Packet Format' of draft-ietf-secsh-filexfer-13 for more info.
  2934.      *
  2935.      * Incidentally, the number of SSH_MSG_CHANNEL_DATA messages has no bearing on the number of SFTP packets present.
  2936.      * There can be one SSH_MSG_CHANNEL_DATA messages containing two SFTP packets or there can be two SSH_MSG_CHANNEL_DATA
  2937.      * messages containing one SFTP packet.
  2938.      *
  2939.      * @see self::_send_sftp_packet()
  2940.      * @return string
  2941.      * @access private
  2942.      */
  2943.     private function get_sftp_packet($request_id = null)
  2944.     {
  2945.         if (isset($request_id) && isset($this->requestBuffer[$request_id])) {
  2946.             $this->packet_type = $this->requestBuffer[$request_id]['packet_type'];
  2947.             $temp = $this->requestBuffer[$request_id]['packet'];
  2948.             unset($this->requestBuffer[$request_id]);
  2949.             return $temp;
  2950.         }
  2952.         // in SSH2.php the timeout is cumulative per function call. eg. exec() will
  2953.         // timeout after 10s. but for SFTP.php it's cumulative per packet
  2954.         $this->curTimeout = $this->timeout;
  2956.         $start = microtime(true);
  2958.         // SFTP packet length
  2959.         while (strlen($this->packet_buffer) < 4) {
  2960.             $temp = $this->get_channel_packet(self::CHANNEL, true);
  2961.             if (is_bool($temp)) {
  2962.                 $this->packet_type = false;
  2963.                 $this->packet_buffer = '';
  2964.                 return false;
  2965.             }
  2966.             $this->packet_buffer.= $temp;
  2967.         }
  2968.         if (strlen($this->packet_buffer) < 4) {
  2969.             return false;
  2970.         }
  2971.         extract(unpack('Nlength', Strings::shift($this->packet_buffer, 4)));
  2972.         /** @var integer $length */
  2974.         $tempLength = $length;
  2975.         $tempLength-= strlen($this->packet_buffer);
  2978.         // 256 * 1024 is what SFTP_MAX_MSG_LENGTH is set to in OpenSSH's sftp-common.h
  2979.         if ($tempLength > 256 * 1024) {
  2980.             throw new \RuntimeException('Invalid Size');
  2981.         }
  2983.         // SFTP packet type and data payload
  2984.         while ($tempLength > 0) {
  2985.             $temp = $this->get_channel_packet(self::CHANNEL, true);
  2986.             if (is_bool($temp)) {
  2987.                 $this->packet_type = false;
  2988.                 $this->packet_buffer = '';
  2989.                 return false;
  2990.             }
  2991.             $this->packet_buffer.= $temp;
  2992.             $tempLength-= strlen($temp);
  2993.         }
  2995.         $stop = microtime(true);
  2997.         $this->packet_type = ord(Strings::shift($this->packet_buffer));
  2999.         if ($this->use_request_id) {
  3000.             extract(unpack('Npacket_id', Strings::shift($this->packet_buffer, 4))); // remove the request id
  3001.             $length-= 5; // account for the request id and the packet type
  3002.         } else {
  3003.             $length-= 1; // account for the packet type
  3004.         }
  3006.         $packet = Strings::shift($this->packet_buffer, $length);
  3008.         if (defined('NET_SFTP_LOGGING')) {
  3009.             $packet_type = '<- ' . $this->packet_types[$this->packet_type] .
  3010.                            ' (' . round($stop - $start, 4) . 's)';
  3011.             if (NET_SFTP_LOGGING == self::LOG_REALTIME) {
  3012.                 switch (PHP_SAPI) {
  3013.                     case 'cli':
  3014.                         $start = $stop = "\r\n";
  3015.                         break;
  3016.                     default:
  3017.                         $start = '<pre>';
  3018.                         $stop = '</pre>';
  3019.                 }
  3020.                 echo $start . $this->format_log([$packet], [$packet_type]) . $stop;
  3021.                 @flush();
  3022.                 @ob_flush();
  3023.             } else {
  3024.                 $this->packet_type_log[] = $packet_type;
  3025.                 if (NET_SFTP_LOGGING == self::LOG_COMPLEX) {
  3026.                     $this->packet_log[] = $packet;
  3027.                 }
  3028.             }
  3029.         }
  3031.         if (isset($request_id) && $this->use_request_id && $packet_id != $request_id) {
  3032.             $this->requestBuffer[$packet_id] = array(
  3033.                 'packet_type' => $this->packet_type,
  3034.                 'packet' => $packet
  3035.             );
  3036.             return $this->get_sftp_packet($request_id);
  3037.         }
  3039.         return $packet;
  3040.     }
  3042.     /**
  3043.      * Returns a log of the packets that have been sent and received.
  3044.      *
  3045.      * Returns a string if NET_SFTP_LOGGING == self::LOG_COMPLEX, an array if NET_SFTP_LOGGING == self::LOG_SIMPLE and false if !defined('NET_SFTP_LOGGING')
  3046.      *
  3047.      * @access public
  3048.      * @return array|string
  3049.      */
  3050.     public function getSFTPLog()
  3051.     {
  3052.         if (!defined('NET_SFTP_LOGGING')) {
  3053.             return false;
  3054.         }
  3056.         switch (NET_SFTP_LOGGING) {
  3057.             case self::LOG_COMPLEX:
  3058.                 return $this->format_log($this->packet_log, $this->packet_type_log);
  3059.                 break;
  3060.             //case self::LOG_SIMPLE:
  3061.             default:
  3062.                 return $this->packet_type_log;
  3063.         }
  3064.     }
  3066.     /**
  3067.      * Returns all errors
  3068.      *
  3069.      * @return array
  3070.      * @access public
  3071.      */
  3072.     public function getSFTPErrors()
  3073.     {
  3074.         return $this->sftp_errors;
  3075.     }
  3077.     /**
  3078.      * Returns the last error
  3079.      *
  3080.      * @return string
  3081.      * @access public
  3082.      */
  3083.     public function getLastSFTPError()
  3084.     {
  3085.         return count($this->sftp_errors) ? $this->sftp_errors[count($this->sftp_errors) - 1] : '';
  3086.     }
  3088.     /**
  3089.      * Get supported SFTP versions
  3090.      *
  3091.      * @return array
  3092.      * @access public
  3093.      */
  3094.     public function getSupportedVersions()
  3095.     {
  3096.         $temp = ['version' => $this->version];
  3097.         if (isset($this->extensions['versions'])) {
  3098.             $temp['extensions'] = $this->extensions['versions'];
  3099.         }
  3100.         return $temp;
  3101.     }
  3103.     /**
  3104.      * Disconnect
  3105.      *
  3106.      * @param int $reason
  3107.      * @return bool
  3108.      * @access protected
  3109.      */
  3110.     protected function disconnect_helper($reason)
  3111.     {
  3112.         $this->pwd = false;
  3113.         parent::disconnect_helper($reason);
  3114.     }
  3116.     /**
  3117.      * Enable Date Preservation
  3118.      *
  3119.      * @access public
  3120.      */
  3121.     function enableDatePreservation()
  3122.     {
  3123.         $this->preserveTime = true;
  3124.     }
  3126.     /**
  3127.      * Disable Date Preservation
  3128.      *
  3129.      * @access public
  3130.      */
  3131.     function disableDatePreservation()
  3132.     {
  3133.         $this->preserveTime = false;
  3134.     }
  3135. }