Oihana Php Ftp

FtpClient uses FtpConnectionTrait, FtpCryptoTrait, FtpDirectoryTrait, FtpFileTrait

A modern, strongly-typed FTP / FTPS client.

The client is a thin façade that composes its behaviour from focused traits. It never touches ext-ftp directly: every transport call goes through an injected FtpDriverInterface, which keeps the whole surface testable and leaves room for alternative transports (e.g. a future SFTP driver).

use oihana\ftp\FtpClient ;
use oihana\ftp\enums\Ftp ;
use oihana\ftp\enums\FtpSecurity ;

$client = new FtpClient
([
    Ftp::HOST     => 'ftp.example.org' ,
    Ftp::USERNAME => 'alice' ,
    Ftp::PASSWORD => 's3cr3t' ,
    Ftp::SECURITY => FtpSecurity::SSL ,
]) ;

$client->connect() ;
// ... transfers ...
$client->disconnect() ;
Tags
author

Marc Alcaraz (ekameleon)

since
1.0.0

Table of Contents

Properties

$maxRetries  : int
The maximum number of attempts for a transient (connection) failure.
$connected  : bool
Whether the client is currently connected.
$credentials  : FtpCredentials
The login credentials.
$driver  : FtpDriverInterface
The transport driver.
$host  : string
The remote host.
$passive  : bool
Whether passive mode is enabled.
$port  : int
The control-channel port.
$root  : string
The remote base directory entered right after login (empty to stay in the default directory).
$secure  : bool
Whether the transport is secured (FTPS).
$security  : string
The transport security mode.
$timeout  : int
The connection timeout, in seconds.
$transferMode  : string
The default transfer mode applied to file operations.

Methods

__construct()  : mixed
Creates a new FTP client.
__destruct()  : mixed
Closes the connection on destruction.
append()  : static
Appends the contents of a local file to a remote file.
changeDirectory()  : static
Changes the current working directory.
chmod()  : static
Changes the permissions of a remote file.
connect()  : static
Opens the connection and authenticates, retrying transient failures with exponential backoff. A no-op when already connected.
createDirectories()  : static
Creates a directory and every missing parent along the path (best effort).
createDirectory()  : static
Creates a remote directory.
currentDirectory()  : string
Returns the current working directory.
delete()  : static
Deletes a remote file.
disconnect()  : static
Closes the connection if it is open.
download()  : static
Downloads a remote file to the local filesystem.
downloadDecrypted()  : static
Downloads an encrypted remote file and decrypts it to the local filesystem.
exists()  : bool
Indicates whether a remote file exists (and exposes a readable size).
getCredentials()  : FtpCredentials
Returns the configured login credentials.
getHost()  : string
Returns the configured remote host.
getMaxRetries()  : int
Returns the configured maximum number of connection attempts.
getPort()  : int
Returns the configured control-channel port.
getRoot()  : string
Returns the configured remote root directory.
getTimeout()  : int
Returns the configured connection timeout.
getTransferMode()  : string
Returns the default transfer mode applied to file operations.
isConnected()  : bool
Indicates whether a connection is currently open.
isPassive()  : bool
Indicates whether passive mode is enabled.
isSecure()  : bool
Indicates whether the transport is secured (FTPS).
lastModified()  : int
Returns the last-modified time of a remote file, as a Unix timestamp.
listFiles()  : array<int, FtpFile>
Returns the structured entries of a directory.
listNames()  : array<int, string>
Returns the names of the entries in a directory.
parentDirectory()  : static
Moves up to the parent directory.
rawList()  : array<int, string>
Returns the raw, server-formatted listing of a directory.
removeDirectory()  : static
Removes a remote directory.
rename()  : static
Renames or moves a remote file or directory.
size()  : int
Returns the size of a remote file, in bytes.
upload()  : static
Uploads a local file to the server.
uploadEncrypted()  : static
Encrypts a local file and uploads the ciphertext to the server.
waitBeforeRetry()  : void
Pauses between two connection attempts. Isolated so tests can override it without changing the retry logic.
applyRoot()  : void
Changes into the configured root directory, if any, right after connecting.
assertLocalFile()  : void
Asserts that a local file exists and is readable.
ensureConnected()  : void
Asserts that the client holds an open connection.
establish()  : void
Performs a single connect + authenticate sequence.
initializeConfig()  : void
Reads the configuration array into the connection state.
resolveTransferMode()  : int
Resolves a transfer-mode string to its `ext-ftp` resource value.
temporaryCryptoFile()  : string
Creates a temporary file used to hold ciphertext during a secure transfer.

Properties

$maxRetries

The maximum number of attempts for a transient (connection) failure.

public int $maxRetries = 3

$connected

Whether the client is currently connected.

private bool $connected = false

$root

The remote base directory entered right after login (empty to stay in the default directory).

private string $root = ''

$security

The transport security mode.

private string $security = \oihana\ftp\enums\FtpSecurity::NONE

$transferMode

The default transfer mode applied to file operations.

private string $transferMode = \oihana\ftp\enums\FtpTransferMode::BINARY

Methods

__construct()

Creates a new FTP client.

public __construct([array<string|int, mixed>|FtpOptions $init = [] ][, FtpDriverInterface|null $driver = null ][, ContainerInterface|null $container = null ]) : mixed
Parameters
$init : array<string|int, mixed>|FtpOptions = []

Configuration keyed by Ftp constants (or an FtpOptions instance): host, port, username, password, security, passive, timeout, maxRetries, plus any logger options.

$driver : FtpDriverInterface|null = null

The transport driver. Defaults to a NativeFtpDriver.

$container : ContainerInterface|null = null

Optional PSR-11 container used to resolve a logger service.

Tags
throws
DependencyException
ContainerExceptionInterface
NotFoundException
NotFoundExceptionInterface
ReflectionException

append()

Appends the contents of a local file to a remote file.

public append(string $localFile, string $remoteFile[, string|null $mode = null ]) : static
Parameters
$localFile : string

The source path on the local filesystem.

$remoteFile : string

The destination path on the server.

$mode : string|null = null

The transfer mode; defaults to the client's configured mode.

Tags
throws
FtpTransferException

When the local file is missing, the append fails, or no connection is open.

Return values
static —

This instance, for chaining.

changeDirectory()

Changes the current working directory.

public changeDirectory(string $directory) : static
Parameters
$directory : string

The target directory.

Tags
throws
FtpTransferException

When the change fails or no connection is open.

Return values
static —

This instance, for chaining.

chmod()

Changes the permissions of a remote file.

public chmod(string $remoteFile, int $permissions) : static
Parameters
$remoteFile : string

The remote path.

$permissions : int

The new permissions, as an octal value (e.g. 0644).

Tags
throws
FtpTransferException

When the change fails or no connection is open.

Return values
static —

This instance, for chaining.

connect()

Opens the connection and authenticates, retrying transient failures with exponential backoff. A no-op when already connected.

public connect() : static
Tags
throws
FtpConnectionException

When the connection cannot be established after every retry.

FtpAuthenticationException

When the server rejects the credentials (no retry).

Return values
static —

This instance, for chaining.

createDirectories()

Creates a directory and every missing parent along the path (best effort).

public createDirectories(string $path) : static

Each path segment is created in turn; segments that already exist are silently skipped, mirroring mkdir -p.

Parameters
$path : string

The directory path to create.

Tags
throws
FtpTransferException

When no connection is open.

Return values
static —

This instance, for chaining.

createDirectory()

Creates a remote directory.

public createDirectory(string $directory) : static
Parameters
$directory : string

The directory to create.

Tags
throws
FtpTransferException

When the creation fails or no connection is open.

Return values
static —

This instance, for chaining.

currentDirectory()

Returns the current working directory.

public currentDirectory() : string
Tags
throws
FtpTransferException

When the directory cannot be determined or no connection is open.

Return values
string —

The absolute path of the current directory.

delete()

Deletes a remote file.

public delete(string $remoteFile) : static
Parameters
$remoteFile : string

The path of the file to delete.

Tags
throws
FtpTransferException

When the deletion fails or no connection is open.

Return values
static —

This instance, for chaining.

disconnect()

Closes the connection if it is open.

public disconnect() : static
Return values
static —

This instance, for chaining.

download()

Downloads a remote file to the local filesystem.

public download(string $remoteFile, string $localFile[, string|null $mode = null ][, bool $createDirectory = true ]) : static
Parameters
$remoteFile : string

The source path on the server.

$localFile : string

The destination path on the local filesystem.

$mode : string|null = null

The transfer mode (one of FtpTransferMode); defaults to the client's configured mode.

$createDirectory : bool = true

Whether to create the local parent directory if missing.

Tags
throws
DirectoryException
FtpTransferException

When the download fails or no connection is open.

Return values
static —

This instance, for chaining.

downloadDecrypted()

Downloads an encrypted remote file and decrypts it to the local filesystem.

public downloadDecrypted(string $remoteFile, string $localFile, string $passphrase) : static
Parameters
$remoteFile : string

The ciphertext source on the server.

$localFile : string

The plaintext destination on the local filesystem.

$passphrase : string

The passphrase used to derive the decryption key.

Tags
throws
FtpTransferException

When the transfer fails.

DirectoryException
FileException
Return values
static —

This instance, for chaining.

exists()

Indicates whether a remote file exists (and exposes a readable size).

public exists(string $remoteFile) : bool

Directories and files whose size the server refuses to report are treated as absent.

Parameters
$remoteFile : string

The remote path.

Tags
throws
FtpTransferException

When no connection is open.

Return values
bool —

True when the file exists with a known size.

getHost()

Returns the configured remote host.

public getHost() : string
Return values
string —

The host name or IP address.

getMaxRetries()

Returns the configured maximum number of connection attempts.

public getMaxRetries() : int
Return values
int —

The retry ceiling.

getPort()

Returns the configured control-channel port.

public getPort() : int
Return values
int —

The port number.

getRoot()

Returns the configured remote root directory.

public getRoot() : string
Return values
string —

The root directory, or an empty string when none is set.

getTimeout()

Returns the configured connection timeout.

public getTimeout() : int
Return values
int —

The timeout, in seconds.

getTransferMode()

Returns the default transfer mode applied to file operations.

public getTransferMode() : string
Return values
string —

One of the FtpTransferMode constants.

isConnected()

Indicates whether a connection is currently open.

public isConnected() : bool
Return values
bool —

True when the client is connected.

isPassive()

Indicates whether passive mode is enabled.

public isPassive() : bool
Return values
bool —

True when passive mode is used.

isSecure()

Indicates whether the transport is secured (FTPS).

public isSecure() : bool
Return values
bool —

True when TLS is used.

lastModified()

Returns the last-modified time of a remote file, as a Unix timestamp.

public lastModified(string $remoteFile) : int

Not every server supports the underlying MDTM command.

Parameters
$remoteFile : string

The remote path.

Tags
throws
FtpTransferException

When the time cannot be determined or no connection is open.

Return values
int —

The Unix timestamp.

listFiles()

Returns the structured entries of a directory.

public listFiles([string $directory = '.' ]) : array<int, FtpFile>

Prefers the MLSD listing when the server supports it; otherwise falls back to parsing the raw ls -l output.

Parameters
$directory : string = '.'

The directory to list (defaults to the current directory).

Tags
throws
FtpTransferException

When the listing fails or no connection is open.

Return values
array<int, FtpFile> —

The structured entries.

listNames()

Returns the names of the entries in a directory.

public listNames([string $directory = '.' ]) : array<int, string>
Parameters
$directory : string = '.'

The directory to list (defaults to the current directory).

Tags
throws
FtpTransferException

When the listing fails or no connection is open.

Return values
array<int, string> —

The entry names.

parentDirectory()

Moves up to the parent directory.

public parentDirectory() : static
Tags
throws
FtpTransferException

When the change fails or no connection is open.

Return values
static —

This instance, for chaining.

rawList()

Returns the raw, server-formatted listing of a directory.

public rawList([string $directory = '.' ][, bool $recursive = false ]) : array<int, string>
Parameters
$directory : string = '.'

The directory to list (defaults to the current directory).

$recursive : bool = false

Whether to recurse into sub-directories.

Tags
throws
FtpTransferException

When the listing fails or no connection is open.

Return values
array<int, string> —

The raw listing lines.

removeDirectory()

Removes a remote directory.

public removeDirectory(string $directory) : static
Parameters
$directory : string

The directory to remove.

Tags
throws
FtpTransferException

When the removal fails or no connection is open.

Return values
static —

This instance, for chaining.

rename()

Renames or moves a remote file or directory.

public rename(string $from, string $to) : static
Parameters
$from : string

The current path.

$to : string

The new path.

Tags
throws
FtpTransferException

When the rename fails or no connection is open.

Return values
static —

This instance, for chaining.

size()

Returns the size of a remote file, in bytes.

public size(string $remoteFile) : int
Parameters
$remoteFile : string

The remote path.

Tags
throws
FtpTransferException

When the size cannot be determined or no connection is open.

Return values
int —

The size in bytes.

upload()

Uploads a local file to the server.

public upload(string $localFile, string $remoteFile[, string|null $mode = null ]) : static
Parameters
$localFile : string

The source path on the local filesystem.

$remoteFile : string

The destination path on the server.

$mode : string|null = null

The transfer mode; defaults to the client's configured mode.

Tags
throws
FtpTransferException

When the local file is missing, the upload fails, or no connection is open.

Return values
static —

This instance, for chaining.

uploadEncrypted()

Encrypts a local file and uploads the ciphertext to the server.

public uploadEncrypted(string $localFile, string $remoteFile, string $passphrase) : static
Parameters
$localFile : string

The plaintext source on the local filesystem.

$remoteFile : string

The destination path on the server.

$passphrase : string

The passphrase used to derive the encryption key.

Tags
throws
DirectoryException
FileException
FtpTransferException

When the local file is missing, or the transfer fails.

Return values
static —

This instance, for chaining.

waitBeforeRetry()

Pauses between two connection attempts. Isolated so tests can override it without changing the retry logic.

protected waitBeforeRetry(int $seconds) : void
Parameters
$seconds : int

The number of seconds to wait.

Tags
codeCoverageIgnore

applyRoot()

Changes into the configured root directory, if any, right after connecting.

private applyRoot() : void
Tags
throws
FtpConnectionException

When the root directory cannot be entered.

assertLocalFile()

Asserts that a local file exists and is readable.

private assertLocalFile(string $localFile) : void
Parameters
$localFile : string

The local path.

Tags
throws
FtpTransferException

When the file is missing or unreadable.

ensureConnected()

Asserts that the client holds an open connection.

private ensureConnected() : void

Shared by the file and directory operations.

Tags
throws
FtpTransferException

When no connection is open.

initializeConfig()

Reads the configuration array into the connection state.

private initializeConfig(array<string|int, mixed> $init) : void
Parameters
$init : array<string|int, mixed>

The configuration keyed by Ftp constants.

resolveTransferMode()

Resolves a transfer-mode string to its `ext-ftp` resource value.

private resolveTransferMode(string|null $mode) : int
Parameters
$mode : string|null

The requested mode, or null to use the configured default.

Return values
int —

Either FTP_ASCII or FTP_BINARY.

temporaryCryptoFile()

Creates a temporary file used to hold ciphertext during a secure transfer.

private temporaryCryptoFile() : string
Tags
throws
FtpTransferException

When the temporary file cannot be created.

Return values
string —

The temporary file path.

On this page

Search results