Understanding the PHP function ftp_cdup()

When you script file transfers over FTP, you frequently need to move around the remote directory tree before you upload, download, or list files. PHP's built-in FTP extension gives you a small set of navigation functions for this, and ftp_cdup() is the one that moves up one level — the FTP equivalent of cd .. on the command line.

This chapter covers what ftp_cdup() does, its syntax and return value, a complete working example, and the gotchas worth knowing before you use it in production.

What is ftp_cdup()?

ftp_cdup() changes the current working directory on the remote FTP server to its parent directory. It does exactly one thing: go up one level. If you are in /var/www/html/uploads, calling ftp_cdup() once leaves you in /var/www/html.

It is the counterpart to ftp_chdir(), which moves into a named directory. Use ftp_chdir() to descend or jump to a path, and ftp_cdup() to step back out toward the root.

ftp_cdup() only affects the current directory tracked by your FTP session. It does not move, copy, or delete anything on the server.

Syntax

ftp_cdup(FTP\Connection $ftp): bool

Return value: true on success, false on failure (for example, if you are already at the root directory or the connection is not authenticated).

As of PHP 8.1, ftp_connect() returns an FTP\Connection object rather than a resource. The function works the same way; only the type hint changed.

How to use ftp_cdup()

Before you can call ftp_cdup(), you must:

1. Open a connection with ftp_connect().
2. Authenticate with ftp_login().
3. (Usually) switch to passive mode with ftp_pasv() so transfers work behind NAT/firewalls.

The example below logs in, descends into a sub-directory with ftp_chdir(), then uses ftp_cdup() to climb back up. It prints the working directory before and after with ftp_pwd() so you can see the effect:

<?php

$ftp = ftp_connect('ftp.example.com');
ftp_login($ftp, 'username', 'password');
ftp_pasv($ftp, true);

// Move into a sub-directory first.
ftp_chdir($ftp, 'uploads');
echo "Before: " . ftp_pwd($ftp) . PHP_EOL; // e.g. /uploads

// Step back up to the parent directory.
if (ftp_cdup($ftp)) {
    echo "After:  " . ftp_pwd($ftp) . PHP_EOL; // e.g. /
} else {
    echo "Failed to change to the parent directory" . PHP_EOL;
}

ftp_close($ftp);

Here we connect, log in, and enable passive mode. We then descend into uploads, confirm the location with ftp_pwd(), and call ftp_cdup() to return to the parent. The if check lets us react when the move fails instead of assuming it worked. Finally we release the connection with ftp_close().

Common pitfalls

• You are already at the root. Calling ftp_cdup() from the top of the tree returns false. Always check the return value rather than assuming success.
• Mistaking it for a file operation. ftp_cdup() changes your position only. To delete or rename remote items use ftp_delete() or ftp_rename().
• Warnings on failure. A failed call also emits an E-WARNING. Suppress or handle it as your error strategy requires, but never rely on suppression instead of checking the boolean result.
• Forgetting passive mode. If listings or transfers hang after navigating, you likely skipped ftp_pasv($ftp, true).

Conclusion

ftp_cdup() is the simplest navigation helper in PHP's FTP toolkit: it moves the session's current directory up one level and returns a boolean telling you whether it worked. Pair it with ftp_chdir() to move down and ftp_pwd() to confirm where you are, and you have everything needed to walk a remote directory tree reliably.

Practice