# FTP
Works with SFTP/FTP servers.
In order to test the contents of a specific file stored on any remote FTP/SFTP system
this module downloads a temporary file to the local system. The temporary directory is
defined by default as ```tests/_data``` to specify a different directory set the tmp config
option to your chosen path.
Don't forget to create the folder and ensure its writable.
Supported and tested FTP types are:
* FTP
* SFTP
Connection uses php build in FTP client for FTP,
connection to SFTP uses [phpseclib](http://phpseclib.sourceforge.net/) pulled in using composer.
For SFTP, add [phpseclib](http://phpseclib.sourceforge.net/) to require list.
```
"require": {
"phpseclib/phpseclib": "0.3.6"
}
```
## Status
* Maintainer: **nathanmac**
* Stability:
- FTP: **stable**
- SFTP: **stable**
* Contact: nathan.macnamara@outlook.com
## Config
* type: ftp - type of connection ftp/sftp (defaults to ftp).
* host *required* - hostname/ip address of the ftp server.
* port: 21 - port number for the ftp server
* timeout: 90 - timeout settings for connecting the ftp server.
* user: anonymous - user to access ftp server, defaults to anonymous authentication.
* password - password, defaults to empty for anonymous.
* key - path to RSA key for sftp.
* tmp - path to local directory for storing tmp files.
* passive: true - Turns on or off passive mode (FTP only)
* cleanup: true - remove tmp files from local directory on completion.
### Example
#### Example (FTP)
modules:
enabled: [FTP]
config:
FTP:
type: ftp
host: '127.0.0.1'
port: 21
timeout: 120
user: 'root'
password: 'root'
key: ~/.ssh/id_rsa
tmp: 'tests/_data/ftp'
passive: true
cleanup: false
#### Example (SFTP)
modules:
enabled: [FTP]
config:
FTP:
type: sftp
host: '127.0.0.1'
port: 22
timeout: 120
user: 'root'
password: 'root'
key: ''
tmp: 'tests/_data/ftp'
cleanup: false
This module extends the Filesystem module, file contents methods are inherited from this module.
## Actions
### amInPath
Enters a directory on the ftp system - FTP root directory is used by default
* `param` $path
### cleanDir
Erases directory contents on the FTP/SFTP server
``` php
<?php
$I->cleanDir('logs');
?>
```
* `param` $dirname
### copyDir
Currently not supported in this module, overwrite inherited method
* `param` $src
* `param` $dst
### deleteDir
Deletes directory with all subdirectories on the remote FTP/SFTP server
``` php
<?php
$I->deleteDir('vendor');
?>
```
* `param` $dirname
### deleteFile
Deletes a file on the remote FTP/SFTP system
``` php
<?php
$I->deleteFile('composer.lock');
?>
```
* `param` $filename
### deleteThisFile
Deletes a file
### dontSeeFileFound
Checks if file does not exist in path on the remote FTP/SFTP system
* `param` $filename
* `param string` $path
### dontSeeFileFoundMatches
Checks if file does not exist in path on the remote FTP/SFTP system, using regular expression as filename.
DOES NOT OPEN the file when it's exists
* `param` $regex
* `param string` $path
### dontSeeInThisFile
Checks If opened file doesn't contain `text` in it
``` php
<?php
$I->openFile('composer.json');
$I->dontSeeInThisFile('codeception/codeception');
?>
```
* `param string` $text
### grabDirectory
Grabber method to return current working directory
```php
<?php
$pwd = $I->grabDirectory();
?>
```
* `return` string
### grabFileCount
Grabber method for returning file/folders count in directory
```php
<?php
$count = $I->grabFileCount();
$count = $I->grabFileCount('TEST', false); // Include . .. .thumbs.db
?>
```
* `param string` $path
* `param bool` $ignore - suppress '.', '..' and '.thumbs.db'
* `return` int
### grabFileList
Grabber method for returning file/folders listing in an array
```php
<?php
$files = $I->grabFileList();
$count = $I->grabFileList('TEST', false); // Include . .. .thumbs.db
?>
```
* `param string` $path
* `param bool` $ignore - suppress '.', '..' and '.thumbs.db'
* `return` array
### grabFileModified
Grabber method to return last modified timestamp
```php
<?php
$time = $I->grabFileModified('test.txt');
?>
```
* `param` $filename
* `return` bool
### grabFileSize
Grabber method to return file size
```php
<?php
$size = $I->grabFileSize('test.txt');
?>
```
* `param` $filename
* `return` bool
### loginAs
Change the logged in user mid-way through your test, this closes the
current connection to the server and initialises and new connection.
On initiation of this modules you are automatically logged into
the server using the specified config options or defaulted
to anonymous user if not provided.
``` php
<?php
$I->loginAs('user','password');
?>
```
* `param String` $user
* `param String` $password
### makeDir
Create a directory on the server
``` php
<?php
$I->makeDir('vendor');
?>
```
* `param` $dirname
### openFile
Opens a file (downloads from the remote FTP/SFTP system to a tmp directory for processing)
and stores it's content.
Usage:
``` php
<?php
$I->openFile('composer.json');
$I->seeInThisFile('codeception/codeception');
?>
```
* `param` $filename
### renameDir
Rename/Move directory on the FTP/SFTP server
``` php
<?php
$I->renameDir('vendor', 'vendor_old');
?>
```
* `param` $dirname
* `param` $rename
### renameFile
Rename/Move file on the FTP/SFTP server
``` php
<?php
$I->renameFile('composer.lock', 'composer_old.lock');
?>
```
* `param` $filename
* `param` $rename
### seeFileContentsEqual
Checks the strict matching of file contents.
Unlike `seeInThisFile` will fail if file has something more than expected lines.
Better to use with HEREDOC strings.
Matching is done after removing "\r" chars from file content.
``` php
<?php
$I->openFile('process.pid');
$I->seeFileContentsEqual('3192');
?>
```
* `param string` $text
### seeFileFound
Checks if file exists in path on the remote FTP/SFTP system.
DOES NOT OPEN the file when it's exists
``` php
<?php
$I->seeFileFound('UserModel.php','app/models');
?>
```
* `param` $filename
* `param string` $path
### seeFileFoundMatches
Checks if file exists in path on the remote FTP/SFTP system, using regular expression as filename.
DOES NOT OPEN the file when it's exists
``` php
<?php
$I->seeFileFoundMatches('/^UserModel_([0-9]{6}).php$/','app/models');
?>
```
* `param` $regex
* `param string` $path
### seeInThisFile
Checks If opened file has `text` in it.
Usage:
``` php
<?php
$I->openFile('composer.json');
$I->seeInThisFile('codeception/codeception');
?>
```
* `param string` $text
### seeNumberNewLines
Checks If opened file has the `number` of new lines.
Usage:
``` php
<?php
$I->openFile('composer.json');
$I->seeNumberNewLines(5);
?>
```
* `param int` $number New lines
### seeThisFileMatches
Checks that contents of currently opened file matches $regex
* `param string` $regex
### writeToFile
Saves contents to tmp file and uploads the FTP/SFTP system.
Overwrites current file on server if exists.
``` php
<?php
$I->writeToFile('composer.json', 'some data here');
?>
```
* `param` $filename
* `param` $contents
<p> </p><div class="alert alert-warning">Module reference is taken from the source code. <a href="https://github.com/Codeception/Codeception/tree/2.5/src/Codeception/Module/FTP.php">Help us to improve documentation. Edit module reference</a></div>