Manual

Net_FTP provides comfortable communication with FTP-Servers. It mainly provides an OO wrapper to PHP's integrated FTP functions, adding some missing features like recursive up- and downloading of complete folders, as well as deleting. The options for generating directory listings were also extended to feature well structured listing of directories and/or files.

Constants

Constants – predefined constants

NET_FTP_FILES_ONLY

Makes Net_FTP::ls() return a structures array of files (no directories) in a directory.

NET_FTP_DIRS_ONLY

Makes Net_FTP::ls() return a structures array of directories (no files) in a directory.

NET_FTP_DIRS_FILES

Makes Net_FTP::ls() return a structures array of directories and files in a directory.

NET_FTP_RAWLIST

Makes Net_FTP::ls() return an unstructred array as returned by the PHP function ftp_raw_list().

Net_FTP::Net_FTP()

Net_FTP::Net_FTP() – constructor

Synopsis

require_once 'Net/FTP.php';

object Net_FTP::Net_FTP ( string $host = null , int $port = null )

Description

Create a new object for communication with FTP servers.

Parameter

string $host = null - The host to connect to ( either an IP address or a domain name).
int $port = null - The port to connect to on the server.

Return value

object - the new Net_FTP object.

Note

This function can not be called statically.

Example

Using Net_FTP()

<?php

  require_once 'Net/FTP.php';

  $test = new Net_FTP('ftp.mydomain.com', 21);

?>

Net_FTP::connect()

Net_FTP::connect() – connects to a given FTP server

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::connect ( string $host = null , int $port = null )

Description

Create a new object for communication with FTP servers.

Parameter

string $host = null - The host to connect to ( either an IP address or a domain name). This parameter can be left out, if it has been set in the constructor or manually!
int $port = null - The port to connect to on the server. This parameter can be left out, if it has been set in the constructor or manually!

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Connection failed" will be returned if the connection fails.

Note

This function can not be called statically.

Example

Using connect()

<?php
     
    $test->connect('192.168.0.1', 21);

?>

Net_FTP::disconnect()

Net_FTP::disconnect() – disconnects from the FTP server

Synopsis

require_once 'Net/FTP.php';

void Net_FTP::disconnect ( )

Description

Disconnect from the FTP server you're connected to.

Return value

void

Note

This function can not be called statically.

Example

Using disconnect()

<?php
     
    $test->disconnect();

?>

Net_FTP::login()

Net_FTP::login() – logs into the FTP server you are connected to

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::login ( string $username = null , int $password = null )

Description

Does the login on the FTP server you are connected to. for that you first have to connect to a FTP server before logging in. Username and Password can either be set by the parameters or manually before (using the set-methods).

Parameter

string $username = null - The username to be used for login to. This parameter can be left out, if it has been set manually!
int $password = null - The password to use for login. This parameter can be left out, if it has been set manually!

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Login failed" will be returned if the login fails.

Note

This function can not be called statically.

Example

Using login()

<?php
     
    $test->login('myuser', 'mypass');

?>

Net_FTP::cd()

Net_FTP::cd() – changes the directory on the server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::cd ( string $directory )

Description

Changes the directory on the FTP server you are logged in. The parameter can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Parameter

string $directory - The directory you want to change to. This can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Directory change failed" will be returned if the operation fails.

Note

This function can not be called statically.

Example

Using cd()

<?php
     
    $test->cd('../mydir');

?>

Net_FTP::pwd()

Net_FTP::pwd() – returns the directory on the server you are currently in.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::pwd ( )

Description

Returns the directory currently selected on the server.

Return value

mixed - path (absolute) as string on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Could not determine the actual path" will be returned if the operation fails.

Note

This function can not be called statically.

Example

Using pwd()

<?php

  echo $test->pwd();

?>

Net_FTP::mkdir()

Net_FTP::mkdir() – creates a new directory.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::mkdir ( string $directory , bool $recursive = false )

Description

Creates a new directory on the FTP server. You can give this function either a relative or an absolute path as the first parameter. The second (optional) parameter lets you create directories recursively (meaning you can create './my/new/dir' even if '/my' doesn't exist. All 3 directories would be created ).

Parameter

string $directory - The directory you want to create. This can either be an absolute path (e.g. '/home/mydir') or a relative one (e.g. 'mydir').

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is specific. There is only one errornumber which may occur. The message given by this error will contain the directory where the error occurred in "Creation of '$dir' failed". operation fails.

Note

This function can not be called statically.

Example

Using mkdir()

<?php

  $test->mkdir('../mydir');

?>

Net_FTP::execute()

Net_FTP::execute() – executes a command on the server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::execute ( string $command )

Description

Executes a given command on the server (the SITE EXEC command is added by the method).

Parameter

string $command - The command to be executed (without SITE EXEC).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Note

This function can not be called statically.

Example

Using execute()

<?php
     
    $test->execute($myCommand);

?>

Net_FTP::mdtm()

Net_FTP::mdtm() – returns the last modification date of a file.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::mdtm ( string $file , string $format = null )

Description

gives you the last modification-date of a file either as a unix timestamp or in a formated date.

Parameter

string $file - The file to check. string $format - A date()-function styled format-string.

Return value

mixed - the last modification date on success, otherwise PEAR::Error.

Throws

Several errors may be returned by mdtm. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Filename '$file' seems to be a directory.	The filename you gave the method does not reference a regular-file but a directory.	Specify a correct filenamepath (eg. /my/file/path/foo.html, ../foo.html).
Could not get last-modification-date of '$file'.	The last-modification date could not be determined by PHP. Reasons for this may be that your FTP-server does not support the used command or that you gave the function a non existent file as reference.	check the given file for existence contact the FTP server's admin
Date-format failed on timestamp '$res'.	The given format-string was not well formated.	Check the documentation of the PHP function date().

Note

This function can not be called statically.

Example

Using mdtm()

<?php

  var_dump($test->mdtm('/foo/bar'));

  // returns the last modification time in german timeformat
  var_dump($test->mdtm('/foo/bar', 'd.m.Y, H:i'));

?>

Net_FTP::size()

Net_FTP::size() – returns the size in bytes of a file.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::size ( string $file )

Description

gives you the size of a file bytes.

Parameter

string $file - The file to check.

Return value

mixed - the size of the given file on success, otherwise PEAR::Error.

Throws

The returned PEAR_Error object in case of an error is unspecific. You can ignore the errornumber and errormessage, because only "Connection failed" will be returned if the connection fails.

Note

This function can not be called statically.

Example

Using size()

<?php
     
    var_dump($test->size('/foo/bar'));
    
?>

Net_FTP::ls()

Net_FTP::ls() – returns the listing of a directory in a specified way.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::ls ( string $dir = null , string $mode = NET_FTP_DIRS_FILES )

Description

this function gives you a listing of either the files / directories / both or an unformated array (like the PHP function ftp_rawlist()).

Parameter

string $dir = null - The directory to list. You can either use a relative or an absolute path. This optional parameter will be set to the current path.
int $mode = - A constant representing the nodes list (directories, files, both or a ram directory listing). This parameter is determined by the constants (see: Constants). This parameter is optional and will be set for listing directories and files structured in an array.

Return value

mixed - a directory listing in the form you determine on success, otherwise PEAR::Error.

Throws

Several errors may be returned by ls. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Raw directory-list in wrong format.	The format given by the server on PHP function ftp_rawlist()was wrong. Check if the directory you wanted to be listed is correct and you have access to listing it.	Specify a correct directory path (eg. /my/file/path/, ../) and check (maybe change) the rights on it.
Could not get last-modification-date of '$file'.	The last-modification date could not be determined by PHP. Reasons for this might be that your FTP-server does not support the used command or that you gave the function a non existent file as reference.	check the given file for existence contact the FTP server's admin
Date-format failed on timestamp '$res'.	The given format-string was not well formated.	Check the documentation of the PHP function date().

Note

This function can not be called statically.

Example

Using ls()

<?php

  var_dump($test->ls('/foo/bar'));

?>

Net_FTP::rm()

Net_FTP::rm() – deletes a file or directory.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::rm ( string $path = null , string $recursive = false )

Description

This method deletes a file or a directory.

Parameter

string $path = null - The file or directory to delete. In case you set the second parameter to true, directories will be deleted even if not empty. All files and directories inside will be deleted.
$recursive = false - This parameter determines, whether a directory is deleted only if it's empty (standard) or if all included files and directories will be deleted with it ($recursive = true).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by rm. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Could not delete file '$file'.	The file named $file (complete path) could not be deleted.	Either the file does not exist or you do not have the permission to delete it. So check if the file exists and you have permissions on it.
Directory name '$dir' is invalid, has to end with '/'	You entered a directory for deletion ($recursive = true) without ending '/'.	Correct your parameter.
Could not delete directory '$dir'.	The directory $dir could not be deleted.	Maybe the directory is not empty ($recursive = false) or you do not have the permission to delete the directory.

Note

This function can not be called statically.

Example

Using rm()

<?php
     
    var_dump($test->rm('/foo/bar/', true));
    
?>

Net_FTP::get()

Net_FTP::get() – download a file to the computer your script runs on.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::get ( string $remote_file , string $local_file , bool $overwrite = false , int $mode = null )

Description

This downloads a file from the FTP server to the computer your script runs on.

Parameter

string $remote_file - The file you'd like to download. This could either be an absolute or relative path to a file (not a directory! see: Net_FTP::getRecursive()).
string $local_file - The destination you'd like to download the file to (including filename, not directory!). You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)
bool $overwrite = false - Whether to overwrite the local file if it exists, or not. if not set the file will not be overwritten.
int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. if not specified, the class will try to determine the mode from the file extension (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by get. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Local file '$local_file' exists and may not be overwriten.	The local file you specified exists and you did not specify to overwrite it.	Set parameter $overwrite = true.
Local file '$file' is not writeable. Can not overwrite.	You specified to overwrite the localfile. This did not work.	Maybe you don't have the permission to overwrite the file. Check the filepermissions.
File '$remote_file' could not be downloaded to '$local_file'.	The download of the remote file failed.	This may have several reasons: Maybe the remote file does not exist or the local directory you wanted to download to does not exist or is not writeable.

Note

This function can not be called statically.

Example

Using get()

<?php
     
    var_dump($test->get('foo/bar.zip', '/tmp/downloaded.zip', true, FTP_BINARY));
    
?>

Net_FTP::put()

Net_FTP::put() – upload a file to the FTP server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::put ( string $local_file , string $remote_file , bool $overwrite = false , int $mode = null )

Description

This uploads a file to the FTP server from the computer your script runs on.

Parameter

string $local_file - The source file you'd like to upload. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)
string $remote_file - The path (including filename) you'd like to upload to. This could either be an absolute or relative path to a file (not a directory! see: Net_FTP::putRecursive()).
bool $overwrite = false - Whether to overwrite the remote file, if it exists or not. If not set the file will not be overwritten.
int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. If not specified, the class will try to determine the mode from the file extension (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by put. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Local file '$local_file' does not exist.	The local file you specified does not exist.	Correct the local file path.
Remote file '$remote_file' exists and may not be overwriten.	The specified remote file exists but may not be overwritten.	Maybe you don't have the permission to overwrite the file. Check the filepermissions.
File '$local_file' could not be uploaded to '$remote_file'.	The upload of the local file failed.	This may have several reasons: Maybe the local file does not exist or the remote directory you wanted to upload to does not exist or is not writeable.

Note

This function can not be called statically.

Example

Using put()

<?php

  var_dump($test->put('/tmp/downloaded.zip', 'foo/bar.zip', true, FTP_BINARY));

?>

Net_FTP::getRecursive()

Net_FTP::getRecursive() – download a whole directory to the computer your script runs on.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::getRecursive ( string $remote_path , string $local_path , bool $overwrite = false , int $mode = null )

Description

This downloads a whole directory from the FTP server to the computer your script runs on.

Parameter

string $remote_path - The directory you'd like to download. This could either be an absolute or relative path to a directory (path has to end with '/').
string $local_path - The destination you'd like to download the directory to. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)
bool $overwrite = false - Whether to overwrite the local files if they exist, or not. if not set the directory will not be overwritten.
int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. if not specified, the class will try to determine the mode from the file extensions (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by getRecursive. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Given remote-path '$remote_path' seems not to be a directory.	The path you specified on the FTP sever seems not to be a valid directory node.	Maybe your path does not end with '/' or the directory does not exist.
Given local-path '$local_path' seems not to be a directory.	The path you specified on the local host seems not to be a valid directory node.	Maybe your path does not end with '/' or the directory does not exist.
Could not create dir '$local_path'.	The given directory could not be created.	Check your permissions on the source-directory.
Could not create dir '$local_path'.	The given directory could not be created.	Check your permissions on the source-directory.

Note

This function can not be called statically.

Example

Using getRecursive()

<?php
     
    var_dump($test->getRecursive('foo/', '/tmp/foo/', true));
    
?>

Net_FTP::putRecursive()

Net_FTP::putRecursive() – upload a whole directory to the FTP server.

Synopsis

require_once 'Net/FTP.php';

mixed Net_FTP::putrecursive ( string $local_path , string $remote_path , bool $overwrite = false , int $mode = null )

Description

This uploads a whole directory to the FTP server from the computer your script runs on.

Parameter

string $local_path - The source directory you'd like to upload. You can specify this with either an absolute path or a path relative to the scripts directory. (Beware: The script directory is determined by the called script, if you use includes!)
string $remote_path - The path you'd like to upload to. This could either be an absolute or relative path to a directory.
bool $overwrite = false - Whether to overwrite the remote directory if it exists, or not. If not set the directory will not be overwritten.
int $mode = null - This has to be one of the constants FTP_ASCII or FTP_BINARY. If not specified, the class will try to determine the mode from the file extensions (from extensions.ini) or fall back to the standard transfer mode (attribute).

Return value

mixed - true on success, otherwise PEAR::Error.

Throws

Several errors may be returned by putRecursive. The errornumber is unspecific (until now) and will not tell you anything about the errormessage. Possible errors are:

Possible PEAR_Error values
Error message	Description	Solution
Given local-path '$local_path' seems not to be a directory.	The local path you have specified does not seem to be a directory.	Correct the local directory path. (Does it end with '/'?)
Given remote-path '$remote_path' seems not to be a directory.	The remote path you have specified does not seem to be a directory.	Correct the local directory path. (Does it end with '/'?)

Note

This function can not be called statically.

Example

Using putRecursive()

<?php

  var_dump($test->putRecursive('/tmp/foo/', 'foo/', true));

?>

Net_FTP::checkFileExtension()

Net_FTP::checkFileExtension() – check extensions.ini for the transfermode of a specific file.

Synopsis

require_once 'Net/FTP.php';

integer Net_FTP::checkfileextension ( string $filename )

Description

This method checks a given filename for its proper transfermode (using extensions.ini). If the file extension can not be found, the class falls back to the standard transfer mode (attribute).

Parameter

string $filename - The filename to check extension for.

Return value

int - either FTP_ASCII or FTP_BINARY.

Throws

No errors. Always a filetransfermode should be returned.

Note

This function can not be called statically.

Example

Using checkFileExtension()

<?php
     
    var_dump($test->checkfileextension('foo/bar.zip'));
    
?>