Improve stream wrapper support #12396

BrianHenryIE · 2025-05-02T04:54:35Z

realpath() always returns false for stream wrappers. This PR changes:

Factory and AutoloadGenerator to use the existing Composer\Util\Platform::realpath() function instead of PHP's realpath()
Filesystem::isAbsolutePath() to return true for stream wrappers' paths

See:

On Windows, don't rely on the OS to find executables #12180 –– added Platform::realpath(), released 2.8.3, Nov 2024
Always treat stream wrappers as absolute paths class-map-generator#18 – similar change
Add "realpath" support for custom stream wrapper php/php-src#12118 – root issue

PhpStan CI check fails for SuggestedPackagesReporter.php which is not related to this PR.

Edit:

There are an additional ~58 uses of regular realpath() in the code (grep -rn src -e "[^t:]realpath(" | grep -v '//' | grep -v "\s*\*" | wc -l), across 30 files (grep -rl src -e "[^t:]realpath(" | wc -l). An okay find & replace regex for PhpStorm is (^((?!//|\*).)*(?<!function |get|::|>))(realpath\(), $1Platform::$3 but it has some false positives, particularly BinaryInstaller's $globalsCode string, and the files may need use Composer\Util\Platform; added.

And in AutoloadGenerator:

composer/src/Composer/Autoload/AutoloadGenerator.php

Lines 214 to 217 in 85ff84d

    
           // Do not remove double realpath() calls. 
        
           // Fixes failing Windows realpath() implementation. 
        
           // See https://bugs.php.net/bug.php?id=72738 
        
           $basePath = $filesystem->normalizePath(realpath(realpath(Platform::getCwd())));

Maybe the double-realpath call should be moved into Platform::realpath() and the Platform::getCwd() should always return its realpath()?

composer/class-map-generator#18

tests/Composer/Test/Util/FilesystemTest.php

Seldaek · 2025-05-12T19:02:22Z

src/Composer/Util/Filesystem.php

+        return strpos($path, '/') === 0
+               || substr($path, 1, 1) === ':'
+               || strpos($path, '\\\\') === 0
+               || Preg::isMatch($this->streamWrappersRegex, $path);


I guess this should be used inside Platform::realpath for the PR to have any effect?

No. This change is for places where a non-absolute path is prepended with the working dir, e.g.

composer/src/Composer/Autoload/AutoloadGenerator.php

Line 347 in 85ff84d

$dir = $filesystem->normalizePath($filesystem->isAbsolutePath($dir) ? $dir : $basePath.'/'.$dir);

which is unnecessary for stream paths.

That said, I do need to look closer at where it is used, e.g.

composer/src/Composer/Repository/Vcs/SvnDriver.php

Lines 364 to 366 in 85ff84d

if ($fs->isAbsolutePath($url)) {

return 'file://' . strtr($url, '\\', '/');

}

Seldaek · 2025-05-12T19:07:45Z

Maybe the double-realpath call should be moved into Platform::realpath() and the Platform::getCwd() should always return its realpath()?

Per the linked bug yes maybe we should always realpath n+1 times on windows, for as long as we get a new path, to make sure we resolve junctions.. On linux the double realpath is useless.

As for Platform::getCwd I do not think it should realpath, as you don't always want to realpath it AFAIR.

There are an additional ~58 uses of regular realpath()

I guess those could be modified too for consistency.

…fixed

BrianHenryIE · 2025-05-13T05:50:06Z

src/Composer/Util/Platform.php

@@ -56,13 +56,19 @@ public static function getCwd(bool $allowEmpty = false): string

    /**
     * Infallible realpath version that falls back on the given $path if realpath is not working
+     *
+     * NB: Do not remove recursive `realpath()` calls. Fixes failing Windows `realpath()` implementation.
+     * @see https://bugs.php.net/bug.php?id=72738
     */
    public static function realpath(string $path): string
    {
        $realPath = realpath($path);
        if ($realPath === false) {
            return $path;


Suggested change

return $path;

return file_exists($realPath) || is_dir($realpath);

I was applying the realpath() to Platform::realpath() change across the other cases, and they are sometimes followed by if($realpathResult === false){ } blocks. E.g.

composer/src/Composer/Package/Archiver/ArchivableFilesFinder.php

Lines 50 to 53 in 85ff84d

$sourcesRealPath = realpath($sources);

if ($sourcesRealPath === false) {

throw new \RuntimeException('Could not realpath() the source directory "'.$sources.'"');

}

I'm thinking Platform::realpath() should return false if the path is incorrect, which is inherent in a realpath('/does/not/exist') call, and which the stream wrapper should handle correctly.

(and revert 198a7ea)

I need to look at the original reason Platform::realpath() was introduced: nicolas-grekas@3d1fb9d

Any suggestion on writing tests on this? I often use antecedent/patchwork which allows redefining built in PHP functions. Although I see composer/composer is using PHPUnit in an unconventional way.

I have applied Platform::realpath() wherever it was not followed by a false check: d1081a3

I'm thinking Platform::realpath() should return false if the path is incorrect, which is inherent in a realpath('/does/not/exist') call, and which the stream wrapper should handle correctly.

Yes, this complicates Platform::realpath() usage.. Ideally we avoid returning false, because checking for it everywhere is a pain. I can see with stream wrappers it's probably more likely to return false, but what are conditions where they would do that? Can we recover from this or should we just throw?

The fallback to return $path; that we currently have in Platform::realpath is because in theory realpath shouldn't fail when the path exists, and we don't call it if the path doesn't exist AFAIK. I have never been able to conclusively say what might trigger a false otherwise, so I put this fallback in place and nobody ever complained so either it isn't used or it works 🤷🏻‍♂️ .

I'd probably be fine throwing in case false is returned, and then we see what happens in the real world, if it causes issues we can still revert to falling back for non-stream-wrapper paths I guess to restore the previous behavior.

Stream wrapper usage is definitely very fringe, so I am a bit worried of degrading the overall experience just to fix this.

Any suggestion on writing tests on this? I often use antecedent/patchwork which allows redefining built in PHP functions. Although I see composer/composer is using PHPUnit in an unconventional way.

You should be able to use patchwork as it requires php 7.1+, so just give it a shot I guess..

Seldaek · 2025-05-13T07:15:59Z

src/Composer/Autoload/AutoloadGenerator.php

-                        if (false === $resolvedPath) {
-                            continue;
-                        }
+                        $resolvedPath = Platform::realpath($installPath . '/' . $updir);


This is a special case where we aren't checking file_exists before, and thus using the false return value as indication that the path doesn't exist and can be skipped.

So I'd probably add a file_exists check before, assuming realpath is changed to throw on failure. Or try/catch to be safer perhaps, because I suppose even if the file exists it might still throw in some weird conditions.

Seldaek · 2025-05-13T07:17:28Z

src/Composer/Compiler.php

@@ -142,7 +143,7 @@ public function compile(string $pharFile = 'composer.phar'): void
            __DIR__ . '/../../vendor/symfony/console/Resources/bin/hiddeninput.exe',
            __DIR__ . '/../../vendor/symfony/console/Resources/completion.bash',
        ] as $file) {
-            $extraFiles[$file] = realpath($file);
+            $extraFiles[$file] = Platform::realpath($file);


This one should be moved below the file_exists check that happens after realpath..

Seldaek · 2025-05-13T07:21:36Z

src/Composer/Console/Application.php

@@ -199,7 +199,7 @@ public function doRun(InputInterface $input, OutputInterface $output): int
            && $input->hasParameterOption('-h', true) === false
        ) {
            $dir = dirname(Platform::getCwd(true));
-            $home = realpath(Platform::getEnv('HOME') ?: Platform::getEnv('USERPROFILE') ?: '/');
+            $home = Platform::realpath(Platform::getEnv('HOME') ?: Platform::getEnv('USERPROFILE') ?: '/');


This one too I'd probably try/catch and use $home = Platform::realpath('/') as fallback. Because otherwise if HOME points to an invalid dir somehow this will blow up in bad ways for people, and this is a fairly hot code path so I'd rather not risk major issues.

Seldaek · 2025-05-13T07:23:32Z

src/Composer/Util/Platform.php

     */
    public static function realpath(string $path): string
    {
        $realPath = realpath($path);
        if ($realPath === false) {
            return $path;
        }
+        if ($realPath !== $path) {


Suggested change

if ($realPath !== $path) {

if (self::isWindows() && $realPath !== $path) {

src/Composer/Util/Filesystem.php

Co-authored-by: Jordi Boggiano <j.boggiano@seld.be>

BrianHenryIE added 4 commits May 1, 2025 21:34

use Composer\Util\Platform::realpath()

2ab3d1e

use Composer\Util\Platform::realpath()

708c809

Always treat stream wrappers as absolute paths

e8a516f

composer/class-map-generator#18

Remove false check which no longer can evaluate to false

198a7ea

BrianHenryIE mentioned this pull request May 2, 2025

Add SymlinkProtectFilesystemAdapter BrianHenryIE/strauss#170

Open

7 tasks

Add ::testIsAbsolutePath()

9f03eba

BrianHenryIE marked this pull request as ready for review May 2, 2025 07:27

Seldaek reviewed May 12, 2025

View reviewed changes

tests/Composer/Test/Util/FilesystemTest.php Outdated Show resolved Hide resolved

Seldaek reviewed May 12, 2025

View reviewed changes

Seldaek added this to the 2.9 milestone May 12, 2025

BrianHenryIE added 2 commits May 12, 2025 21:52

Do not treat file:// paths as absolute path without check it un-pre…

ed968c0

…fixed

Recursively call ::realpath() until $path does not change

27fac4b

BrianHenryIE commented May 13, 2025

View reviewed changes

Replace realpath() with Platform::realpath()

d1081a3

Seldaek reviewed May 13, 2025

View reviewed changes

Seldaek 6D4E reviewed May 13, 2025

View reviewed changes

src/Composer/Util/Filesystem.php Outdated Show resolved Hide resolved

Update src/Composer/Util/Filesystem.php

4b5129b

Co-authored-by: Jordi Boggiano <j.boggiano@seld.be>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Improve stream wrapper support #12396

Improve stream wrapper support #12396

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

	// Do not remove double realpath() calls.
	// Fixes failing Windows realpath() implementation.
	// See https://bugs.php.net/bug.php?id=72738
	$basePath = $filesystem->normalizePath(realpath(realpath(Platform::getCwd())));

	if ($fs->isAbsolutePath($url)) {
	return 'file://' . strtr($url, '\\', '/');
	}

	return $path;
	return file_exists($realPath) \|\| is_dir($realpath);

	$sourcesRealPath = realpath($sources);
	if ($sourcesRealPath === false) {
	throw new \RuntimeException('Could not realpath() the source directory "'.$sources.'"');
	}

	if ($realPath !== $path) {
	if (self::isWindows() && $realPath !== $path) {

Uh oh!

Improve stream wrapper support #12396

Are you sure you want to change the base?

Improve stream wrapper support #12396

Uh oh!

Conversation

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!