Ftp Class

The FTP class allows you to upload, download, move and mirror files with remote servers over the FTP protocol.

Configuration

The FTP class is configured through the fuel/core/config/ftp.php configuration file. It is already populated with a default configuration group. You can override this configuration and add new groups by copying this config file to your application config directory, and modify that file as needed.

The following configuration settings can be defined:

Param Type Default Description
hostname string 
'localhost'
 IP or domain name of the FTP server to connect with.
username string 
''
 Name of the user to connect with, if login is required.
password string 
''
 Name of the password to connect with, if login is required.
timeout integer 
90
 Timeout in seconds for all subsequent network operations.
port integer 
21
 The port number your FTP server responds to. Most servers use 21.
passive boolean 
true
 Whether to use passive mode. Passive is set automatically by default.
ssl_mode boolean 
false
 Use FTPS mode which is slightly more secure than usual FTP. (Note: this is not SFTP).
debug boolean 
false
 Whether to enable debugging to display error messages.

All configuration values are optional. If you omit one, the default value as given above will be used.
This is also the case when you pass a array with custom configuration values when you call forge().

forge($config = 'default', $connect = true)

The forge method is used to create a new instance of the FTP class and can either reference a different config group or be passed an array of configuration options.

Static Yes
Parameters
Param Default Description
$config 
'default'
 The name of the config group to use, or a configuration array.
$connect 
true
 Automatically connect to this server.
Returns Ftp object
Example 
// Connect to the default server
$ftp = Ftp::forge();

// Connect to a predefined server defined in config/ftp.php
$ftp2 = Ftp::forge('image-storage');

// Connect to a server on-the-fly
$ftp3 = Ftp::forge(array(
	'hostname' => 'fuelphp.com',
	'username' => '',
	'password' => '',
	'timeout'  => 90,
	'port'     => 21,
	'passive'  => true,
	'ssl_mode' => false,
	'debug'    => false
));

if ($ftp3->delete_dir('/') === true)
{
	exit('The world owes you a debt of gratitude');
}
else
{
	exit('You tried and that is the main thing.');
}

connect()

The connect method allows you to manually connect to an FTP resource. You only use this method if you didn't automatically connect when you forge()'d the ftp object.

Static No
Parameters None
Returns the current FTP object, for chaining
Example 
// create an ftp object, but don't connect
$ftp = Ftp::forge(array(
	'hostname' => 'ftp.example.com',
	'username' => '',
	'password' => '',
	'timeout'  => 90,
	'port'     => 21,
	'passive'  => true,
	'ssl_mode' => false,
	'debug'    => false
), false);

// do some stuff here

// now connect to the server
$ftp->connect();

change_dir($path = '')

The change_dir changes the "current directory".

Static No
Parameters
Param Default Description
$path 
''
 Remote path to move to.
Returns boolean
Example 
// Move to /user/phil/public_html/some/path/
$ftp->change_dir('/public_html/some/path/');

mkdir($path, $permissions = null)

The mkdir method is used to create a new directory on the remote server.

Static No
Parameters
Param Default Description
$path Required Remote directory to create.
$permissions 
null
 If set the permissions will be applied to the directory.
Returns boolean
Example 
// Make a write-able uploads folder
$ftp->mkdir('/public_html/uploads/', 0777);

upload($local_path, $remote_path, $mode = 'auto', $permissions = null)

Upload a file or directory from the local server to the remote server.

Static No
Parameters
Param Default Description
$local_path Required Local server path.
$remote_path Required Remote server path.
$mode 
'auto'
 Options are ascii, binary, and auto (the default). If auto is used it will base the mode on the file extension of the source file.
$permissions 
null
 If set the permissions will be applied to the directory.
Returns boolean
Example 
// Upload myfile.html
$ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775);

download($remote_path, $local_path, $mode = 'auto')

Download a file or directory from the remote server to the local server.

Static No
Parameters
Param Default Description
$remote_path Required Remote server path.
$local_path Required Local server path.
$mode 
'auto'
 Options are ascii, binary, and auto (the default). If auto is used it will base the mode on the file extension of the source file.
Returns boolean
Example 
// Download myotherfile.html
$ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii');

rename($old_file, $new_file, $move = false)

Move or rename a file on the remote server.

Static No
Parameters
Param Default Description
$old_file Required File to be renamed or moved.
$new_file Required File to move or rename to.
$move 
false
 'true' if this is move, 'false' if it is a rename. This flag is used for debug error messages only.
Returns boolean
Example 
// connect to an FTP server
$ftp = Ftp::forge($config);

// rename the file
$ftp->rename('/path/to/oldfile.txt', '/path/to/newfile.txt', false);

// close the connection
$ftp->close();

move($old_file, $new_file)

Alias for rename(), with the $move flag set to true.

delete_file($filepath)

Deletes a file from the remote server.

Static No
Parameters
Param Default Description
$filepath Required File to be deleted.
Returns boolean
Example 
// connect to an FTP server
$ftp = Ftp::forge($config);

// delete a file
if ( ! $ftp->delete_file('/path/to/file.txt'))
{
	// delete failed
}

// close the connection
$ftp->close();

delete_dir($filepath)

Deletes a folder and recursively anything in it from the remote server.

Static No
Parameters
Param Default Description
$filepath Required File to be deleted.
Returns boolean
Example 
// connect to an FTP server
$ftp = Ftp::forge($config);

// delete a folder with all its contents
if ( ! $ftp->delete_dir('/path/to/folder'))
{
	// delete failed
}

// close the connection
$ftp->close();

chmod($path, $perm)

Change the permissions of a file on the remote server.

Static No
Parameters
Param Default Description
$path Required File to change the permissions on.
$perm Required Permissions, defined unix style, as an octal value.
Returns boolean
Example 
// connect to an FTP server
$ftp = Ftp::forge($config);

// make the file writeable for all
if ( ! $ftp->chmod('/path/to/file.txt', 0666))
{
	// changing permissions failed
}

// close the connection
$ftp->close();

list_files($path = '.')

Lists all files in the given path on the remote server.

Static No
Parameters
Param Default Description
$path 
'.'
 Remote server path. Defaults to current directory.
Returns array
Example 
// connect to an FTP server
$ftp = Ftp::forge($config);

// make the file writeable for all
if ( $files = $ftp->list_files('/path/to/files') === false)
{
	// listing failed
}
else
{
	/* might return something like
	   $files = array(3) {
		  [0]=>
		  string(11) "public_html"
		  [1]=>
		  string(10) "public_ftp"
		  [2]=>
		  string(3) "www"
	*/
  }

// close the connection
$ftp->close();

mirror($local_path, $remote_path)

Recursively reads a local folder and everything it contains (including sub-folders) and creates a mirror via FTP based on it. Whatever the directory structure of the original file path will be recreated on the server.

Static No
Parameters
Param Default Description
$local_path 
'default'
 Local server path.
$remote_path 
true
 Remote server path.
Returns boolean
Example 
$ftp = Ftp::forge();

$ftp->connect($config);

$ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/');

$ftp->close();

close()

The close method closes an open ftp connection to a remote server created by forge() or connect().

Static No
Parameters None
Returns boolean
Example 
// close a connection
if ( ! $ftp->close())
{
	// connection wasn't open
}