[Filesystem] Document the Path::join() method

[OskarStark]

Fix #21163

[javiereguiluz]

this looks correct because the join() method calls canonicalize() and this turns any slashes into forward slashes. See https://github.com/symfony/symfony/blob/01f0faf9c332bda3d63e4dce05e4deaf8491cf2b/src/Symfony/Component/Filesystem/Path.php#L49-L66

My question though: is the resulting path fully valid on Windows?

[OskarStark]

Yes, the resulting path is fully valid on Windows. Windows accepts both forward slashes (/) and backslashes () as path separators in most contexts, including:

• File operations in PHP (fopen, file_get_contents, etc.)
• Command line operations
• Most Windows APIs

The canonicalization to forward slashes is actually a best practice for cross-platform compatibility. PHP's file system functions handle forward slashes correctly on Windows, automatically converting them when needed for the underlying Windows API calls.

The only exception might be when passing paths to external Windows programs that specifically require backslashes, but this is rare and can be handled with Path::normalize() when needed.

Here are some references:

1. PHP Manual on Windows file paths: https://www.php.net/manual/en/wrappers.file.php

   "On Windows, both slash (/) and backslash () are used as directory separator character."

2. Microsoft Documentation: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file

   "File I/O functions in the Windows API convert "/" to "" as part of converting the name to an NT-style name"

3. PHP source code (main/streams/plain_wrapper.c): PHP internally handles the conversion when needed for Windows file operations.

You can test this yourself on Windows:

// Both work identically on Windows:
file_exists("C:/Windows/System32");  // true
file_exists("C:\\Windows\\System32"); // true

[javiereguiluz]

Thanks Oskar!

I did some mionor tweakes while merging (6276aca) to mention that both types of slashes work on Windows.