From b799a0b3f09238fe46892b811025e7bf2ac81b19 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Tue, 6 Aug 2013 15:38:21 -0700 Subject: Partial update to FTP docs --- user_guide_src/source/libraries/ftp.rst | 87 +++++++++++++++++++-------------- 1 file changed, 49 insertions(+), 38 deletions(-) (limited to 'user_guide_src/source/libraries/ftp.rst') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index 05a3fdcc8..fd82590b9 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -10,9 +10,19 @@ directory to be recreated remotely via FTP. .. note:: SFTP and SSL FTP protocols are not supported, only standard FTP. -********************** +.. contents:: + :local: + +.. raw:: html + +
+ +************************** +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:: @@ -79,53 +89,54 @@ In this example a local directory is mirrored on the server. $this->ftp->close(); -****************** -Function Reference -****************** +*************** +Class Reference +*************** -$this->ftp->connect() -===================== +.. class:: CI_FTP -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. + .. method:: connect([$config = array()]) -Here is an example showing how you set preferences manually:: + :param array $config: Connection values + :returns: bool - $this->load->library('ftp'); + 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. - $config['hostname'] = 'ftp.example.com'; - $config['username'] = 'your-username'; - $config['password'] = 'your-password'; - $config['port'] = 21; - $config['passive'] = FALSE; - $config['debug'] = TRUE; + Here is an example showing how you set preferences manually:: - $this->ftp->connect($config); + $this->load->library('ftp'); -Setting FTP Preferences in a Config File -**************************************** + $config['hostname'] = 'ftp.example.com'; + $config['username'] = 'your-username'; + $config['password'] = 'your-password'; + $config['port'] = 21; + $config['passive'] = FALSE; + $config['debug'] = TRUE; -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 config/ftp.php and it will be used -automatically. + $this->ftp->connect($config); -Available connection options -**************************** + **Setting FTP Preferences in a Config File** -- **hostname** - the FTP hostname. Usually something like: - ftp.example.com -- **username** - the FTP username. -- **password** - the FTP password. -- **port** - The port number. Set to 21 by default. -- **debug** - TRUE/FALSE (boolean). Whether to enable debugging to - display error messages. -- **passive** - TRUE/FALSE (boolean). Whether to use passive mode. - Passive is set automatically by default. + 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 config/ftp.php and it will be used + automatically. + + **Available connection options** + + ================== =================================== + Option Name Description + ================== =================================== + **hostname** the FTP hostname. Usually something like: ftp.example.com + **username** the FTP username + **password** the FTP password + **port** The port number. Set to 21 by default. + **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. + **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. + ================== =================================== -$this->ftp->upload() -==================== 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. -- cgit v1.2.3-24-g4f1b From eb21ac8e9b85b681bc03b935955b3fbfa9b0db1e Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:27:29 +0200 Subject: [ci skip] Finish updating the FTP class docs --- user_guide_src/source/libraries/ftp.rst | 201 ++++++++++++++++++-------------- 1 file changed, 111 insertions(+), 90 deletions(-) (limited to 'user_guide_src/source/libraries/ftp.rst') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index fd82590b9..1b1a45e36 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -37,7 +37,6 @@ 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'); @@ -54,7 +53,6 @@ file is read and uploaded in ASCII mode. The file permissions are set to $this->ftp->close(); In this example a list of files is retrieved from the server. - :: $this->load->library('ftp'); @@ -73,7 +71,6 @@ In this example a list of files is retrieved from the server. $this->ftp->close(); In this example a local directory is mirrored on the server. - :: $this->load->library('ftp'); @@ -121,140 +118,164 @@ Class Reference 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 config/ftp.php and it will be used - automatically. + that file. Then save the file at *application/config/ftp.php* and it + will be used automatically. **Available connection options** ================== =================================== - Option Name Description + Option Name Description ================== =================================== - **hostname** the FTP hostname. Usually something like: ftp.example.com - **username** the FTP username - **password** the FTP password - **port** The port number. Set to 21 by default. - **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. - **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. + **hostname** the FTP hostname. Usually something like: ftp.example.com + **username** the FTP username + **password** the FTP password + **port** The port number. Set to 21 by default. + **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. + **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. ================== =================================== + .. method:: upload($locpath, $rempath[, $mode = 'auto'[, $permissions = NULL]]) -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:: + :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: bool - $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); + 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:: -**Mode 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. + $this->ftp->upload('/local/path/to/myfile.html', '/public_html/myfile.html', 'ascii', 0775); -If set, permissions have to be passed as an octal value. + If 'auto' mode is used it will base the mode on the file extension of the source file. -$this->ftp->download() -====================== + If set, permissions have to be passed as an octal value. -Downloads a file from your server. You must supply the remote path and -the local path, and you can optionally set the mode. Example:: + .. method:: download($rempath, $locpath[, $mode = 'auto']) - $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); + :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: bool -**Mode 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. + Downloads a file from your server. You must supply the remote path and + the local path, and you can optionally set the mode. Example:: -Returns FALSE if the download does not execute successfully (including -if PHP does not have permission to write the local file) + $this->ftp->download('/public_html/myfile.html', '/local/path/to/myfile.html', 'ascii'); -$this->ftp->rename() -==================== + If 'auto' mode is used it will base the mode on the file extension of the source file. -Permits you to rename a file. Supply the source file name/path and the -new file name/path. + Returns FALSE if the download does not execute successfully (including if PHP does not have permission to write the local file). -:: + .. method:: rename($old_file, $new_file, $move = FALSE) - // Renames green.html to blue.html - $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); + :param string $old_file: Old file name + :param string $new_file: New file name + :param bool $move: Whether a move is being performed + :returns: bool -$this->ftp->move() -================== + Permits you to rename a file. Supply the source file name/path and the new file name/path. + :: -Lets you move a file. Supply the source and destination paths:: + // Renames green.html to blue.html + $this->ftp->rename('/public_html/foo/green.html', '/public_html/foo/blue.html'); - // Moves blog.html from "joe" to "fred" - $this->ftp->move('/public_html/joe/blog.html', '/public_html/fred/blog.html'); + .. method:: move($old_file, $new_file) -Note: if the destination file name is different the file will be -renamed. + :param string $old_file: Old file name + :param string $new_file: New file name + :returns: bool -$this->ftp->delete_file() -========================== + Lets you move a file. Supply the source and destination paths:: -Lets you delete a file. Supply the source path with the file name. + // 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. - $this->ftp->delete_file('/public_html/joe/blog.html'); + .. method:: delete_file($filepath) -$this->ftp->delete_dir() -========================= + :param string $filepath: Path to file to delete + :returns: bool -Lets you delete a directory and everything it contains. Supply the -source path to the directory with a trailing slash. + Lets you delete a file. Supply the source path with the file name. + :: -**Important** Be VERY careful with this function. It will recursively -delete **everything** within the supplied path, including sub-folders -and all files. Make absolutely sure your path is correct. Try using the -list_files() function first to verify that your path is correct. + $this->ftp->delete_file('/public_html/joe/blog.html'); -:: + .. method:: delete_dir($filepath) - $this->ftp->delete_dir('/public_html/path/to/folder/'); + :param string $filepath: Path to directory to delete + :returns: bool -$this->ftp->list_files() -========================= + Lets you delete a directory and everything it contains. Supply the + source path to the directory with a trailing slash. -Permits you to retrieve a list of files on your server returned as an -array. You must supply the path to the desired directory. + .. 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. -:: + :: - $list = $this->ftp->list_files('/public_html/'); + $this->ftp->delete_dir('/public_html/path/to/folder/'); - print_r($list); + .. method:: list_files([$path = '.']) -$this->ftp->mirror() -==================== + :param string $path: Directory path + :returns: array or FALSE on failure -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:: + Permits you to retrieve a list of files on your server returned as an + array. You must supply the path to the desired directory. + :: - $this->ftp->mirror('/path/to/myfolder/', '/public_html/myfolder/'); + $list = $this->ftp->list_files('/public_html/'); + print_r($list); -$this->ftp->mkdir() -=================== + .. method:: mirror($locpath, $rempath) -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 passed an octal value in the second parameter (if you are -running PHP 5). + :param string $locpath: Local path + :param string $rempath: Remote path + :returns: 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/'); + + .. method:: mkdir($path[, $permissions = NULL]) + + :param string $path: Path to directory to create + :param int $permissions: Permissions (octal) + :returns: 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. - // Creates a folder named "bar" - $this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE); + Permissions can be set by passing an octal value in the second parameter. + :: -$this->ftp->chmod() -=================== + // Creates a folder named "bar" + $this->ftp->mkdir('/public_html/foo/bar/', DIR_WRITE_MODE); -Permits you to set file permissions. Supply the path to the file or -folder you wish to alter permissions on:: + .. method:: chmod($path, $perm) + + :param string $path: Path to alter permissions for + :param int $perm: Permissions (octal) + :returns: bool - // Chmod "bar" to 777 - $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + Permits you to set file permissions. Supply the path to the file or + directory you wish to alter permissions on:: -$this->ftp->close(); -==================== + // Chmod "bar" to 777 + $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + + .. method:: close() + + :returns: bool -Closes the connection to your server. It's recommended that you use this -when you are finished uploading. + Closes the connection to your server. It's recommended that you use this + when you are finished uploading. \ No newline at end of file -- cgit v1.2.3-24-g4f1b From a322989d6e24f381df56dea2428c29d4d185d6b5 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Fri, 3 Jan 2014 17:35:52 +0200 Subject: [ci skip] Add missing docs for CI_FTP::changedir() --- user_guide_src/source/libraries/ftp.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'user_guide_src/source/libraries/ftp.rst') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index 1b1a45e36..c587869db 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -273,6 +273,17 @@ Class Reference // Chmod "bar" to 777 $this->ftp->chmod('/public_html/foo/bar/', DIR_WRITE_MODE); + .. 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: 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. + .. method:: close() :returns: bool -- cgit v1.2.3-24-g4f1b From 28c2c975b118016d07212ed8e7c22ff280309f82 Mon Sep 17 00:00:00 2001 From: Andrey Andreev Date: Sat, 8 Feb 2014 04:27:48 +0200 Subject: [ci skip] Add return types to library docs --- user_guide_src/source/libraries/ftp.rst | 112 ++++++++++++++++++-------------- 1 file changed, 63 insertions(+), 49 deletions(-) (limited to 'user_guide_src/source/libraries/ftp.rst') diff --git a/user_guide_src/source/libraries/ftp.rst b/user_guide_src/source/libraries/ftp.rst index c587869db..dd9440443 100644 --- a/user_guide_src/source/libraries/ftp.rst +++ b/user_guide_src/source/libraries/ftp.rst @@ -94,8 +94,9 @@ Class Reference .. method:: connect([$config = array()]) - :param array $config: Connection values - :returns: bool + :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 @@ -123,24 +124,25 @@ Class Reference **Available connection options** - ================== =================================== - Option Name Description - ================== =================================== - **hostname** the FTP hostname. Usually something like: ftp.example.com - **username** the FTP username - **password** the FTP password - **port** The port number. Set to 21 by default. - **debug** TRUE/FALSE (boolean). Whether to enable debugging to display error messages. - **passive** TRUE/FALSE (boolean). Whether to use passive mode. Passive is set automatically by default. - ================== =================================== + ============== =============== ============================================================================= + 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 + ============== =============== ============================================================================= .. 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: bool + :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. @@ -154,10 +156,11 @@ Class Reference .. 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: bool + :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:: @@ -166,14 +169,16 @@ Class Reference 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). + Returns FALSE if the download does not execute successfully + (including if PHP does not have permission to write the local file). - .. method:: rename($old_file, $new_file, $move = FALSE) + .. 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: bool + :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. :: @@ -183,9 +188,10 @@ Class Reference .. method:: move($old_file, $new_file) - :param string $old_file: Old file name - :param string $new_file: New file name - :returns: bool + :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:: @@ -196,8 +202,9 @@ Class Reference .. method:: delete_file($filepath) - :param string $filepath: Path to file to delete - :returns: bool + :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. :: @@ -206,8 +213,9 @@ Class Reference .. method:: delete_dir($filepath) - :param string $filepath: Path to directory to delete - :returns: bool + :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. @@ -223,8 +231,9 @@ Class Reference .. method:: list_files([$path = '.']) - :param string $path: Directory path - :returns: array or FALSE on failure + :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. @@ -235,9 +244,10 @@ Class Reference .. method:: mirror($locpath, $rempath) - :param string $locpath: Local path - :param string $rempath: Remote path - :returns: bool + :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 @@ -248,9 +258,10 @@ Class Reference .. method:: mkdir($path[, $permissions = NULL]) - :param string $path: Path to directory to create - :param int $permissions: Permissions (octal) - :returns: bool + :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. @@ -263,9 +274,10 @@ Class Reference .. method:: chmod($path, $perm) - :param string $path: Path to alter permissions for - :param int $perm: Permissions (octal) - :returns: bool + :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:: @@ -275,9 +287,10 @@ Class Reference .. 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: bool + :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. @@ -286,7 +299,8 @@ Class Reference .. method:: close() - :returns: bool + :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. \ No newline at end of file -- cgit v1.2.3-24-g4f1b