FTP Adapter

FTP Adapter

InitPHP\Upload\Adapters\FTPAdapter uploads files to a remote server over FTP or FTPS. It requires the ftp extension; constructing it without ext-ftp throws an UnsupportedException.

Credentials

Key	Type	Default	Description
host	string	''	FTP server hostname.
port	int	21	FTP port.
username	string	''	Login user.
password	string	''	Login password.
timeout	int	90	Connection timeout in seconds.
url	string	''	Public base URL the remote root is served from.
passive	bool	true	Use passive mode (recommended behind NAT/firewalls).
ssl	bool	false	Open an explicit FTPS (ftp_ssl_connect) connection.

use InitPHP\Upload\Upload;
use InitPHP\Upload\File;
use InitPHP\Upload\Adapters\FTPAdapter;

$adapter = new FTPAdapter(
    [
        'host'     => 'ftp.example.com',
        'username' => 'deploy',
        'password' => getenv('FTP_PASSWORD'),
        'url'      => 'https://cdn.example.com/',
        'passive'  => true,
    ],
    [
        'allowed_max_size' => 10 * 1024 * 1024,
    ]
);

$upload = new Upload($adapter);

Storing files

foreach (File::setPost('photos') as $file) {
    $stored = $upload->setFile($file)->to('gallery');

    if ($stored !== false) {
        echo $stored->getURL(); // https://cdn.example.com/gallery/<name>
    }
}

The connection is opened lazily on the first transfer and closed automatically when the adapter is destroyed.

Behaviour notes

• Binary mode. Transfers use FTP_BINARY, so images, archives, PDFs and every other non-text file are transferred byte-for-byte — never corrupted by line-ending translation.
• Passive mode. Enabled by default. Most clients behind NAT or a firewall need it. Set 'passive' => false only if your server explicitly requires active mode.
• FTPS. Set 'ssl' => true to connect with ftp_ssl_connect() (explicit FTP-over-TLS). Plain FTP sends credentials and data in the clear — prefer FTPS, or SFTP via another tool, whenever possible.
• Remote directories. When $target names a sub-path (to('gallery/2026')), the directories are created on a best-effort basis, segment by segment, before the file is sent.

FTPS example

$adapter = new FTPAdapter([
    'host'     => 'ftp.example.com',
    'port'     => 21,
    'username' => 'deploy',
    'password' => getenv('FTP_PASSWORD'),
    'url'      => 'https://cdn.example.com/',
    'ssl'      => true,   // explicit FTPS
    'passive'  => true,
]);

Return value and errors

Outcome	Result
Stored successfully	the File, with getURL() set
The transfer returned false	false
Could not connect	throws UploadException: FTP connection failed.
Bad credentials	throws UploadException: FTP username or password incorrect!
Validation failed	throws UploadException

use InitPHP\Upload\Exceptions\UploadException;
use InitPHP\Upload\Exceptions\UnsupportedException;

try {
    $upload = new Upload(new FTPAdapter($credentials, $options));
    $stored = $upload->setFile($file)->to('gallery');
} catch (UnsupportedException $e) {
    // ext-ftp is not installed
} catch (UploadException $e) {
    // connection, authentication or validation problem
}

(UnsupportedException extends UploadException, so a single catch (UploadException $e) also catches the missing-extension case.)

Tips

• Store secrets in the environment, not in source — see the example's getenv('FTP_PASSWORD').
• url is only used to build the public URL string; it usually points at the HTTP(S) host that serves the FTP root, which may differ from host.
• A timeout that is too low can make large uploads fail mid-transfer; raise it for big files or slow links.

See also

• Validation · Error Handling
• Local Adapter · S3 Adapter
• Troubleshooting