Transferring files over FTP
resource ftp_connect ( string host [, int port [, int timeout]])
bool ftp_login ( resource ftp_stream, string username, string password)
bool ftp_pasv ( resource ftp_stream, bool enable_passive_mode)
bool ftp_chdir ( resource ftp_stream, string directory)
bool ftp_get ( resource ftp_stream, string local_file, string remote_file, int mode [, int resume_position])
void ftp_close ( resource ftp_stream)
The File Transfer Protocol is a common way for servers to make files publicly accessible for others to login and download. Like HTTP, PHP makes accessing FTP easy by allowing you to use FTP addresses in fopen() calls, however this method is not very flexible.
For more advanced uses, PHP has a special set of functions that are designed to open up the full flexibility of the FTP protocol without becoming overly complicated - by using functions such as ftp_connect(), ftp_get(), and ftp_put(), you can make PHP connect to, and interact with, FTP servers.
Author's Note: The FTP functions are excellent for manipulating live FTP connections, however if you just want to connect and perform a single action, consider using the Curl extension.
Take a look at this script:
$conn = ftp_connect("ftp.gnu.org");
ftp_login($conn, "anonymous", "firstname.lastname@example.org");
$files = ftp_nlist($conn, ".");
$filetoget = array_pop($files);
ftp_get($conn, $filetoget, $filetoget, FTP_BINARY);
There are quite a few new functions in there, so we need to break it down into easier-to-understand chunks. Firstly, note that all the FTP functions use the return value from ftp_connect(), as is usual for PHP. The ftp_connect() function itself takes the host to connect to as its parameter, returning the connection resource that you need to store away. Before you try executing any commands on the server, you need to use ftp_login() and, optionally ftp_pasv() also.
Ftp_login() function takes the connection resource as its first parameter, plus a username and password as parameters two and three - connecting to a public server like the GNU FTP archive means that we can use "anonymous" and an email address to connect. The ftp_pasv() function enables you to switch on or switch off passive FTP mode, depending on the value of the second parameter - you will need this enabled if you are behind a firewall.
Author's Note: The FTP protocol dictates that two channels are opened - one where you connect to the server, and one where the server connects to you. This behaviour is banned behind many firewalls because an outside computer connecting to an inside computer seemingly randomly appears to be an attack. As such, the passive FTP system was developed, which is where the client connects twice to the server in order to bypass problems with firewalls. Note that there is no harm in using passive-mode FTP even if you are not behind a firewall - in fact, doing so is recommended because it means your code is more portable.
Moving on, ftp_chdir() changes the working directory of the FTP connection to the directory specified by the second parameter. This can be either a relative path, for example "music", or an absolute path as used in the example, such as "/gnu/bash". The ftp_nlist() function returns a list of all files in a given directory, and takes two parameters - the connection to use, and the directory to check. In the example, "." is specified as parameter two, which means "the current directory", so ftp_nlist() will return a list of the files in the current directory. Note that the function returns the files in an array as sent by the server - this is not likely to be alphabetically sorted.
Shuffle() is used to randomise the contents of the file list, then array_pop() is used to grab the name of a file to download. This is then passed to ftp_get() as parameters two and three, along with $conn and FTP_BINARY as parameters one and four.
Ftp_get() downloads a file from the server to your local system, and takes four parameters: the connection to use, the name you want to call the file you download, the name of the file you want to grab, and the transfer type. FTP_BINARY means transfer the file as binary, which is safe for all data types, but you can also use FTP_ASCII for text files - FTP_BINARY is recommended for all data types, though.
Calling ftp_get() saves the file specified in parameter three to the file specified in parameter two - if you don't have write permissions to the file specified by parameter two, or if the drive is full, the call will return false to show failure, otherwise it will return true.
Finally, ftp_close() is used to close the FTP connection opened earlier. Note that most FTP servers have connection limits - the number of open connections they allow at any one given moment. As a result, it is best to close your connections as soon as you are done with them, because other people might be waiting to get on.
Next chapter: Other helpful FTP functions >>
Previous chapter: Mail management
Home: Table of Contents