To understand this, just look at the main code's call to the function and the function definition -
// function call in the main code
searchFolder( TOP_LEVEL_DIR, $folderName, $matches );
// function definition
function searchFolder( $current_folder, $folder_to_find, &$matches )
{
if ( !( $handle = opendir( $current_folder ) ) ) die( "Cannot open $current_folder." );
while ( $entry = readdir( $handle ) ) {
if ( is_dir( "$current_folder/$entry" ) ) {
if ( $entry != "." && $entry != ".." ) {
// This entry is a valid folder
// If it matches our folder name, add it to the list of matches
if ( $entry == $folder_to_find ) $matches[] = "$current_folder/$entry";
// Search this folder
searchFolder( "$current_folder/$entry", $folder_to_find, $matches );
}
}
}
closedir( $handle );
}
The key to understanding how a recursive function works is to understand that each call to the function creates a new local set of variables. The three variables that have been defined for the parameters -$current_folder, $folder_to_find, $matches, and the $handle and $entry variables are all new and separate for each call to the function. Technically, this is accomplished through storing the data on a LIFO (last in first out) stack.
When the main code calls the function, it supplies three call time VALUES as parameters. The first value happens to come from a defined constant and the other two happen to come from main program variables. These VALUES are assigned to the current local $current_folder, $folder_to_find, and $matches (this is actually assigned a reference to the supplied value due to the &) variables.
The code in the function runs to open the folder given by the value in the current local $current_folder variable, to match any current entry given by the value in the current local $folder_to_find variable, and stores any matching path, as an array entry, in the current local $matches variable, which is a reference to the value that was initially supplied when the function was called, which is a main program array variable.
When the code inside the function finds a entry that is a folder, it calls the searchFolder() function recursively and passes the following three call time VALUES - "$current_folder/$entry", $folder_to_find, and $matches. The second and third parameters are just being passed through, as is. What's important is the first parameter. It's made up of the current local $current_folder and the $entry that was found, and it becomes the $current_folder input to the next invocation of the searchFolder() function.
This repeats for each entry that's found that is a folder.
When any level of the the searchFolder() function is done looping over the directory it was given as its current local $current_folder value, it returns to the calling code. This pops the local variables off of the stack. This leaves the stack in the state it was in when the function was called. If the calling code happens to be a lower level of the searchFolder() function, as far as that instance of the function knows, it's still trying to loop over the directory it was given as its current local $current_folder value.
This repeats back until the instance of the function that was called by the main code finishes looping over the initial starting directory it was given as its current local $current_folder value.
