306 lines
9.5 KiB
ReStructuredText
306 lines
9.5 KiB
ReStructuredText
#########
|
|
FTP Class
|
|
#########
|
|
|
|
CodeIgniter's FTP Class permits files to be transferred to a remote
|
|
server. Remote files can also be moved, renamed, and deleted. The FTP
|
|
class also includes a "mirroring" function that permits an entire local
|
|
directory to be recreated remotely via FTP.
|
|
|
|
.. note:: SFTP and SSL FTP protocols are not supported, only standard
|
|
FTP.
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
.. raw:: html
|
|
|
|
<div class="custom-index container"></div>
|
|
|
|
**************************
|
|
Working with the FTP Class
|
|
**************************
|
|
|
|
Initializing the Class
|
|
======================
|
|
|
|
Like most other classes in CodeIgniter, the FTP class is initialized in
|
|
your controller using the $this->load->library function::
|
|
|
|
$this->load->library('ftp');
|
|
|
|
Once loaded, the FTP object will be available using: $this->ftp
|
|
|
|
Usage Examples
|
|
==============
|
|
|
|
In this example a connection is opened to the FTP server, and a local
|
|
file is read and uploaded in ASCII mode. The file permissions are set to
|
|
755.
|
|
::
|
|
|
|
$this->load->library('ftp');
|
|
|
|
$config['hostname'] = 'ftp.example.com';
|
|
$config['username'] = 'your-username';
|
|
$config['password'] = 'your-password';
|
|
$config['debug'] = TRUE;
|
|
|
|
$this->ftp->connect($config);
|
|
|
|
$this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775);
|
|
|
|
$this->ftp->close();
|
|
|
|
In this example a list of files is retrieved from the server.
|
|
::
|
|
|
|
$this->load->library('ftp');
|
|
|
|
$config['hostname'] = 'ftp.example.com';
|
|
$config['username'] = 'your-username';
|
|
$config['password'] = 'your-password';
|
|
$config['debug'] = TRUE;
|
|
|
|
$this->ftp->connect($config);
|
|
|
|
$list = $this->ftp->list_files('/public_html/');
|
|
|
|
print_r($list);
|
|
|
|
$this->ftp->close();
|
|
|
|
In this example a local directory is mirrored on the server.
|
|
::
|
|
|
|
$this->load->library('ftp');
|
|
|
|
$config['hostname'] = 'ftp.example.com';
|
|
$config['username'] = 'your-username';
|
|
$config['password'] = 'your-password';
|
|
$config['debug'] = TRUE;
|
|
|
|
$this->ftp->connect($config);
|
|
|
|
$this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/');
|
|
|
|
$this->ftp->close();
|
|
|
|
***************
|
|
Class Reference
|
|
***************
|
|
|
|
.. php:class:: CI_FTP
|
|
|
|
.. php:method:: connect([$config = array()])
|
|
|
|
:param array $config: Connection values
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Connects and logs into to the FTP server. Connection preferences are set
|
|
by passing an array to the function, or you can store them in a config
|
|
file.
|
|
|
|
Here is an example showing how you set preferences manually::
|
|
|
|
$this->load->library('ftp');
|
|
|
|
$config['hostname'] = 'ftp.example.com';
|
|
$config['username'] = 'your-username';
|
|
$config['password'] = 'your-password';
|
|
$config['port'] = 21;
|
|
$config['passive'] = FALSE;
|
|
$config['debug'] = TRUE;
|
|
|
|
$this->ftp->connect($config);
|
|
|
|
**Setting FTP Preferences in a Config File**
|
|
|
|
If you prefer you can store your FTP preferences in a config file.
|
|
Simply create a new file called the ftp.php, add the $config array in
|
|
that file. Then save the file at *application/config/ftp.php* and it
|
|
will be used automatically.
|
|
|
|
**Available connection options**
|
|
|
|
============== =============== =============================================================================
|
|
Option name Default value Description
|
|
============== =============== =============================================================================
|
|
**hostname** n/a FTP hostname (usually something like: ftp.example.com)
|
|
**username** n/a FTP username
|
|
**password** n/a FTP password
|
|
**port** 21 FTP server port number
|
|
**debug** FALSE TRUE/FALSE (boolean): Whether to enable debugging to display error messages
|
|
**passive** TRUE TRUE/FALSE (boolean): Whether to use passive mode
|
|
============== =============== =============================================================================
|
|
|
|
.. php:method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]])
|
|
|
|
:param string $locpath: Local file path
|
|
:param string $rempath: Remote file path
|
|
:param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii')
|
|
:param int $permissions: File permissions (octal)
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Uploads a file to your server. You must supply the local path and the
|
|
remote path, and you can optionally set the mode and permissions.
|
|
Example::
|
|
|
|
$this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775);
|
|
|
|
If 'auto' mode is used it will base the mode on the file extension of the source file.
|
|
|
|
If set, permissions have to be passed as an octal value.
|
|
|
|
.. php:method:: download($rempath, $locpath[, $mode = 'auto'])
|
|
|
|
:param string $rempath: Remote file path
|
|
:param string $locpath: Local file path
|
|
:param string $mode: FTP mode, defaults to 'auto' (options are: 'auto', 'binary', 'ascii')
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Downloads a file from your server. You must supply the remote path and
|
|
the local path, and you can optionally set the mode. Example::
|
|
|
|
$this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii');
|
|
|
|
If 'auto' mode is used it will base the mode on the file extension of the source file.
|
|
|
|
Returns FALSE if the download does not execute successfully
|
|
(including if PHP does not have permission to write the local file).
|
|
|
|
.. php:method:: rename($old_file, $new_file[, $move = FALSE])
|
|
|
|
:param string $old_file: Old file name
|
|
:param string $new_file: New file name
|
|
:param bool $move: Whether a move is being performed
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Permits you to rename a file. Supply the source file name/path and the new file name/path.
|
|
::
|
|
|
|
// Renames green.html to blue.html
|
|
$this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html');
|
|
|
|
.. php:method:: move($old_file, $new_file)
|
|
|
|
:param string $old_file: Old file name
|
|
:param string $new_file: New file name
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Lets you move a file. Supply the source and destination paths::
|
|
|
|
// Moves blog.html from "joe" to "fred"
|
|
$this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html');
|
|
|
|
.. note:: If the destination file name is different the file will be renamed.
|
|
|
|
.. php:method:: delete_file($filepath)
|
|
|
|
:param string $filepath: Path to file to delete
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Lets you delete a file. Supply the source path with the file name.
|
|
::
|
|
|
|
$this->ftp->delete_file('/public_html/joe/blog.html');
|
|
|
|
.. php:method:: delete_dir($filepath)
|
|
|
|
:param string $filepath: Path to directory to delete
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Lets you delete a directory and everything it contains. Supply the
|
|
source path to the directory with a trailing slash.
|
|
|
|
.. important:: Be VERY careful with this method!
|
|
It will recursively delete **everything** within the supplied path,
|
|
including sub-folders and all files. Make absolutely sure your path
|
|
is correct. Try using ``list_files()`` first to verify that your path is correct.
|
|
|
|
::
|
|
|
|
$this->ftp->delete_dir('/public_html/path/to/folder/');
|
|
|
|
.. php:method:: list_files([$path = '.'])
|
|
|
|
:param string $path: Directory path
|
|
:returns: An array list of files or FALSE on failure
|
|
:rtype: array
|
|
|
|
Permits you to retrieve a list of files on your server returned as an
|
|
array. You must supply the path to the desired directory.
|
|
::
|
|
|
|
$list = $this->ftp->list_files('/public_html/');
|
|
print_r($list);
|
|
|
|
.. php:method:: mirror($locpath, $rempath)
|
|
|
|
:param string $locpath: Local path
|
|
:param string $rempath: Remote path
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
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. You must supply a source path and a destination path::
|
|
|
|
$this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/');
|
|
|
|
.. php:method:: mkdir($path[, $permissions = NULL])
|
|
|
|
:param string $path: Path to directory to create
|
|
:param int $permissions: Permissions (octal)
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Lets you create a directory on your server. Supply the path ending in
|
|
the folder name you wish to create, with a trailing slash.
|
|
|
|
Permissions can be set by passing an octal value in the second parameter.
|
|
::
|
|
|
|
// Creates a folder named "bar"
|
|
$this->ftp->mkdir('/public_html/foo/bar/', 0755);
|
|
|
|
.. php:method:: chmod($path, $perm)
|
|
|
|
:param string $path: Path to alter permissions for
|
|
:param int $perm: Permissions (octal)
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Permits you to set file permissions. Supply the path to the file or
|
|
directory you wish to alter permissions on::
|
|
|
|
// Chmod "bar" to 755
|
|
$this->ftp->chmod('/public_html/foo/bar/', 0755);
|
|
|
|
.. php:method:: changedir($path[, $suppress_debug = FALSE])
|
|
|
|
:param string $path: Directory path
|
|
:param bool $suppress_debug: Whether to turn off debug messages for this command
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Changes the current working directory to the specified path.
|
|
|
|
The ``$suppress_debug`` parameter is useful in case you want to use this method
|
|
as an ``is_dir()`` alternative for FTP.
|
|
|
|
.. php:method:: close()
|
|
|
|
:returns: TRUE on success, FALSE on failure
|
|
:rtype: bool
|
|
|
|
Closes the connection to your server. It's recommended that you use this
|
|
when you are finished uploading. |