We've already written a PHP guide on how to delete a directory with PHP, but in this guide we'll look at how you can delete a file with PHP in more detail, using the pre-built internal PHP function, unlink. We'll show how unlink works, the required parameters needed, and an array of typical error messages you might encounter when working with this function, all with easy-to-follow PHP code examples.
What is the PHP function unlink?
Similar to the rmdir function in PHP, the unlink function is used to remove a file instead of a folder, in PHP. This is not to be confused with the wrongly assumed 'delete' function in PHP, which does not exist. In fact, there is no 'delete' keyword in the PHP programming language. If you're looking to remove a file, folder, or variable, you should use, unlink, rmdir, or unset.
As part of the filesystem functions within PHP, unlink is a great function that programmers can use to remove files dynamically within their code. Passing a string filename to the function will delete that file from your system if using the default context stream resource. This function works in a similar way to the Unix C unlink function.
How to delete a file with PHP using the unlink function
Let's explore some code examples of how the unlink function works. In the following example, the function will return true on a success or false on a failure.
# This will remove the file, text.txt
unlink('test.txt');
If our PHP script wasn't in the same location as the file we were trying to remove, we could pass an absolute file path to the function instead of a relative path (like the one above). For that, we could use the __DIR__ magic constant, which will be the full path to the file. It's generally better practice to use an absolute, in incase, you move folders around. PHP automatically populates this constant, regardless if you moved the files to a completely different location/operating system. If the path to the file is a symlink, the symlink will be deleted, not the file. On servers where PHP is installed on Windows, to remove a symlink, you should use rmdir PHP function. Since PHP 7.3+, it is now possible to unlink files even with handles in use, whereas, before this version of PHP, it would fail. The slight change now is, that the handle must be closed before attempting to re-create the file again.
# This will remove the file, text.txt
unlink(__DIR__ . '/files/test.txt');
# Run this, to see your current directory path
var_dump(__DIR__);
If the function fails for whatever reason, it will return false. For example here, we're attempting to remove a file that doesn't exist. In this code example, we have used the touch function to create a blank file first.
# Create a blank file
touch('test.txt');
# Returns false, because 'wrong-file.txt' doesn't exist
var_dump(unlink('wrong-file.txt'));
How to fix PHP unlink permission denied
There might be times when you get a permission error when using the unlink function in PHP. There's normally a handful of reasons but let's take a look at the most common.
Incorrect file permissions
By setting the permissions to writable for everyone, you ensure PHP does in fact have permissions to remove before attempting it. You can use the built-in PHP function 'chmod', where you pass the file and octal value. Remember it always should start with a zero '0'.
# Set the permissions to everyone before removing
chmod('test.txt', 0777);
unlink('test.txt');
The handle is still open
The PHP handle on the file may still be open. If that's the case, first close the file handle, then attempt to remove the file. To do this use the fclose function in PHP, passing the file handle variable you used to open the original file.
# Ensure the handle is closed first before removing
fclose($handle);
unlink('test.txt');
The file is in fact a folder
Without manually checking, it could be that the file you are deleting is actually a folder instead of a file. Depending on what you're trying to achieve, one way is to check if the file isn't a folder using the 'is_dir' function. Wrapping this function in an IF statement, where if it returns false, you know it is a file you're working with.
# Check the file isn't a folder before removing
if (!is_dir('test.txt')) {
unlink('test.txt');
}
Or you could use 'is_file' to check it really is a file, essentially the opposite of is_dir. We'd recommend using is_file because it's quicker for other programmers to see the logic behind what's going on, like the example below, if it is a file, remove it.
# Check it is a file and not a folder before removing
if (is_file('test.txt')) {
unlink('test.txt');
}
Conclusion
Unlink is another key PHP function to have under your belt. By learning and understanding this function, along with 'rmdir', you'll be able to remove both files and folders easily in PHP. Remember there are a few differences between Unix and Windows machines, but generally, unlink should be used in cases where you need to remove a file.
- There is no 'delete' keyword in PHP
- To remove a file use unlink
- To remove a folder use rmdir
- To remove (unset) a variable at runtime, use 'unset'
- The unset function should not be used to attempt to remove a file in PHP
- If the path is a symlink, the symlink will be removed instead of the file
- Use the 'rmdir' function to remove symlinks on Windows