rmdir()

Introduction

In PHP, the rmdir() function is used to remove a directory. It is a useful function for managing your file system. In this article, we will cover everything you need to know about the rmdir() function, including its syntax, parameters, and examples of how it can be used.

Understanding the rmdir() Function

The rmdir() function removes a directory from the file system. There is one important rule to remember: rmdir() only deletes empty directories. If the directory still contains files or subdirectories, the call fails and PHP emits an E_WARNING.

This is by design — it prevents you from wiping out a whole tree with a single mistaken call. To delete a directory that has contents, you must remove the contents first (see Example 2 below).

Other situations that cause rmdir() to fail and return false:

• The path does not exist or is a file rather than a directory.
• The script's user lacks write/execute permission on the parent directory.
• On some systems, the directory is the current working directory of the process or is otherwise in use.

Related functions you will often use alongside rmdir(): mkdir() to create directories, is_dir() to test whether a path is a directory, scandir() to list its contents, and unlink() to delete the individual files inside it.

Syntax of the rmdir() Function

rmdir(string $directory, ?resource $context = null): bool

The function returns true on success and false on failure.

Caching note: PHP caches the results of file-status checks. After creating or deleting directories in a tight loop, call clearstatcache() before re-testing the same path with is_dir() or file_exists(), otherwise you may read a stale result.

Examples of Using rmdir()

Example 1: Removing a Directory

This example checks that the path exists with is_dir() before attempting to remove it, and reports whether the call succeeded:

<?php

$directory = 'example_directory';

if (is_dir($directory)) {
    if (rmdir($directory)) {
        echo "Directory removed successfully.";
    } else {
        echo "Failed to remove directory. It may not be empty or lack permissions.";
    }
} else {
    echo "Directory does not exist.";
}

If example_directory exists and is empty, this prints Directory removed successfully. Guarding with is_dir() lets you avoid the warning rmdir() would otherwise emit for a missing path.

Example 2: Removing a Non-Empty Directory

Because rmdir() refuses to delete a directory that still has contents, you must empty it first. The idiomatic solution is a recursive helper that walks the tree, unlink()s each file, and recurses into each subdirectory before finally calling rmdir() on the now-empty directory:

<?php

function removeDirectory($dir) {
    if (!is_dir($dir)) {
        return false;
    }
    $files = array_diff(scandir($dir), ['.', '..']);
    foreach ($files as $file) {
        $path = $dir . DIRECTORY_SEPARATOR . $file;
        is_dir($path) ? removeDirectory($path) : unlink($path);
    }
    return rmdir($dir);
}

removeDirectory('example_directory');

Here array_diff(scandir($dir), ['.', '..']) strips the special . and .. entries returned by scandir(), and DIRECTORY_SEPARATOR builds paths that work on both Windows and Unix-like systems. The function returns the result of the final rmdir(), so you can check it for success.

Tip: Recursive deletion is destructive and has no undo. Validate the path before calling it (for example, refuse an empty string or the filesystem root) so a bug can't wipe out more than you intended.

Common Mistakes and Gotchas

• Trying to remove a non-empty directory. This is the most frequent cause of failure. Empty the directory first, or use the recursive helper above.
• Ignoring the return value. rmdir() returns false rather than throwing for most failures (it emits a warning). Always check the boolean result in code that matters.
• Suppressing the warning with @. @rmdir($dir) hides the message but not the failure. Prefer checking is_dir() and the return value instead.
• Forgetting permissions. Deleting a directory requires write and execute permission on its parent, not on the directory itself.

Conclusion

The rmdir() function provides a straightforward way to remove empty directories in PHP. To delete a directory that has contents, clear it first — typically with a recursive helper that combines scandir() and unlink(). Always check the return value, and guard destructive recursive deletes with a path check.

To go further, explore the companion directory functions: mkdir(), is_dir(), scandir(), and rename().

Practice