W3docs
en
Log in

ftp_rawlist()

The ftp_rawlist() function is a built-in PHP function that returns a detailed listing of a directory on an FTP server. In this article, we'll discuss the

Understanding the PHP Function ftp_rawlist()

The ftp_rawlist() function returns a detailed listing of a directory on an FTP server. Each element of the array it returns is one line of the server's raw LIST output — the same text you would see in a terminal FTP client, including file permissions, owner, size, and modification date.

This page covers what ftp_rawlist() returns, its syntax, a full working example, how to parse the raw lines into usable data, recursive listings, and error handling. If you only need the file names in a directory, reach for ftp_nlist() instead — it is simpler and far easier to parse.

What is ftp_rawlist()?

ftp_rawlist() accepts two required parameters and one optional parameter:

  1. ftp_stream — the connection object (PHP 8.1+) or resource returned by ftp_connect() (or ftp_ssl_connect()).
  2. directory — the directory to list.
  3. recursive (optional) — set to true to list subdirectories recursively.

On success it returns an array of strings, where each string is one raw line of output; on failure (or for an empty directory it cannot read) it returns false.

The key thing to understand is that this output is not standardized. It is whatever the server's LIST command emits, so its format depends on the server's operating system and configuration. A Unix-style server typically returns lines that look like the output of ls -l:

drwxr-xr-x   2 owner group        4096 Jun 21 10:00 images
-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html

Windows/DOS-style servers return a different layout entirely. Because of this, ftp_rawlist() gives you full detail at the cost of having to parse free-form text yourself. Contrast it with:

  • ftp_nlist() — returns a plain array of file names only.
  • ftp_mlsd() — returns a machine-readable, structured listing (preferred when the server supports the MLSD command).

Syntax of ftp_rawlist()

The syntax of the ftp_rawlist() function is as follows:

Syntax of ftp_rawlist()

array ftp_rawlist ( FTP\Connection|resource $ftp_stream , string $directory [, bool $recursive = false ] )

The ftp_rawlist() function takes two required parameters, ftp_stream and directory. The ftp_stream parameter is the connection identifier returned by the ftp_connect() function, and the directory parameter is the directory to list. The function also has one optional parameter, recursive, which allows you to specify whether to list subdirectories.

Usage of ftp_rawlist()

To use the ftp_rawlist() function, you first need to establish a connection to the FTP server using the ftp_connect() function. Here's an example:

Usage of ftp_rawlist()

<?php

// Set up an FTP connection
$conn = ftp_connect('ftp.example.com');
if (!$conn) {
    die("Could not connect to FTP server.");
}

// Login with your FTP credentials
if (!ftp_login($conn, 'username', 'password')) {
    die("Login failed.");
}

// Get a detailed listing of the directory
$listing = ftp_rawlist($conn, '/public_html');

// Output the listing to the console
if ($listing) {
    foreach ($listing as $item) {
        echo $item . "\n";
    }
}

// Close the FTP connection
ftp_close($conn);
?>

Here we connect with ftp_connect(), authenticate with ftp_login(), retrieve the listing with ftp_rawlist(), print each raw line, and finally release the connection with ftp_close().

Tip — passive mode: Many networks and firewalls block the active-mode data channel that ftp_rawlist() uses to fetch the listing, which makes it hang or return false. If that happens, enable passive mode with ftp_pasv($conn, true) after logging in.

Security Note: Standard FTP transmits credentials and data in plaintext. For production environments, consider using ftp_ssl_connect() for explicit FTP over TLS, or switch to SFTP (via the ssh2 extension) for encrypted transfers.

Parsing the raw listing

Because each line is unstructured text, you usually want to extract individual fields. For a Unix-style server you can split each line on whitespace: the permissions are the first token, the size is the fifth, and the file name is everything after the eighth token (the name can contain spaces).

Parsing a Unix-style raw listing

<?php

// One line of typical ftp_rawlist() output:
$line = '-rw-r--r--   1 owner group       10240 Jun 20 14:32 index.html';

// Split on runs of whitespace, limited so the name stays intact.
$parts = preg_split('/\s+/', $line, 9);

$type        = $parts[0][0] === 'd' ? 'directory' : 'file';
$permissions = $parts[0];
$size        = (int) $parts[4];
$name        = $parts[8];

echo "Name:        $name\n";
echo "Type:        $type\n";
echo "Size:        $size bytes\n";
echo "Permissions: $permissions\n";
?>

This prints:

Name:        index.html
Type:        file
Size:        10240 bytes
Permissions: -rw-r--r--

If your server supports it, prefer ftp_mlsd(), which returns this data already structured so you can skip the fragile string parsing.

Listing subdirectories recursively

Passing true as the third argument tells the server to descend into subdirectories. The output then includes blank lines and directory headers (a path followed by a colon) that separate each subdirectory's contents — be ready to skip them when iterating:

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html', true);

foreach ($listing as $line) {
    if ($line === '' || str_ends_with($line, ':')) {
        // Skip blank separators and "/path/to/dir:" headers
        continue;
    }
    echo $line . "\n";
}
?>

Note that not every FTP server honors the recursive flag, and a deep tree can be slow, so test against your target server.

Error handling in ftp_rawlist()

It's important to handle errors properly when using the ftp_rawlist() function. If the function returns false, it means that the operation was unsuccessful. Here's an example of how to handle errors:

Error handling in ftp_rawlist()

<?php

// Assuming $conn is an active FTP connection
$listing = ftp_rawlist($conn, '/public_html');

if (!$listing) {
    echo "Failed to get directory listing from FTP server.\n";
}

ftp_close($conn);
?>

By handling errors appropriately and checking the return value of the function, you can ensure the success of your FTP operations using the ftp_rawlist() function.

Conclusion

ftp_rawlist() is the function to reach for when you need full file metadata — permissions, owner, size, and date — from an FTP directory, not just names. The trade-off is that its output is the server's raw, OS-dependent LIST text, so plan to parse it (or use the structured ftp_mlsd() where available). Always check the return value, enable passive mode when behind a firewall, and prefer an encrypted connection for production.

Practice

Practice
What is the function of ftp_rawlist in PHP?
What is the function of ftp_rawlist in PHP?
Was this page helpful?