[Finder] Add a note to the followLinks method

[lkolndeep]

Add some explanations to followLinks method with a note including a little example.

[javiereguiluz]

I'm missing something here ... this note starts saying "followLinks does not resolve links" ... and ends showing that "using followLinks allow to get a fourth item". So, it was resolved, right?

[lkolndeep]

@javiereguiluz Hello Javier, the goal of the followLinks method is not to resolve paths like I was thinking before. That is why I decided to add this note in the documentation.

Resolve explanation

Consider this path /home/lkolndeep/my_web_projects/web_project_2024/testFinderFolder which contains the following files, folders and symlinks:

file1.txt  
file2.txt  
file3.txt  
folder1  
folder2  
folder3  
symlink1 (linked to file1.txt)
symlink2 (linked to file2.txt)
symlink3 (linked to file3.txt)

Suppose this code:

$finder->files()->followLinks()->in('/home/lkolndeep/my_web_projects/web_project_2024/testFinderFolder');

$listFiles = [];
if ($finder->hasResults()) {
    foreach ($finder as $file) {
        $listFiles[] = $file->getRelativePathname();
    }
}

A dd($listFiles) will give me this:

array:6 [▼
  0 => "symlink2"
  1 => "symlink1"
  2 => "symlink3"
  3 => "file1.txt"
  4 => "file3.txt"
  5 => "file2.txt"
]

As you can see, we have in the list symlink1, symlink2 and symlink3 which are not resolved. If these three symlinks would have been resolved, we would have had this instead:

array:6 [▼
  0 => "file2.txt"
  1 => "file1.txt"
  2 => "file3.txt"
  3 => "file1.txt"
  4 => "file3.txt"
  5 => "file2.txt"
]

That is why I put first the sentence: Be careful, the followLinks method does not resolve links.

Testing the followLinks method in a use case

Actually, the goal of this method is to make the links to follow or traverse into directories, I give you an example:

Suppose we have the same path /home/lkolndeep/my_web_projects/web_project_2024/testFinderFolder but with these following files, folders and symlinks:

file1.txt
file2.txt
folder1 (which contains subfile1.txt)
folder2 (which contains subfile2.txt)
symlink1 (linked to file1.txt)
symlink2 (linked to file2.txt)
foldersymlink1 (linked to folder1)
foldersymlink2 (linked to folder2)

Case without the followLinks method

Here, the code without the followLinks method:

$finder = new Finder();
$finder->files()->in('/home/lkolndeep/my_web_projects/web_project_2024/testFinderFolder');

$listFiles = [];
if ($finder->hasResults()) {
    foreach ($finder as $file) {
        $listFiles[] = $file->getRelativePathname();
    }
}

Here, dd($listFiles); gives me:

 array:6 [▼
  0 => "folder2/subfile2.txt"
  1 => "symlink2"
  2 => "symlink1"
  3 => "file1.txt"
  4 => "file2.txt"
  5 => "folder1/subfile1.txt"
]

Case with the followLinks method

Now, we add the followLinks method in the code:

$finder = new Finder();
$finder->followLinks()->files()->in('/home/lkolndeep/my_web_projects/web_project_2024/testFinderFolder');

$listFiles = [];
if ($finder->hasResults()) {
    foreach ($finder as $file) {
        $listFiles[] = $file->getRelativePathname();
    }
}

dd($listFiles); gives us now another result:

 array:8 [▼
  0 => "folder2/subfile2.txt"
  1 => "symlink2"
  2 => "symlink1"
  3 => "foldersymlink2/subfile2.txt"
  4 => "file1.txt"
  5 => "file2.txt"
  6 => "foldersymlink1/subfile1.txt"
  7 => "folder1/subfile1.txt"
]

We can notice that compared to the above result, there are two more elements which have been added:

foldersymlink2/subfile2.txt
foldersymlink1/subfile1.txt

It means that the links foldersymlink1 and foldersymlink2 follow the directories thanks the followLinks method.

We must be careful of the meanings: resolve != follow.

For your information, I just pushed force the branch again because of a spelling mistake. I put tranversed instead of traversed.

[javiereguiluz]

Stephan, thanks a lot for the nice and detailed explanation. Now I fully understand the issue and I agree that we should explain this with more detail to help readers.

However, I didn't like the original proposal based on a long text-based note. I think it's difficult to fully understand it. In contrast, I liked a lot the examples that you used in your explanation ... so, while merging, I reword this entirely to show a simple file/dir example with symlinks and a short explanation of the differences when suing or not the followLinks() method.

See 1e880ca

[lkolndeep]

@javiereguiluz Ok, Javier. Thank you very much!