ftpClient
for handling FTP communication
This class provides comfortable communication with FTP-servers. You may do everything enabled by the PHP-FTP-extension and further functionalities, like recursive-deletion, -up- and -download. Another feature is to create directories recursively.
This is a port of the Net_FTP PEAR class to be fully PHP5 compliant. It revises the error model to throw exceptions as well as tidying up the options, constants and making some small refactorings. Additionally, the all space indentation has been replaced with tabs reducing overall file size by 6Kb.
Because this is simply a port of Net_FTP, it is released under the same license as Net_FTP.
Example usage:
// connect to mirror service and list contents of the kubuntu directory
$oFtp = new ftpClient(
array(
ftpClient::OPTION_HOSTNAME => 'mirror.csclub.uwaterloo.ca',
ftpClient::OPTION_PORT => '21',
ftpClient::OPTION_TIMEOUT => 20,
ftpClient::OPTION_TRANSFER_MODE => FTP_ASCII,
ftpClient::OPTION_USERNAME => 'anonymous',
ftpClient::OPTION_PASSWORD => 'username.example.com',
)
);
if ( $oFtp->login() ) {
$oFtp->cd('ubuntu-releases/kubuntu/');
$res = $oFtp->ls();
print_r($res);
}
$oFtp->disconnect();
To switch to/from passive mode an FTP connection must first be made. This is the only option that cannot be set from the options array as setting ftp_pasv requires the FTP connection resource.
// switch to passive mode $oFtp = new ftpClient(// set options here); $oFtp->connect(); $oFtp->setPassive(); // switch to active $oFtp->setActive();
Dependencies: ftpClient has the following dependencies in the Scorpio Framework: baseOptionsSet ftpException
Methods
public __destruct()
Ensure disconnect is always called when object is destroyed to prevent open resources
public connect([$host = null], [$port = null])
This function generates the FTP-connection. You can optionally define a hostname and/or a port. If you do so, this data is stored inside the object.
public disconnect()
This function close the FTP-connection
public login([$username = null], [$password = null])
This logs you into the ftp-server. You are free to specify username and password in this method. If you specify it, the values will be taken into the corresponding attributes, if do not specify, the attributes are taken.
If connect() has not been called yet, a connection will be setup
public cd($dir)
This changes the currently used directory. You can use either an absolute directory-path (e.g. "/home/blah") or a relative one (e.g. "../test").
public pwd()
Show's you the actual path on the server This function questions the ftp-handle for the actual selected path and returns it.
public mkdir($dir, [$recursive = false])
This works similar to the mkdir-command on your local machine. You can either give it an absolute or relative path. The relative path will be completed with the actual selected server-path. (see: pwd())
public execute($command)
This method tries executing a command on the ftp, using SITE EXEC.
public site($command)
Execute a SITE command on the server This method tries to execute a SITE command on the ftp server.
public chmod($target, $permissions)
This method will try to chmod the file specified on the server Currently, you must give a number as the the permission argument (777 or similar). The file can be either a relative or absolute path. NOTE: Some servers do not support this feature. In that case, you will get an exception thrown. If successful, the method returns true
public chmodRecursive($target, $permissions)
This method will try to chmod a folder and all of its contents on the server. The target argument must be a folder or an array of folders and the permissions argument have to be an integer (i.e. 777). The file can be either a relative or absolute path. NOTE: Some servers do not support this feature. In that case, you will get an exception thrown. If successful, the method returns true
public rename($remote_from, $remote_to)
Rename or move a file or a directory from the ftp-server
private _makeDirPermissions($permissions)
This will return logical permissions mask for directory. if directory has to be readable it have also be executable
public mdtm($file, [$format = null])
This will return the last modification-time of a file. You can either give this function a relative or an absolute path to the file to check. NOTE: Some servers will not support this feature and the function works only on files, not directories! When successful, it will return the last modification-time as a unix-timestamp or, when $format is specified, a preformated timestring.
public size($file)
This will return the size of a given file in bytes. You can either give this function a relative or an absolute file-path. NOTE: Some servers do not support this feature!
public ls([$dir = null], [$mode = 2])
This method returns a directory-list of the current directory or given one.
To display the current selected directory, simply set the first parameter to
null
or leave it blank, if you do not want to use any other parameters.
There are 4 different modes of listing directories. Either to list only
the files (using ftpClient::LS_MODE_FILES_ONLY), to list only directories
(using ftpClient::LS_MODE_DIRS_ONLY) or to show both (using
ftpClient::LS_MODE_DIRS_FILES, which is default).
The 4th one is the ftpClient::LS_MODE_RAW_LIST, which returns just the array
created by the ftp_rawlist() - function built into PHP.
The other function-modes will return an array containing the requested data.
The files and dirs are listed in human-sorted order, but if you select
ftpClient::LS_MODE_DIRS_FILES the directories will be added above the files,
although both sorted.
All elements in the arrays are associative arrays themselves. They have the
following structure:
Dirs:
["name"] => string The name of the directory
["rights"] => string The rights of the directory (in style
"rwxr-xr-x")
["user"] => string The owner of the directory
["group"] => string The group-owner of the directory
["files_inside"]=> string The number of files/dirs inside the
directory excluding "." and ".."
["date"] => int The creation-date as Unix timestamp
["is_dir"] => bool true, cause this is a dir
Files:
["name"] => string The name of the file
["size"] => int Size in bytes
["rights"] => string The rights of the file (in style
"rwxr-xr-x")
["user"] => string The owner of the file
["group"] => string The group-owner of the file
["date"] => int The creation-date as Unix timestamp
["is_dir"] => bool false, cause this is a file
public rm($path, [$recursive = false], [$filesonly = false])
This method will delete the given file or directory ($path) from the server (maybe recursive).
Whether the given string is a file or directory is only determined by the last sign inside the string ("/" or not).
If you specify a directory, you can optionally specify $recursive as true, to let the directory be deleted recursive (with all sub-directories and files inherited).
You can either give a absolute or relative path for the file / dir. If you choose to use the relative path, it will be automatically completed with the actual selected directory.
public get($remote_file, $local_file, [$overwrite = false], [$mode = null])
This function will download a file from the ftp-server.
You can either specify an absolute path to the file (beginning with "/") or a relative one, which will be completed with the actual directory you selected on the server. You can specify the path to which the file will be downloaded on the local machine, if the file should be overwritten if it exists (optionally, default is no overwriting) and in which mode (FTP_ASCII or FTP_BINARY) the file should be downloaded (if you do not specify this, the method tries to determine it automatically from the mode-directory or uses the default-mode, set by you).
If you give a relative path to the local-file, the script-path is used as basepath.
public put($local_file, $remote_file, [$overwrite = false], [$mode = null], [$options = 0])
This function will upload a file to the ftp-server.
You can either specify a absolute path to the remote-file (beginning with "/") or a relative one, which will be completed with the actual directory you selected on the server. You can specify the path from which the file will be uploaded on the local maschine, if the file should be overwritten if it exists (optionally, default is no overwriting) and in which mode (FTP_ASCII or FTP_BINARY) the file should be downloaded (if you do not specify this, the method tries to determine it automatically from the mode-directory or uses the default-mode, set by you).
If you give a relative path to the local-file, the script-path is used as basepath.
public getRecursive($remote_path, $local_path, [$overwrite = false], [$mode = null])
This functionality allows you to transfer a whole directory-structure from the remote-ftp to your local host. You have to give a remote-directory (ending with '/') and the local directory (ending with '/') where to put the files you download. The remote path is automatically completed with the current-remote-dir, if you give a relative path to this function. You can give a relative path for the $local_path, too. Then the script-basedir will be used for comletion of the path. The parameter $overwrite will determine, whether to overwrite existing files or not. Standard for this is false. Fourth you can explicitly set a mode for all transfer actions done. If you do not set this, the method tries to determine the transfer mode by checking your mode-directory for the file extension. If the extension is not inside the mode-directory, it will get your default mode.
Since 1.4 no error will be returned when a file exists while $overwrite is set to false.
public putRecursive($local_path, $remote_path, [$overwrite = false], [$mode = null])
This functionality allows you to transfer a whole directory-structure from your local host to the remote-ftp. You have to give a remote-directory (ending with '/') and the local directory (ending with '/') where to put the files you download. The remote path is automatically completed with the current-remote-dir, if you give a relative path to this function. You can give a relative path for the $local_path, too. Then the script-basedir will be used for comletion of the path. The parameter $overwrite will determine, whether to overwrite existing files or not. Standard for this is false. Fourth you can explicitly set a mode for all transfer actions done. If you do not set this, the method tries to determine the transfer mode by checking your mode-directory for the file-extension. If the extension is not inside the mode-directory, it will get your default mode.
public checkFileExtension($filename)
This checks, whether a file should be transfered in ascii- or binary-mode by it's file-extension. If the file-extension is not set or the extension is not inside one of the extension-dirs, the actual set transfer-mode is returned.
public getOptionsSet()
Returns the baseOptionsSet object
public setOptionsSet($inOptionsSet)
Set a new options set object over the current one
public setHostname($host)
Set the hostname
public setPort($port)
Set the Port
public setUsername($user)
Set the Username
public setPassword($password)
Set the password
public setMode($mode)
Set the transfer-mode. You can use the predefined constants FTP_ASCII or FTP_BINARY. The mode will be stored for any further transfers.
public setPassive()
Set the transfer-method to passive mode
public setActive()
Set the transfer-method to active mode
public setTimeout([$timeout = 0])
Set the timeout for FTP operations
Use this method to set a timeout for FTP operation. Timeout has to be an integer.
public addExtension($mode, $ext)
Adds an extension to a mode-directory
The mode-directory saves file-extensions coresponding to filetypes (ascii e.g.: 'php', 'txt', 'htm',...; binary e.g.: 'jpg', 'gif', 'exe',...). The extensions have to be saved without the '.'. And can be predefined in an external file (see: getExtensionsFile()).
The array is build like this: 'php' => FTP_ASCII, 'png' => FTP_BINARY
To change the mode of an extension, just add it again with the new mode!
public removeExtension($ext)
This function removes an extension from the mode-directories (described above).
public getExtensionsFile($filename)
This get's both (ascii- and binary-mode-directories) from the given file. Beware, if you read a file into the mode-directory, all former set values will be unset!
Example file contents: [ASCII] asc = 0 txt = 0 [BINARY] bin = 1 jpg = 1
public getHostname()
Returns the hostname
public getPort()
Returns the port
public getUsername()
Returns the username
public getPassword()
Returns the password
public getMode()
Returns the transfermode, default FTP_ASCII
public isPassive()
Returns, whether the connection is set to passive mode or not
public getExtensionMode($ext)
Returns the mode set for a file-extension
public getTimeoutOption()
Returns the current timeout value, defaulting to 20 seconds
public getTimeout()
Returns the actual timeout set on the current connection.
public attach($observer)
Adds a ftpClientObserver instance to the list of observers that are listening for messages emitted by this Net_FTP instance.
public detach($observer)
Removes a ftpClientObserver instance from the list of observers.
public isAttached($observer)
Returns true if $observer is a currently attached listener
public notify($event)
Informs each registered observer instance that a new message has been sent.
public setDirMatcher($pattern, $matchmap)
Sets the directory listing matcher
Use this method to set the directory listing matcher to a specific pattern. Indicate the pattern as a perl regular expression and give an array containing as keys the fields selected in the regular expression and as values the offset of the subpattern in the pattern.
Example: $pattern = '/(?:(d)|.)([rwxt-]+)\s+(\w+)\s+([\w\d-]+)\s+([\w\d-]+)\s+(\w+) \s+(\S+\s+\S+\s+\S+)\s+(.+)/', $matchmap = array( 'is_dir' => 1, 'rights' => 2, 'files_inside' => 3, 'user' => 4, 'group' => 5, 'size' => 6, 'date' => 7, 'name' => 8, )
Make sure at least the is_dir and name keys are set. The is_dir key should point to a subpattern that is empty for non-directories and non-empty for directories.
private _constructPath($path)
Rebuild the path, if given relative
This method will make a relative path absolute by prepending the current remote directory in front of it.
private _checkRemoteDir($path)
Checks whether the given path is a remote directory by trying to chdir() into it (and back out)
private _rmFile($file)
This will remove a file
private _rmDir($dir)
This will remove a dir
private _rmDirRecursive($dir, [$filesonly = false])
This will remove a dir and all subdirs and -files
private _lsBoth($dir)
Lists up files and directories
private _lsDirs($dir)
Lists up directories
private _lsFiles($dir)
Lists up files
private _listAndParse($dir)
This lists up the directory-content and parses the items into well-formated arrays. The results of this array are sorted (dirs on top, sorted by name; files below, sorted by name).
private _determineOSMatch($dir_list)
Determine server OS This determines the server OS and returns a valid regex to parse ls() output.
private _lsLocal($dir_path)
Lists a local directory
private _natSort($item_1, $item_2)
Function for use with usort(). Compares the list-array-elements by name.
private _parseDate($date)
Parse dates to timestamps
Inherited Methods
Posted by: Scorpio Documentor (Writer), in Ftp on 19 Nov 2009 @ 20:30
This
work is licenced under a
Creative Commons Licence.