[ Index ]

PHP Cross Reference of DokuWiki

title

Body

[close]

/vendor/phpseclib/phpseclib/phpseclib/Net/ -> SFTP.php (summary)

Pure-PHP implementation of SFTP. PHP version 5

Author: Jim Wigginton
Copyright: 2009 Jim Wigginton
License: http://www.opensource.org/licenses/mit-license.html MIT License
Link: http://phpseclib.sourceforge.net
File Size: 3547 lines (120 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

SFTP:: (81 methods):
  __construct()
  precheck()
  partial_init_sftp_connection()
  init_sftp_connection()
  disableStatCache()
  enableStatCache()
  clearStatCache()
  enablePathCanonicalization()
  disablePathCanonicalization()
  enableArbitraryLengthPackets()
  disableArbitraryLengthPackets()
  pwd()
  logError()
  realpath()
  chdir()
  nlist()
  nlist_helper()
  rawlist()
  readlist()
  comparator()
  setListOrder()
  update_stat_cache()
  remove_from_stat_cache()
  query_stat_cache()
  stat()
  lstat()
  stat_helper()
  truncate()
  touch()
  chown()
  chgrp()
  chmod()
  setstat()
  setstat_recursive()
  readlink()
  symlink()
  mkdir()
  mkdir_helper()
  rmdir()
  put()
  read_put_responses()
  close_handle()
  get()
  delete()
  delete_recursive()
  file_exists()
  is_dir()
  is_file()
  is_link()
  is_readable()
  is_writable()
  is_writeable()
  fileatime()
  filemtime()
  fileperms()
  fileowner()
  filegroup()
  recursiveFilesize()
  filesize()
  filetype()
  get_stat_cache_prop()
  get_lstat_cache_prop()
  get_xstat_cache_prop()
  rename()
  parseTime()
  parseAttributes()
  parseMode()
  parseLongname()
  send_sftp_packet()
  reset_connection()
  get_sftp_packet()
  append_log()
  getSFTPLog()
  getSFTPErrors()
  getLastSFTPError()
  getSupportedVersions()
  getNegotiatedVersion()
  setPreferredVersion()
  disconnect_helper()
  enableDatePreservation()
  disableDatePreservation()


Class: SFTP  - X-Ref

Pure-PHP implementations of SFTP.

__construct($host, $port = 22, $timeout = 10)   X-Ref
Default Constructor.

Connects to an SFTP server

$host can either be a string, representing the host, or a stream resource.

param: mixed $host
param: int $port
param: int $timeout

precheck()   X-Ref
Check a few things before SFTP functions are called

return: bool

partial_init_sftp_connection()   X-Ref
Partially initialize an SFTP connection

return: bool

init_sftp_connection()   X-Ref
(Re)initializes the SFTP channel

return: bool

disableStatCache()   X-Ref
Disable the stat cache


enableStatCache()   X-Ref
Enable the stat cache


clearStatCache()   X-Ref
Clear the stat cache


enablePathCanonicalization()   X-Ref
Enable path canonicalization


disablePathCanonicalization()   X-Ref
Disable path canonicalization

If this is enabled then $sftp->pwd() will not return the canonicalized absolute path


enableArbitraryLengthPackets()   X-Ref
Enable arbitrary length packets


disableArbitraryLengthPackets()   X-Ref
Disable arbitrary length packets


pwd()   X-Ref
Returns the current directory name

return: string|bool

logError($response, $status = -1)   X-Ref
Logs errors

param: string $response
param: int $status

realpath($path)   X-Ref
Canonicalize the Server-Side Path Name

SFTP doesn't provide a mechanism by which the current working directory can be changed, so we'll emulate it.  Returns
the absolute (canonicalized) path.

If canonicalize_paths has been disabled using disablePathCanonicalization(), $path is returned as-is.

return: mixed
param: string $path
see: self::chdir()
see: self::disablePathCanonicalization()

chdir($dir)   X-Ref
Changes the current directory

return: bool
param: string $dir

nlist($dir = '.', $recursive = false)   X-Ref
Returns a list of files in the given directory

return: array|false
param: string $dir
param: bool $recursive

nlist_helper($dir, $recursive, $relativeDir)   X-Ref
Helper method for nlist

return: array|false
param: string $dir
param: bool $recursive
param: string $relativeDir

rawlist($dir = '.', $recursive = false)   X-Ref
Returns a detailed list of files in the given directory

return: array|false
param: string $dir
param: bool $recursive

readlist($dir, $raw = true)   X-Ref
Reads a list, be it detailed or not, of files in the given directory

return: array|false
param: string $dir
param: bool $raw

comparator(array $a, array $b)   X-Ref
Compares two rawlist entries using parameters set by setListOrder()

Intended for use with uasort()

return: int
param: array $a
param: array $b

setListOrder(...$args)   X-Ref
Defines how nlist() and rawlist() will be sorted - if at all.

If sorting is enabled directories and files will be sorted independently with
directories appearing before files in the resultant array that is returned.

Any parameter returned by stat is a valid sort parameter for this function.
Filename comparisons are case insensitive.

Examples:

$sftp->setListOrder('filename', SORT_ASC);
$sftp->setListOrder('size', SORT_DESC, 'filename', SORT_ASC);
$sftp->setListOrder(true);
Separates directories from files but doesn't do any sorting beyond that
$sftp->setListOrder();
Don't do any sort of sorting

param: string ...$args

update_stat_cache($path, $value)   X-Ref
Save files / directories to cache

param: string $path
param: mixed $value

remove_from_stat_cache($path)   X-Ref
Remove files / directories from cache

return: bool
param: string $path

query_stat_cache($path)   X-Ref
Checks cache for path

Mainly used by file_exists

return: mixed
param: string $path

stat($filename)   X-Ref
Returns general information about a file.

Returns an array on success and false otherwise.

return: array|false
param: string $filename

lstat($filename)   X-Ref
Returns general information about a file or symbolic link.

Returns an array on success and false otherwise.

return: array|false
param: string $filename

stat_helper($filename, $type)   X-Ref
Returns general information about a file or symbolic link

Determines information without calling \phpseclib3\Net\SFTP::realpath().
The second parameter can be either NET_SFTP_STAT or NET_SFTP_LSTAT.

return: array|false
param: string $filename
param: int $type

truncate($filename, $new_size)   X-Ref
Truncates a file to a given length

return: bool
param: string $filename
param: int $new_size

touch($filename, $time = null, $atime = null)   X-Ref
Sets access and modification time of file.

If the file does not exist, it will be created.

return: bool
param: string $filename
param: int $time
param: int $atime

chown($filename, $uid, $recursive = false)   X-Ref
Changes file or directory owner

$uid should be an int for SFTPv3 and a string for SFTPv4+. Ideally the string
would be of the form "user@dns_domain" but it does not need to be.
`$sftp->getSupportedVersions()['version']` will return the specific version
that's being used.

Returns true on success or false on error.

return: bool
param: string $filename
param: int|string $uid
param: bool $recursive

chgrp($filename, $gid, $recursive = false)   X-Ref
Changes file or directory group

$gid should be an int for SFTPv3 and a string for SFTPv4+. Ideally the string
would be of the form "user@dns_domain" but it does not need to be.
`$sftp->getSupportedVersions()['version']` will return the specific version
that's being used.

Returns true on success or false on error.

return: bool
param: string $filename
param: int|string $gid
param: bool $recursive

chmod($mode, $filename, $recursive = false)   X-Ref
Set permissions on a file.

Returns the new file permissions on success or false on error.
If $recursive is true than this just returns true or false.

return: mixed
param: int $mode
param: string $filename
param: bool $recursive

setstat($filename, $attr, $recursive)   X-Ref
Sets information about a file

return: bool
param: string $filename
param: string $attr
param: bool $recursive

setstat_recursive($path, $attr, &$i)   X-Ref
Recursively sets information on directories on the SFTP server

Minimizes directory lookups and SSH_FXP_STATUS requests for speed.

return: bool
param: string $path
param: string $attr
param: int $i

readlink($link)   X-Ref
Return the target of a symbolic link

return: mixed
param: string $link

symlink($target, $link)   X-Ref
Create a symlink

symlink() creates a symbolic link to the existing target with the specified name link.

return: bool
param: string $target
param: string $link

mkdir($dir, $mode = -1, $recursive = false)   X-Ref
Creates a directory.

return: bool
param: string $dir
param: int $mode
param: bool $recursive

mkdir_helper($dir, $mode)   X-Ref
Helper function for directory creation

return: bool
param: string $dir
param: int $mode

rmdir($dir)   X-Ref
Removes a directory.

return: bool
param: string $dir

put($remote_file, $data, $mode = self::SOURCE_STRING, $start = -1, $local_start = -1, $progressCallback = null)   X-Ref
Uploads a file to the SFTP server.

By default, \phpseclib3\Net\SFTP::put() does not read from the local filesystem.  $data is dumped directly into $remote_file.
So, for example, if you set $data to 'filename.ext' and then do \phpseclib3\Net\SFTP::get(), you will get a file, twelve bytes
long, containing 'filename.ext' as its contents.

Setting $mode to self::SOURCE_LOCAL_FILE will change the above behavior.  With self::SOURCE_LOCAL_FILE, $remote_file will
contain as many bytes as filename.ext does on your local filesystem.  If your filename.ext is 1MB then that is how
large $remote_file will be, as well.

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

If $data is a resource then it'll be used as a resource instead.

Currently, only binary mode is supported.  As such, if the line endings need to be adjusted, you will need to take
care of that, yourself.

$mode can take an additional two parameters - self::RESUME and self::RESUME_START. These are bitwise AND'd with
$mode. So if you want to resume upload of a 300mb file on the local file system you'd set $mode to the following:

self::SOURCE_LOCAL_FILE | self::RESUME

If you wanted to simply append the full contents of a local file to the full contents of a remote file you'd replace
self::RESUME with self::RESUME_START.

If $mode & (self::RESUME | self::RESUME_START) then self::RESUME_START will be assumed.

$start and $local_start give you more fine grained control over this process and take precident over self::RESUME
when they're non-negative. ie. $start could let you write at the end of a file (like self::RESUME) or in the middle
of one. $local_start could let you start your reading from the end of a file (like self::RESUME_START) or in the
middle of one.

Setting $local_start to > 0 or $mode | self::RESUME_START doesn't do anything unless $mode | self::SOURCE_LOCAL_FILE.

{@internal ASCII mode for SFTPv4/5/6 can be supported by adding a new function - \phpseclib3\Net\SFTP::setMode().}

return: bool
param: string $remote_file
param: string|resource $data
param: int $mode
param: int $start
param: int $local_start
param: callable|null $progressCallback

read_put_responses($i)   X-Ref
Reads multiple successive SSH_FXP_WRITE responses

Sending an SSH_FXP_WRITE packet and immediately reading its response isn't as efficient as blindly sending out $i
SSH_FXP_WRITEs, in succession, and then reading $i responses.

return: bool
param: int $i

close_handle($handle)   X-Ref
Close handle

return: bool
param: string $handle

get($remote_file, $local_file = false, $offset = 0, $length = -1, $progressCallback = null)   X-Ref
Downloads a file from the SFTP server.

Returns a string containing the contents of $remote_file if $local_file is left undefined or a boolean false if
the operation was unsuccessful.  If $local_file is defined, returns true or false depending on the success of the
operation.

$offset and $length can be used to download files in chunks.

return: string|bool
param: string $remote_file
param: string|bool|resource|callable $local_file
param: int $offset
param: int $length
param: callable|null $progressCallback

delete($path, $recursive = true)   X-Ref
Deletes a file on the SFTP server.

return: bool
param: string $path
param: bool $recursive

delete_recursive($path, &$i)   X-Ref
Recursively deletes directories on the SFTP server

Minimizes directory lookups and SSH_FXP_STATUS requests for speed.

return: bool
param: string $path
param: int $i

file_exists($path)   X-Ref
Checks whether a file or directory exists

return: bool
param: string $path

is_dir($path)   X-Ref
Tells whether the filename is a directory

return: bool
param: string $path

is_file($path)   X-Ref
Tells whether the filename is a regular file

return: bool
param: string $path

is_link($path)   X-Ref
Tells whether the filename is a symbolic link

return: bool
param: string $path

is_readable($path)   X-Ref
Tells whether a file exists and is readable

return: bool
param: string $path

is_writable($path)   X-Ref
Tells whether the filename is writable

return: bool
param: string $path

is_writeable($path)   X-Ref
Tells whether the filename is writeable

Alias of is_writable

return: bool
param: string $path

fileatime($path)   X-Ref
Gets last access time of file

return: mixed
param: string $path

filemtime($path)   X-Ref
Gets file modification time

return: mixed
param: string $path

fileperms($path)   X-Ref
Gets file permissions

return: mixed
param: string $path

fileowner($path)   X-Ref
Gets file owner

return: mixed
param: string $path

filegroup($path)   X-Ref
Gets file group

return: mixed
param: string $path

recursiveFilesize(array $files)   X-Ref
Recursively go through rawlist() output to get the total filesize

return: int

filesize($path, $recursive = false)   X-Ref
Gets file size

return: mixed
param: string $path
param: bool $recursive

filetype($path)   X-Ref
Gets file type

return: string|false
param: string $path

get_stat_cache_prop($path, $prop)   X-Ref
Return a stat properity

Uses cache if appropriate.

return: mixed
param: string $path
param: string $prop

get_lstat_cache_prop($path, $prop)   X-Ref
Return an lstat properity

Uses cache if appropriate.

return: mixed
param: string $path
param: string $prop

get_xstat_cache_prop($path, $prop, $type)   X-Ref
Return a stat or lstat properity

Uses cache if appropriate.

return: mixed
param: string $path
param: string $prop
param: string $type

rename($oldname, $newname)   X-Ref
Renames a file or a directory on the SFTP server.

If the file already exists this will return false

return: bool
param: string $oldname
param: string $newname

parseTime($key, $flags, &$response)   X-Ref
Parse Time

See '7.7.  Times' of draft-ietf-secsh-filexfer-13 for more info.

return: array
param: string $key
param: int $flags
param: string $response

parseAttributes(&$response)   X-Ref
Parse Attributes

See '7.  File Attributes' of draft-ietf-secsh-filexfer-13 for more info.

return: array
param: string $response

parseMode($mode)   X-Ref
Attempt to identify the file type

Quoting the SFTP RFC, "Implementations MUST NOT send bits that are not defined" but they seem to anyway

return: int
param: int $mode

parseLongname($longname)   X-Ref
Parse Longname

SFTPv3 doesn't provide any easy way of identifying a file type.  You could try to open
a file as a directory and see if an error is returned or you could try to parse the
SFTPv3-specific longname field of the SSH_FXP_NAME packet.  That's what this function does.
The result is returned using the
{@link http://tools.ietf.org/html/draft-ietf-secsh-filexfer-04#section-5.2 SFTPv4 type constants}.

If the longname is in an unrecognized format bool(false) is returned.

return: mixed
param: string $longname

send_sftp_packet($type, $data, $request_id = 1)   X-Ref
Sends SFTP Packets

See '6. General Packet Format' of draft-ietf-secsh-filexfer-13 for more info.

return: void
param: int $type
param: string $data
param: int $request_id
see: self::_get_sftp_packet()
see: self::send_channel_packet()

reset_connection($reason)   X-Ref
Resets a connection for re-use

param: int $reason

get_sftp_packet($request_id = null)   X-Ref
Receives SFTP Packets

See '6. General Packet Format' of draft-ietf-secsh-filexfer-13 for more info.

Incidentally, the number of SSH_MSG_CHANNEL_DATA messages has no bearing on the number of SFTP packets present.
There can be one SSH_MSG_CHANNEL_DATA messages containing two SFTP packets or there can be two SSH_MSG_CHANNEL_DATA
messages containing one SFTP packet.

return: string
see: self::_send_sftp_packet()

append_log($message_number, $message)   X-Ref
Logs data packets

Makes sure that only the last 1MB worth of packets will be logged

param: string $message_number
param: string $message

getSFTPLog()   X-Ref
Returns a log of the packets that have been sent and received.

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')

return: array|string|false

getSFTPErrors()   X-Ref
Returns all errors on the SFTP layer

return: array

getLastSFTPError()   X-Ref
Returns the last error on the SFTP layer

return: string

getSupportedVersions()   X-Ref
Get supported SFTP versions

return: array

getNegotiatedVersion()   X-Ref
Get supported SFTP versions

return: int|false

setPreferredVersion($version)   X-Ref
Set preferred version

If you're preferred version isn't supported then the highest supported
version of SFTP will be utilized. Set to null or false or int(0) to
unset the preferred version

param: int $version

disconnect_helper($reason)   X-Ref
Disconnect

return: false
param: int $reason

enableDatePreservation()   X-Ref
Enable Date Preservation


disableDatePreservation()   X-Ref
Disable Date Preservation