XXXIX. FTP Functions

Introduction

The functions in this extension implement client access to file servers speaking the File Transfer Protocol (FTP) as defined in http://www.faqs.org/rfcs/rfc959. This extension is meant for detailed access to an FTP server providing a wide range of control to the executing script. If you only wish to read from or write to a file on an FTP server, consider using the ftp:// wrapper with the filesystem functions which provide a simpler and more intuitive interface.

Requirements

No external libraries are needed to build this extension.

Installation

In order to use FTP functions with your PHP configuration, you should add the --enable-ftp option when installing PHP 4 or greater or --with-ftp when using PHP 3.

The windows version of PHP has built in support for this extension. You do not need to load any additional extension in order to use these functions.

Runtime Configuration

This extension has no configuration directives defined in php.ini.

Resource Types

This extension uses one resource type, which is the link identifier of the FTP connection, returned by ftp_connect() or ftp_ssl_connect().

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

FTP_ASCII (integer)
FTP_TEXT (integer)
FTP_BINARY (integer)
FTP_IMAGE (integer)
FTP_TIMEOUT_SEC (integer): See ftp_set_option() for information.

The following constants were introduced in PHP 4.3.0.

FTP_AUTOSEEK (integer): See ftp_set_option() for information.
FTP_AUTORESUME (integer): Automatically determine resume position and start position for GET and PUT requests (only works if FTP_AUTOSEEK is enabled)
FTP_FAILED (integer): Asynchronous transfer has failed
FTP_FINISHED (integer): Asynchronous transfer has finished
FTP_MOREDATA (integer): Asynchronous transfer is still active

Examples

Example 1. FTP example

<?php // set up basic connection $conn_id = ftp_connect($ftp_server); // login with username and password $login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass); // check connection if ((!$conn_id) || (!$login_result)) { echo "FTP connection has failed!"; echo "Attempted to connect to $ftp_server for user $ftp_user_name"; exit; } else { echo "Connected to $ftp_server, for user $ftp_user_name"; } // upload the file $upload = ftp_put($conn_id, $destination_file, $source_file, FTP_BINARY); // check upload status if (!$upload) { echo "FTP upload has failed!"; } else { echo "Uploaded $source_file to $ftp_server as $destination_file"; } // close the FTP stream ftp_close($conn_id); ?>

Table of Contents
ftp_alloc -- Allocates space for a file to be uploaded
ftp_cdup -- Changes to the parent directory
ftp_chdir -- Changes the current directory on a FTP server
ftp_chmod -- Set permissions on a file via FTP
ftp_close -- Closes an FTP connection
ftp_connect -- Opens an FTP connection
ftp_delete -- Deletes a file on the FTP server
ftp_exec -- Requests execution of a program on the FTP server
ftp_fget -- Downloads a file from the FTP server and saves to an open file
ftp_fput -- Uploads from an open file to the FTP server
ftp_get_option -- Retrieves various runtime behaviours of the current FTP stream
ftp_get -- Downloads a file from the FTP server
ftp_login -- Logs in to an FTP connection
ftp_mdtm -- Returns the last modified time of the given file
ftp_mkdir -- Creates a directory
ftp_nb_continue -- Continues retrieving/sending a file (non-blocking)
ftp_nb_fget -- Retrieves a file from the FTP server and writes it to an open file (non-blocking)
ftp_nb_fput -- Stores a file from an open file to the FTP server (non-blocking)
ftp_nb_get -- Retrieves a file from the FTP server and writes it to a local file (non-blocking)
ftp_nb_put -- Stores a file on the FTP server (non-blocking)
ftp_nlist -- Returns a list of files in the given directory
ftp_pasv -- Turns passive mode on or off
ftp_put -- Uploads a file to the FTP server
ftp_pwd -- Returns the current directory name
ftp_quit -- Alias of ftp_close()
ftp_raw -- Sends an arbitrary command to an FTP server
ftp_rawlist -- Returns a detailed list of files in the given directory
ftp_rename -- Renames a file or a directory on the FTP server
ftp_rmdir -- Removes a directory
ftp_set_option -- Set miscellaneous runtime FTP options
ftp_site -- Sends a SITE command to the server
ftp_size -- Returns the size of the given file
ftp_ssl_connect -- Opens an Secure SSL-FTP connection
ftp_systype -- Returns the system type identifier of the remote FTP server

User Contributed Notes
FTP Functions

dickiedyce at uk dot com
07-May-2005 10:20


It may seem obvious to others, but it had me stumped for nearly an hour! If you can connect to an ftp site but some functions (list, put, get etc) don't work, then try using ftp_pasv and set passive mode on.



<?php



// setup $host and $file variables for your setup before here...



$hostip = gethostbyname($host);

$conn_id = ftp_connect($hostip);



// login with username and password

$login_result = ftp_login($conn_id, $ftp_user_name, $ftp_user_pass);



// IMPORTANT!!! turn passive mode on

ftp_pasv ( $conn_id, true );



if ((!$conn_id) || (!$login_result)) {

  echo "FTP connection has failed!";

  echo "Attempted to connect to $host for user $ftp_user_name";

  die;

} else {

  echo "Connected to $host, for user $ftp_user_name<br>";

  echo "Host IP is $hostip<br>";

  

  // upload a file

  if (ftp_put($conn_id, $remote_file, $file, FTP_ASCII)) {

    echo "successfully uploaded $file<br>";

  } else {

    echo "There was a problem while uploading $file<br>";

  }

    

  // close the connection

  ftp_close($conn_id);

}

?>

arjen at queek dot nl
15-Jul-2004 09:38


If you prefer a OO-approach to the FTP-functions, you can use this snippet of code (PHP5 only! and does add some overhead). It's just a "start-up", extend/improve as you wish...

You can pass all ftp_* functions to your object and stripping ftp_ of the function name. Plus, you don't have to pass the ftp-resource as the first argument.



For example:

<?php

ftp_delete($ftp, $file);    // Where $ftp is your ftp-resource

?>



Can become:

<?php

$ftp->delete($file);        // Where $ftp is your FTP-object

?>



Code:

<?php



class FTP {



    private $ftp;

    

    /* public Void __construct(): Constructor */

    public function __construct($host, $port = 21, $timeout = 90) {

        $this->ftp = ftp_connect($host, $port, $timeout);

    }

    

    /* public Void __destruct(): Destructor */

    public function __destruct() {

        @ftp_close($this->ftp);

    }



    /* public Mixed __call(): Re-route all function calls to the PHP-functions */

    public function __call($function, $arguments) {

        // Prepend the ftp resource to the arguments array

        array_unshift($arguments, $this->ftp);

        

        // Call the PHP function

        return call_user_func_array('ftp_' . $function, $arguments);

    }

    

}



?>

Kristy Christie (kristy at isp7 dot net)
15-Jun-2004 01:50


Here's a little function that I created to recurse through a local directory and upload the entire contents to a remote FTP server.



In the example, I'm trying to copy the entire "iwm" directory located at /home/kristy/scripts/iwm to a remote server's /public_html/test/ via FTP.



The only trouble is that for the line "if (!ftp_chdir($ftpc,$ftproot.$srcrela))", which I use to check if the directory already exists on the remote server, spits out a warning about being unable to change to that directory if it doesn't exist.



But an error handler should take care of it.



My thanks to the person who posted the snippet on retrieving the list of files in a directory.



For the version of the script that echo's it's progress as it recurses & uploads, go to: http://pastebin.com/73784



<?php



// --------------------------------------------------------------------

// THE TRIGGER

// --------------------------------------------------------------------



    // set the various variables

    $ftproot = "/public_html/test/";

    $srcroot = "/home/kristy/scripts/";        

    $srcrela = "iwm/";



    // connect to the destination FTP & enter appropriate directories both locally and remotely

    $ftpc = ftp_connect("ftp.mydomain.com");

    $ftpr = ftp_login($ftpc,"username","password");



    if ((!$ftpc) || (!$ftpr)) { echo "FTP connection not established!"; die(); }

    if (!chdir($srcroot)) { echo "Could not enter local source root directory."; die(); }

    if (!ftp_chdir($ftpc,$ftproot)) { echo "Could not enter FTP root directory."; die(); }



    // start ftp'ing over the directory recursively

    ftpRec ($srcrela);



    // close the FTP connection

    ftp_close($ftpc);



// --------------------------------------------------------------------

// THE ACTUAL FUNCTION

// --------------------------------------------------------------------

function ftpRec ($srcrela)

{

    global $srcroot;

    global $ftproot;

    global $ftpc;

    global $ftpr;

                

    // enter the local directory to be recursed through

    chdir($srcroot.$srcrela);

    

    // check if the directory exists & change to it on the destination

    if (!ftp_chdir($ftpc,$ftproot.$srcrela))

    {

        // remote directory doesn't exist so create & enter it

           ftp_mkdir    ($ftpc,$ftproot.$srcrela);

           ftp_chdir    ($ftpc,$ftproot.$srcrela);

    }



    if ($handle = opendir("."))

    {

       while (false !== ($fil = readdir($handle)))

       {

           if ($fil != "." && $fil != "..")    

           {

               // check if it's a file or directory

               if (!is_dir($fil))

               {    

                   // it's a file so upload it

                   ftp_put($ftpc, $ftproot.$srcrela.$fil, $fil, FTP_BINARY);

                }

                else

                {

                    // it's a directory so recurse through it

                    if ($fil == "templates")

                    {

                            // I want the script to ignore any directories named "templates"

                            // and therefore, not recurse through them and upload their contents

                    }

                    else

                    {

                        ftpRec ($srcrela.$fil."/");

                        chdir ("../");

                    }

                }

          }

      }

      closedir($handle);

    }    

}

?>

postmaster at alishomepage dot com
24-Jan-2004 05:29


I have written an OpenSource ZIP2FTP interface, which actually takes a given ZIP file and decompresses it in the folder on an FTP server you specify...



Therefore it may be quite interesting for you people interested in FTP, its adress is http://zip2ftp.alishomepage.com ; those who directly want the source may visit http://zip2ftp.alishomepage.com/?do=getSource

Vikrant Korde <vakorde at hotmail dot com>
14-Nov-2003 07:35


<?



//If you want to move or replicate the folder hierarchy from your current server to another remote server. Then this will be helpful as this will browse the current server's directory and at the same time it will copy that file in the remote server in the same directory. 



//This script will copy all the files from this directory and subdirectory to another remote server via FTP



function rec_copy ($source_path, $destination_path, $con)

{

    ftp_mkdir($con, $destination_path);

    ftp_site($con, 'CHMOD 0777 '.$destination_path);

    ftp_chdir($con,$destination_path);



    if (is_dir($source_path)) 

    {

        chdir($source_path);

        $handle=opendir('.');

        while (($file = readdir($handle))!==false) 

        {

            if (($file != ".") && ($file != "..")) 

            {

                if (is_dir($file))

                {

                    // here i am restricting the folder name 'propertyimages' from being copied to remote server. -- VK

                    if($file != "propertyimages")

                    {

                        rec_copy ($source_path."/".$file, $file, $con);

                        chdir($source_path);

                        ftp_cdup($con);

                    }

                }

                if (is_file($file))

                {

                    $fp = fopen($file,"r");

                    // this will convert spaces to '_' so that it will not throw error.  -- VK

                    ftp_fput ($con, str_replace(" ", "_", $file), $fp,FTP_BINARY);

                    ftp_site($con, 'CHMOD 0755 '.str_replace(" ", "_", $file));

                } 

            }

        }

        closedir($handle); 

    }

}



// make a FTP connection --VK

$con = ftp_connect("69.18.213.131",21);

$login_result = ftp_login($con,"username","password");    



// this is the root path for the remote server-- VK

$rootpath = "mainwebsite_html";    



// this is the physical path of the source directory. actually u can also use the relative path. -- VK

$sourcepath = realpath("../")."/resdesk";



// this directory name will only change the top most directory and not the inner one -- VK

$destination_dir_name = "resdesk_".$account_id."/";



rec_copy ($sourcepath, $destination_dir_name, $con);

if (function_exists("ftp_close")) 

{

    ftp_close($con);

}

?>

postmaster at alishomepage dot com
24-Oct-2003 06:06


Here's another FTP interface over PHP (also uses MySQL)



http://myftp.alishomepage.com



PS: this script will ALSO allow you to download its source... So it becomes interesting for YOU PROGRAMMERS as well :D

arjenjb dot wanadoo dot nl
09-Mar-2003 12:29


Check http://nanoftpd.sourceforge.net/ for a FTP server written in PHP.

Supports Passive and Active FTP, and all other standard FTP commands as decribed in RFC959.

NOSPAMkent at ioflux dot NOSPAM dot com
19-Sep-2002 07:05


I think what some other posts were trying to say which may need clarification is that in PHP 4.2.3, ftp_connect("myhost.com") was failing most of the time, except it would work like every few minutes.



The fix is that ftp_connect seems to have a bug resolving addresses. If you do:



$hostip = gethostbyname($host);

$conn_id = ftp_connect($hostip);



It seems to solve the problem.

(Other users referred to an ftpbuf() error... not sure what that is, but this should fix it.)

sven at cartell-network dot de
13-Feb-2002 01:27


connection to a ftp server across proxy



$ftp_server = "proxy"; f.e. 123.456.789.10

$ftp_user_name = "username@ftpserver"; f.e. exampleuk@www.example.uk

$ftp_user_pass = "password";



$conn_id = ftp_connect($ftp_server, 2121);

$login_result = ftp_login( $conn_id, $ftp_user_name, $ftp_user_pass );