Server File Finder

It has happened more than once.

I am quite sure there is a certain file on the server. Yet, with the dozens of directories and many more subdirectories, it takes a long time to find it.

Or, something that has happened quite a bit during the decades I've been programming, the same file name is in more than one place on the server. In that case, every directory and subdirectory needs to be searched.

It occurred to me that perhaps some Possibilities subscribers have also experienced that frustration.

The PHP script included with the online article is designed to search the server for all occurrences of a file name.

Upload the script. Type its URL into your browser, along with the file name you are looking for. See a list of every location of a file by that name.

Partial file names may be specified.

Optionally, you can set up the PHP script to require a password.

This script should be removed from your server when you are done with it. Otherwise, hackers could use it to see what files you have and choose which they want to exploit.

Even if you elect to password the script, it is still prudent to remove it from the server when you are done using it. When you need to use it again, re-upload it to your server.

Before anything else, here is the source code for the File Finder script. Notes follow.

<?php
/*
File Finder
Version 1.0
November 7, 2021
Will Bontrager Software LLC
https://www.willmaster.com/
*/

/* One optional customization */
// If password is used, specify it 
//   at the end of the URL as
//      &password=YourPassword 
// To enable password restriction, specify 
//   a password between the quotes.
$Password = "";
/* End of optional customization */

if( empty($_GET['lookfor']) )
{
   echo <<<USAGE
<pre>
Usage (may use https instead of http):
http://{$_SERVER['HTTP_HOST']}{$_SERVER['PHP_SELF']}?lookfor=filename

"filename" may be the entire file name or part of a file name.
If the specified partial "filename" is at the beginning of the file name, 
    then prepend a ("^") caret character.
If the specified partial "filename" is at the end of the file name, 
    then append a ("\$") dollar character.

If a password is required, append &password=YourPassword to the URL 
    (changing YourPassword to the correct password).

</pre>
USAGE;
   exit;
}
if( (!empty($Password)) and $_GET['password'] != $Password ) { exit; }
echo "<pre>Looking for <b>{$_GET['lookfor']}</b>\n";
$LookFor = str_replace('^','CARRRRRROT',$_GET['lookfor']);
$LookFor = str_replace('$','DALLLLLLAR',$LookFor);
$LookFor = preg_quote($LookFor);
$LookFor = str_replace('DALLLLLLAR','$',$LookFor);
$LookFor = str_replace('CARRRRRROT','^',$LookFor);
#echo "<pre>Looking for <b>$LookFor</b>\n";
$AlreadyScanned = array();
$AlreadyScanned[__DIR__.'/.'] = true;
$AlreadyScanned[__DIR__.'/..'] = true;
$Directory = array();
$Directory[__DIR__] = true;
while( count($Directory) )
{
   $key = array_key_first($Directory);
   $Base = $key;
   $AlreadyScanned[$key] = true;
   unset($Directory[$key]);
   $fileList = scandir($key);
   foreach( $fileList as $ff )
   {
      $f = "$Base/$ff";
      if( preg_match("/$LookFor/i",$ff) ) { echo "$f<br>"; }
      if( is_dir($f) and empty($AlreadyScanned[$f]) and (!preg_match('!\.\.?$!',$f)) ) { $Directory[$f] = true; }
   }
}
echo "--DONE--</pre>";
?>

Notes —

Copy the above source code and save it as FileFinder.php (or other *.php file name, if you prefer)

There is one place that may be customized, where the optional password would be specified.

The reason for the password is to prevent hackers from using FileFinder.php while it is available on your server. They don't need to know what files you have on your server.

But the password is optional.

Whether or not you password FileFinder.php (passwords tend to be crackable), it is prudent to remove the File Finder script from your server after you are done using it.

To implement a password, specify the password between the double-quotation marks in the $Password = ""; line of the above script.

If you decide to implement passworded access, and your password contains URL-reserved characters (like "?", "#", "&", "+"), then your password needs to be URL encoded for the browser URL when you are ready to use the File Finder script. URL-Encode Text Data can be used to encode your password for use in the URL.

Using the File Finder Script

The File Finder script will look for all occurrences of the file name you specify within the directory it is uploaded into and all of that directory's subdirectories.

If you want File Finder to search all of the document directories, then upload FileFinder.php into the document root (the directory where your domain's home or index page file is at).

On the other hand, if you want to search only the image directory and its subdirectories (as an example), then upload FileFinder.php into the image directory.

Once uploaded, make a note of its URL.

To specify the file to search for, append ?lookfor=FileName to the URL. Example:

https://example.com/FileFinder.php?lookfor=FileName

Replace FileName with the file name to find.

If FileFinder.php is password protected, also append &password=YourPassword to the URL. Example:

https://example.com/FileFinder.php?lookfor=FileName&password=YourPassword

As before, replace FileName with the file name to find. And also replace YourPassword with the correct password.

When the File Finder runs, it lists the server location of each matching file name.

The file name you specify is case-insensitive. FILE.txt and file.txt both match the same file name on the server.

You may specify a partial file name, in which case File Finder matches every file with the partial file name. Example:

https://example.com/FileFinder.php?lookfor=hello

The above will match all files that contain hello (Examples: hello.php hello-everybody.html the-hellolog.csv)

For a partial file name, you can specify that the partial name is to match only when the file on the server starts with what you specified. The way to do that is to begin the partial file name with the keyboard caret ("^") character. Example:

https://example.com/FileFinder.php?lookfor=^file

The above will match all files that begin with file (Examples: file.php files.html filelog.csv)

Conversely, you can specify that the partial name is to match only when the file on the server ends with what you specified. The way to do that is to end the partial file name with the keyboard dollar ("$") character. Example:

https://example.com/FileFinder.php?lookfor=.txt$

The above will match all files that end with .txt (Examples: log.txt notes.txt my-stuff.txt)

The File Finder will look for file name matches only within the domain's document root area of the server. In other words, only wherever URLs can reach.

The script can save a lot of time for site owners with many files and directories on their server and need to find a certain file. And also developers, who often are not as familiar with a client's server as they are with their own, can do a quick search to see if certain files are available.

This article first appeared with an issue of the Possibilities newsletter.

Will Bontrager