blueshoes php application framework and cms            core_net
[ class tree: core_net ] [ index: core_net ] [ all elements ]

Class: Bs_FtpClient

Source Location: /core/net/ftp/Bs_FtpClient.class.php

Class Overview

Bs_Object
   |
   --Bs_FtpClient

Abstract Ftp client class. needs to be subclassed.


Author(s):

Version:

  • 4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:42 $

Copyright:

  • blueshoes.org

Variables

Methods


Child classes:

Bs_FtpClientPhp
Ftp client class using the built in module/functions from php.

Inherited Variables

Inherited Methods

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[line 68]
Abstract Ftp client class. needs to be subclassed.

this is the minimal implementation for all ftp clients in blueshoes. this way one can rely on the methods. you don't need to document again what's documented here. better refer to this file.

i think that ftp transactions are only used in an admin environment and not for spitting out live pages. so speed doesn't matter that much.

requested reading:

 rfc  959:   the official, current ftp rfc.
             http://www.faqs.org/rfcs/rfc959.html from 1985. i don't think that
             older rfc's should be supported or even looked at.
 rfc 1123:   Requirements for Internet Hosts -- Application and Support
             (Contains important clarifications for RFC-959)
 rfc 2228:   FTP Security Extensions
 rfc 2389:   Feature negotiation mechanism for the File Transfer Protocol
 rfc 2428:   FTP Extensions for IPv6 and NATs
 rfc 2577:   FTP Security Considerations
 rfc 2640:   Internationalization of the File Transfer Protocol
 links:      - The FTP Protocol Resource Center http://war.jgaa.com/ftp/
             - php manual. i think it's bad and incomplete.
               http://www.php.net/manual/en/ref.ftp.php

 //some method names come from the ftp command. example: mdtm() (returns lastmod).
 

caution: when working with the filesystem there's always the risk of loosing data. be aware of that. take special care of these situations:

  • synchronization (overwritten by mistake, wrong timestamps)
  • broken transactions in the middle (old file killed, new incomplete)
  • file links and dir links (for example a recursive rmDir())
knowledge base:
  • the ftp protocol differs to others like http and email in that 2 connections are used. one for the control flow, one for the data transfer.
  • the protocol has not been changed since 1985. (there have been extenstions.) so there are commands that are like-standard, but undocumented. they include SIZE and MDTM and a different use of REST. also there's a problem with the return value of the LIST command, which has never been standardized (sucks alot). now there's a draft document for these new commands/changes and new commands to work around the LIST problem. i really hope this makes it into a new rfc soon. see http://war.jgaa.com/ftp/draft/draft-ietf-ftpext-mlst-11.txt




Tags:

pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.3 $ $Date: 2003/10/29 17:48:42 $
copyright:  blueshoes.org
author:  Andrej Arn <at blueshoes dot org>


[ Top ]


Class Variables

$anonymous =  TRUE

[line 110]

if connection should be made anonymous or not.



Tags:

var:  default is FALSE.
see:  vars $username, Bs_FtpClient::$password
access:  public

Type:   bool


[ Top ]

$host =

[line 95]

the host to connect to.



Tags:

access:  public

Type:   string


[ Top ]

$password =

[line 126]

if not connecting anonymous this password will be sent.



Tags:

see:  vars $anonymous, Bs_FtpClient::$username
access:  public

Type:   string


[ Top ]

$port =  21

[line 102]

the port to connect to. default is 21.



Tags:

access:  public

Type:   int


[ Top ]

$transferMode =  FTP_ASCII

[line 135]

the transfer mode. one of [FTP_ASCII|FTP_BINARY]. default is binary.

i thought it's too dangerous (with subclassing) to just call it 'mode'. again: make sure these 2 constants are set: FTP_ASCII and FTP_BINARY.




Tags:

var:  (use constant)
access:  public

Type:   string


[ Top ]

$username =

[line 118]

if not connecting anonymous this username will be sent.



Tags:

see:  vars $anonymous, Bs_FtpClient::$password
access:  public

Type:   string


[ Top ]

$_isConnected =  FALSE

[line 88]

tells if we're connected to a server or not.



Tags:

see:  Bs_FtpClient::isConnected()
access:  public

Type:   bool


[ Top ]



Class Methods


constructor Bs_FtpClient [line 177]

Bs_FtpClient Bs_FtpClient( )

constructor



Overridden in child classes as:

Bs_FtpClientPhp::Bs_FtpClient()
constructor

[ Top ]

method cdUp [line 261]

bool cdUp( )

Changes to the remote parent directory.

it's like doing 'cd ..'.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::cdUp()
uses ftp_cdup — Changes to the parent directory

[ Top ]

method chDir [line 281]

bool chDir( string $directory)

Changes remote directory.



Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::chDir()
ftp_chdir — Changes directories on an FTP server

Parameters:

string   $directory   (the directory to go to.)

[ Top ]

method connect [line 220]

bool connect( )

Opens up an FTP connection (to the current host/port).



Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::connect()
uses ftp_connect

[ Top ]

method delete [line 726]

bool delete( string $remoteFile)

Deletes a file on the ftp server.



Tags:

return:  TRUE on success, FALSE on failure.
see:  Bs_FtpClient::localDelete()
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::delete()
ftp_delete — Deletes a file on the ftp server.

Parameters:

string   $remoteFile  

[ Top ]

method dirExists [line 632]

void dirExists( )



[ Top ]

method fGet [line 579]

bool fGet( resource $fp, string $remoteFile, [int $mode = NULL])

Downloads a file from the FTP server and saves to an open file.

retrieves remote_file from the FTP server, and writes it to the given file pointer, fp. The transfer mode specified must be either FTP_ASCII or FTP_BINARY.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::fGet()
ftp_fget — Downloads a file from the FTP server and saves to an open file.

Parameters:

resource   $fp   (file pointer)
string   $remoteFile  
int   $mode   (use constant, one of FTP_ASCII or FTP_BINARY. if not given $this->_transferMode is used.)

[ Top ]

method fileExists [line 620]

bool fileExists( string $remoteFile)

tells if the given file exists on the server.



Tags:

return:  TRUE if it does, FALSE if it does not
throws:  null if we can't tell (error, no permission)
access:  public


Parameters:

string   $remoteFile  

[ Top ]

method fPut [line 609]

bool fPut( resource $fp, string $remoteFile, [int $mode = NULL])

Uploads from an open file to the FTP server.

uploads the data from the file pointer fp until end of file. The results are stored in remote_file on the FTP server. The transfer mode specified must be either FTP_ASCII or FTP_BINARY.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::fPut()
ftp_fput — Uploads from an open file to the FTP server.

Parameters:

resource   $fp   (file pointer)
string   $remoteFile  
int   $mode   (use constant, one of FTP_ASCII or FTP_BINARY. if not given $this->_transferMode is used.)

[ Top ]

method get [line 565]

bool get( string $localFile, string $remoteFile, [int $mode = NULL])

Downloads a file from the FTP server.

retrieves $remoteFile from the FTP server, and saves it to $localFile locally. The transfer mode specified must be either FTP_ASCII or FTP_BINARY. caution: overwrites any existing file.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::get()
ftp_get — Downloads a file from the FTP server.

Parameters:

string   $localFile  
string   $remoteFile  
int   $mode   (use constant, one of FTP_ASCII or FTP_BINARY. if not given $this->_transferMode is used.)

[ Top ]

method isConnected [line 210]

void isConnected( )



[ Top ]

method lastMod [line 679]

int lastMod( string $remoteFile)

Returns the last modified time of the given remote file.

caution: Not all servers support this feature. see header documentation. note: does not work with directories. executes the FTP MDTM command.




Tags:

return:  unix timestamp
see:  Bs_FtpClient::localLastMod()
throws:  bool FALSE on error or if not supported by server.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::lastMod()
ftp_mdtm — Returns the last modified time of the given file.

Parameters:

string   $remoteFile  

[ Top ]

method localCdUp [line 271]

bool localCdUp( )

Changes to the local parent directory.

it's like doing 'cd ..'.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


[ Top ]

method localChDir [line 291]

bool localChDir( string $param)

Changes local directory.



Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Parameters:

string   $param   (the directory to go to.)

[ Top ]

method localDelete [line 737]

bool localDelete( string $localFile)

Deletes a local file.



Tags:

return:  TRUE on success, FALSE on failure.
see:  Bs_FtpClient::delete()
access:  public


Parameters:

string   $localFile  

[ Top ]

method localDirExists [line 636]

void localDirExists( )



[ Top ]

method localExists [line 628]

void localExists( )



[ Top ]

method localLastMod [line 691]

int localLastMod( string $localFile)

Returns the last modified time of the given local file.



Tags:

return:  unix timestamp
see:  Bs_FtpClient::lastMod()
throws:  bool FALSE on error
access:  public


Parameters:

string   $localFile  

[ Top ]

method localMkDir [line 312]

mixed localMkDir( string $directory)

Creates a local directory.



Tags:

return:  (string (the new directory name) on success, bool FALSE on failure.
access:  public


Parameters:

string   $directory   (the new directory name.)

[ Top ]

method localNlist [line 395]

mixed localNlist( string $directory)

Returns a list of files in the given local directory.



Tags:

return:  (an array (vector) of filenames on success, bool FALSE on failure.
access:  public


Parameters:

string   $directory   (the directory name.)

[ Top ]

method localPwd [line 251]

string localPwd( )

Returns the current local directory name.



Tags:

access:  public


[ Top ]

method localRawList [line 517]

array &localRawList( string $localDir)

Returns a detailed list of files in the given local directory.

in difference to rawList() the returned value is always 'parsed'. everything else would make no sense.




Tags:

return:  (vector holding hashes)
see:  Bs_FtpClient::rawList()
access:  public


Parameters:

string   $localDir  

[ Top ]

method localRename [line 715]

bool localRename( string $localFile, string $newLocalFile)

Renames a local file.



Tags:

return:  TRUE on success, FALSE on failure.
see:  Bs_FtpClient::rename()
access:  public


Parameters:

string   $localFile  
string   $newLocalFile  

[ Top ]

method localRmDir [line 365]

bool localRmDir( string $directory)

Removes a local directory.



Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Parameters:

string   $directory   (the directory name.)

[ Top ]

method localRmDirRec [line 369]

void localRmDirRec( )



[ Top ]

method localSize [line 664]

int localSize( string $localFile)

Returns the size of the given local file.



Tags:

return:  the file size (in bytes i guess)
see:  Bs_FtpClient::size()
throws:  bool FALSE on error
access:  public


Parameters:

string   $localFile  

[ Top ]

method login [line 231]

bool login( )

Logs in an FTP connection.

uses the current username/password.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::login()
uses ftp_login

[ Top ]

method mkDir [line 302]

bool mkDir( string $directory)

Creates a remote directory.

your current working dir won't change [into that directory].




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::mkDir()
ftp_mkdir — Creates a directory

Parameters:

string   $directory   (the new directory name.)

[ Top ]

method nList [line 385]

array &nList( string $directory)

Returns a list of files in the given remote directory.

2do: does it return directories too? how about file- and dirlinks? are the values relative or absolute?




Tags:

return:  (vector of filenames.)
throws:  bool FALSE
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::nList()
ftp_nlist — Returns a list of files in the given directory.

Parameters:

string   $directory   (the directory name.)

[ Top ]

method parseRawList [line 471]

array &parseRawList( array &$rawList)

parses the given $rawList.

i really don't see why the return of an ftp LIST command has never been standardized. see header documentation.

different ftp servers return a different string format. please report here what you know. Serv-U version 2.4 "-rw-r--r-- 1 user group 117 Sep 17 10:38 welcomeMessage.txt" comets ftpd (some linux ftpd, i should check that.) "drwxr-xr-x 3 root root 4096 Jan 25 2001 ircd"

Serv-U and the linux one give the same output (one space different). that's pretty good.

description of the parts: drwxr-xr-x => the first character can be a 'd' or a '-'. d means the 'file' is a directory,

  • means it is a file.
3 => this integer is a number from 1 to n. if the 'file' is a file, it's always set to 1. if it is a directory, it is 2-n. it is the number of (recursive) subdirectories plus the current directory plus 1. so a '3' means this dir has exactly one subdir. root => the owner user. root => the owner group. 4096 => the file size in bytes. Jan 25 2001 => this is the datetime in some strange format and with missing information. if the file has changed this year for the last time, we get month day and hour/minute. if it was in a previous year, we get month day and the year. anyway we never get the seconds. this makes it harder/more buggy to synchronize files. ircd => the file/directory name (whatever it is). i've read about problems if the names have spaces in there. my suggestion: don't use spaces at all.

the return array may have the following keys, depending on the ftpserver-os: 'name' => 'someshit.txt' //file or directory name 'size' => 4096 //bytes 'date' => '2001/09/07 08:23' //or '2001/09/07'. see above. 'attr' => 'drwxr-xr-x' //(directory yes/no, user rights, group rights, world rights) 'type' => [dir|file] //can't tell if it's a link :( 'dirno' => [1-n] //the directory number, details see above. 'user' => 'root' //the owner user. on windows this doesn't mean much. 'group' => 'root' //the owner group. on windows this doesn't mean much.




Tags:

return:  (see above)
see:  Bs_FtpClient::rawList()
throws:  bool FALSE if not capable = we did not get the format above.
access:  public


Parameters:

array   &$rawList  

[ Top ]

method pasv [line 550]

bool pasv( bool $param)

Turns passive mode on or off.

if $param is TRUE, passive mode will be activated, deactivated otherwise. in passive mode, data connections are initiated by the client, rather than by the server.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::pasv()
ftp_pasv — Turns passive mode on or off.

Parameters:

bool   $param  

[ Top ]

method put [line 594]

bool put( string $localFile, string $remoteFile, [int $mode = NULL])

Uploads a file to the FTP server.

stores local_file on the FTP server, as remote_file. The transfer mode specified must be either FTP_ASCII or FTP_BINARY. caution: overwrites any existing file.




Tags:

return:  TRUE on success, FALSE on failure.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::put()
ftp_put — Uploads a file to the FTP server.

Parameters:

string   $localFile  
string   $remoteFile  
int   $mode   (use constant, one of FTP_ASCII or FTP_BINARY. if not given $this->_transferMode is used.)

[ Top ]

method pwd [line 242]

string pwd( [bool $useCache = TRUE])

Returns the current remote directory name.



Tags:

throws:  bool FALSE
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::pwd()
uses ftp_pwd

Parameters:

bool   $useCache   default is TRUE. if we should use the cached information if available.

[ Top ]

method quit [line 759]

void quit( )

Closes the FTP connection.



Tags:

access:  public


Overridden in child classes as:

Bs_FtpClientPhp::quit()
ftp_quit — Closes an FTP connection

[ Top ]

method rawList [line 419]

mixed &rawList( string $directory, [bool $parse = TRUE])

Returns a detailed list of files in the given remote directory.

executes the FTP LIST command.

if param $parse is TRUE, the return value is a vector holding a hash. each file is represented by a hash inside the vector. for details see parseRawList().

if param $parse is FALSE, the return value is a vector holding strings with the unparsed information. use $this->sysType() to do something on your own. or better implement the missing functionality into your favorite ftp class! whatever! do something! don't just sit here and stare at these lines! and give me some of your pizza! *yummy* :-)




Tags:

return:  (an array (vector) see above, bool FALSE on failure.
see:  Bs_FtpClient::parseRawList()
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::rawList()
ftp_rawlist — Returns a detailed list of files in the given directory.

Parameters:

string   $directory   (the directory name.)
bool   $parse   (default is TRUE, see above.)

[ Top ]

method rename [line 703]

bool rename( string $remoteFile, string $newRemoteFile)

Renames a file on the ftp server.



Tags:

return:  TRUE on success, FALSE on failure.
see:  Bs_FtpClient::localRename()
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::rename()
ftp_rename — Renames a file on the ftp server.

Parameters:

string   $remoteFile  
string   $newRemoteFile  

[ Top ]

method reset [line 195]

void reset( )

clears up the object by resetting all class vars to its original state, as if the object was newly created. reusing an object this way saves resources and time in php (instead of creating a new object).

the subclassing class should implement a reset() method also, call this one to clean up the vars of this class, and clean up it's own vars itself. and of course disconnect the connection first.




Tags:

access:  public


Overridden in child classes as:

Bs_FtpClientPhp::reset()
uses parent method, see there.

[ Top ]

method rmDir [line 326]

bool rmDir( string $directory)

Removes a remote directory.

the directory must be empty. if you are currently in that directory (current working dir) you better move out. the ftp command for this is RMD.




Tags:

return:  TRUE on success, FALSE on failure.
todo:  what happens with dir- and file links?
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::rmDir()
ftp_rmdir — Removes a directory

Parameters:

string   $directory   (the directory name.)

[ Top ]

method rmDirRec [line 339]

int rmDirRec( string $directory)

Removes a remote directory recursively; with all content in it.

if you are currently in that directory (current working dir) you better move out.




Tags:

return:  (1 if everything was removed, 0 if parts were removed, -1 if nothing was removed.)
todo:  test this code
todo:  what happens with dir- and file links?
access:  public


Parameters:

string   $directory   (the directory name.)

[ Top ]

method site [line 750]

? site( string $command)

Sends a SITE command to the server.

sends the command $command to the FTP server. SITE commands are not standardized, and vary from server to server. They are useful for handling such things as file permissions and group membership.




Tags:

access:  public


Overridden in child classes as:

Bs_FtpClientPhp::site()
ftp_site — Sends a SITE command to the server.

Parameters:

string   $command  

[ Top ]

method size [line 652]

int size( string $remoteFile)

Returns the size of the given remote file.

caution: Not all servers support this feature. see header documentation. please report here which server do/don't support it. thanx. executes the FTP SIZE command.




Tags:

return:  the file size (in bytes i guess)
see:  Bs_FtpClient::localSize()
throws:  bool FALSE on error or if not supported by server.
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::size()
ftp_size — Returns the size of the given file.

Parameters:

string   $remoteFile  

[ Top ]

method synchronizeDir [line 774]

void synchronizeDir( mixed $localDir, mixed $remoteDir, [int $depth = 0], [mixed $direction = 'both'])



Parameters:

int   $depth   (how many directory levels we should follow. 0 = none. -1 = unlimited. default is 0 (more security).)

[ Top ]

method synchronizeFile [line 767]

void synchronizeFile( mixed $localFile, mixed $remoteFile, [string $direction = 'both'])



Parameters:

string   $direction   (one of [both|up|down])

[ Top ]

method sysType [line 538]

string sysType( [bool $useCache = TRUE])

Returns the system type identifier of the remote FTP server.

executes the FTP SYST command. the name returned shall be one listed in the assigned numbers document. see the kb file operatingSystemNames.txt (about 130 are listed).

my Serv-U ftpd on windows returns 'UNIX', exactly like some ftpd on my linux box does. and because they give similar unix-like output on the LIST command (see parseRawList()) i think that's what it's for. if you want to know the operating system you better use something else than ftp.




Tags:

throws:  bool FALSE
access:  public


Overridden in child classes as:

Bs_FtpClientPhp::sysType()
ftp_systype — Returns the system type identifier of the remote FTP server.

Parameters:

bool   $useCache   default is TRUE. if we should use the cached information if available.

[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:10:40 +0100 by phpDocumentor 1.2.3