When working with files and folders in PHP applications, it's common for programmers to obtain information about hard or symbolic links. These types of links can be useful for sharing files or creating shortcuts, (especially to common files) but they can also complicate file management tasks. For example, when deleting hard links or symbolic links, it could be useful in the code to check it exists before attempting the deletion. In such cases, the "linkinfo()" function in PHP can be a useful tool for obtaining information about these links and taking appropriate actions based on the results. When performing a scan of a folder structure, using something similar to PHP's "scandir" function, you don't know which are files, folders, or file links. Using something like linkinfo can help you determine what's what, but how does PHP's linkinfo function work, and what sort of information can it return?
What is the linkinfo function in PHP?
Calling the linkinfo function in PHP and giving it a path will allow you to view more information about that particular path. For example, depending on your operating system, it will return the inode number which is a unique identifier for a file or directory, used in Unix-based systems. The function takes one parameter, a string, which should be a filesystem path, and returns an int value. If the integer value is "-1", it means the link was not found or a violation was triggered in the "open.base_dir", which are the locations that PHP is allowed to browse internally. However, any value greater than -1 means the link was found and is Unix's internal inode value.
# Outputs 2051 (or similar)
echo linkinfo('index.php');
# Outputs -1
echo linkinfo('link-does-not-exist');
In Unix, an inode is the data structure in the file system, that contains metadata about files and directories. These include size, permissions, timestamps, and the location of the data's physical blocks (i.e. the file's contents). The operating system uses the inode number to locate and retrieve this information as each number is unique.
How does linkinfo work?
The PHP function linkinfo works by taking the given link provided and returning the "st_dev" field of the Unix C "stat" structure that is returned by the "lstat" system call. In other words;
- The stat structure contains information about a file (i.e. size, permissions, and timestamps)
- The "lstat" system call is a C programming language function that retrieves this information including for symbolic links
- The st_dev field of stat contains the device ID of the device that the file or link lives on
It is possible to run this function on Windows-based platforms but might result in different values such as zero for all file types. To obtain all the information the operating system holds on a file, folder, or link, you could as an alternative such as the PHP function stat, which returns an array of information that it holds on a given provided path. However, if you're working with hard links or symbolic links it's better to use linkinfo over stat as this function serves a better purpose.
If the linkinfo function returns "-1" but you're unsure why, you can use another one of PHP's built-in functions, error_get_last. This will allow you to view information on the last error that occurred in your PHP script. By dumping the contents of error_get_last, you'll see an array of data that will display, the type of error, the error message, the file where the error occurred, and the line it was triggered on. This is particularly useful if the PHP "open.base_dir" security feature is triggered.
To test this function in action, you can use both the PHP functions "symlink" and "link" to create hard and symbolic links in your file system.
Real-world use for linkinfo
There are many real-world uses for the linkinfo PHP function in web applications that you might create. One popular choice for this function is within file system management scripts. You or your DevOps may periodically want to check the status of symbolic links within the file system to ensure they're working as expected (i.e. link to the correct and valid location). Another use case is within backup tools. When backing up files and folders, it is important to know when you're working with a symbolic link as these are required to be backed up differently from regular files. If you're creating a file explorer-style application or piece of code, it is important to identify such symbolic links so you are able to relay this to your end-user with the appropriate information.
Conclusion
Using the linkinfo function in PHP can be a quick and easy way to check the existence of a file, folder, or symlink. If running this function returns, "-1", you'll know that it failed to obtain the information and/or does not exist. This function is primarily designed for& Unix-based operating systems, such as Linux or macOS.