Check buildProvider when installing for bundled PHP extensions

asgrim · asgrim · commit 2e0ac3ff31eb · 2025-07-28T19:52:53.000+01:00
diff --git a/src/Command/BuildCommand.php b/src/Command/BuildCommand.php
@@ -9,6 +9,7 @@
 use Php\Pie\ComposerIntegration\PieComposerFactory;
 use Php\Pie\ComposerIntegration\PieComposerRequest;
 use Php\Pie\ComposerIntegration\PieOperation;
+use Php\Pie\DependencyResolver\BundledPhpExtensionRefusal;
 use Php\Pie\DependencyResolver\DependencyResolver;
 use Php\Pie\DependencyResolver\InvalidPackageName;
 use Php\Pie\DependencyResolver\UnableToResolveRequirement;
@@ -88,6 +89,11 @@ public function execute(InputInterface $input, OutputInterface $output): int
                 $targetPlatform,
                 $this->container,
             );
+        } catch (BundledPhpExtensionRefusal $bundledPhpExtensionRefusal) {
+            $output->writeln('');
+            $output->writeln('<comment>' . $bundledPhpExtensionRefusal->getMessage() . '</comment>');
+
+            return self::INVALID;
         }
 
         $output->writeln(sprintf('<info>Found package:</info> %s which provides <info>%s</info>', $package->prettyNameAndVersion(), $package->extensionName()->nameWithExtPrefix()));
diff --git a/src/Command/DownloadCommand.php b/src/Command/DownloadCommand.php
@@ -9,6 +9,7 @@
 use Php\Pie\ComposerIntegration\PieComposerFactory;
 use Php\Pie\ComposerIntegration\PieComposerRequest;
 use Php\Pie\ComposerIntegration\PieOperation;
+use Php\Pie\DependencyResolver\BundledPhpExtensionRefusal;
 use Php\Pie\DependencyResolver\DependencyResolver;
 use Php\Pie\DependencyResolver\InvalidPackageName;
 use Php\Pie\DependencyResolver\UnableToResolveRequirement;
@@ -90,6 +91,11 @@ public function execute(InputInterface $input, OutputInterface $output): int
                 $targetPlatform,
                 $this->container,
             );
+        } catch (BundledPhpExtensionRefusal $bundledPhpExtensionRefusal) {
+            $output->writeln('');
+            $output->writeln('<comment>' . $bundledPhpExtensionRefusal->getMessage() . '</comment>');
+
+            return self::INVALID;
         }
 
         $output->writeln(sprintf('<info>Found package:</info> %s which provides <info>%s</info>', $package->prettyNameAndVersion(), $package->extensionName()->nameWithExtPrefix()));
diff --git a/src/Command/InfoCommand.php b/src/Command/InfoCommand.php
@@ -7,6 +7,7 @@
 use Php\Pie\ComposerIntegration\PieComposerFactory;
 use Php\Pie\ComposerIntegration\PieComposerRequest;
 use Php\Pie\ComposerIntegration\PieOperation;
+use Php\Pie\DependencyResolver\BundledPhpExtensionRefusal;
 use Php\Pie\DependencyResolver\DependencyResolver;
 use Php\Pie\DependencyResolver\InvalidPackageName;
 use Php\Pie\DependencyResolver\UnableToResolveRequirement;
@@ -87,6 +88,11 @@ public function execute(InputInterface $input, OutputInterface $output): int
                 $targetPlatform,
                 $this->container,
             );
+        } catch (BundledPhpExtensionRefusal $bundledPhpExtensionRefusal) {
+            $output->writeln('');
+            $output->writeln('<comment>' . $bundledPhpExtensionRefusal->getMessage() . '</comment>');
+
+            return self::INVALID;
         }
 
         $output->writeln(sprintf('<info>Found package:</info> %s which provides <info>%s</info>', $package->prettyNameAndVersion(), $package->extensionName()->nameWithExtPrefix()));
diff --git a/src/Command/InstallCommand.php b/src/Command/InstallCommand.php
@@ -9,6 +9,7 @@
 use Php\Pie\ComposerIntegration\PieComposerFactory;
 use Php\Pie\ComposerIntegration\PieComposerRequest;
 use Php\Pie\ComposerIntegration\PieOperation;
+use Php\Pie\DependencyResolver\BundledPhpExtensionRefusal;
 use Php\Pie\DependencyResolver\DependencyResolver;
 use Php\Pie\DependencyResolver\InvalidPackageName;
 use Php\Pie\DependencyResolver\UnableToResolveRequirement;
@@ -103,6 +104,11 @@ public function execute(InputInterface $input, OutputInterface $output): int
                 $targetPlatform,
                 $this->container,
             );
+        } catch (BundledPhpExtensionRefusal $bundledPhpExtensionRefusal) {
+            $output->writeln('');
+            $output->writeln('<comment>' . $bundledPhpExtensionRefusal->getMessage() . '</comment>');
+
+            return self::INVALID;
         }
 
         $output->writeln(sprintf('<info>Found package:</info> %s which provides <info>%s</info>', $package->prettyNameAndVersion(), $package->extensionName()->nameWithExtPrefix()));
diff --git a/src/DependencyResolver/BundledPhpExtensionRefusal.php b/src/DependencyResolver/BundledPhpExtensionRefusal.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Php\Pie\DependencyResolver;
+
+use RuntimeException;
+
+use function sprintf;
+
+use const PHP_EOL;
+
+class BundledPhpExtensionRefusal extends RuntimeException
+{
+    public static function forPackage(Package $package): self
+    {
+        return new self(sprintf(
+            'Bundled PHP extension %s should be installed by your distribution, not by PIE.%s%sCombining installation methods of bundled PHP extensions can lead to confusing and unintended consequences.%s%sIf you are really sure, you want to install %s using PIE, re-run the command with the --force flag.',
+            $package->name(),
+            PHP_EOL,
+            PHP_EOL,
+            PHP_EOL,
+            PHP_EOL,
+            $package->name(),
+        ));
+    }
+}
diff --git a/src/DependencyResolver/Package.php b/src/DependencyResolver/Package.php
@@ -163,6 +163,11 @@ public function extensionName(): ExtensionName
         return $this->extensionName;
     }
 
+    public function isBundledPhpExtension(): bool
+    {
+        return str_starts_with($this->name(), 'php/');
+    }
+
     public function name(): string
     {
         return $this->name;
diff --git a/src/DependencyResolver/ResolveDependencyWithComposer.php b/src/DependencyResolver/ResolveDependencyWithComposer.php
@@ -12,14 +12,17 @@
 use Php\Pie\ExtensionType;
 use Php\Pie\Platform\TargetPlatform;
 use Php\Pie\Platform\ThreadSafetyMode;
+use Symfony\Component\Console\Output\OutputInterface;
 
 use function in_array;
 use function preg_match;
+use function sprintf;
 
 /** @internal This is not public API for PIE, so should not be depended upon unless you accept the risk of BC breaks */
 final class ResolveDependencyWithComposer implements DependencyResolver
 {
     public function __construct(
+        private readonly OutputInterface $output,
         private readonly QuieterConsoleIO $arrayCollectionIo,
     ) {
     }
@@ -62,6 +65,7 @@ public function __invoke(
 
         $piePackage = Package::fromComposerCompletePackage($package);
 
+        $this->assertBuildProviderProvidersBundledExtensions($targetPlatform, $piePackage, $forceInstallPackageVersion);
         $this->assertCompatibleOsFamily($targetPlatform, $piePackage);
         $this->assertCompatibleThreadSafetyMode($targetPlatform->threadSafety, $piePackage);
 
@@ -95,4 +99,48 @@ private function assertCompatibleOsFamily(TargetPlatform $targetPlatform, Packag
             );
         }
     }
+
+    private function assertBuildProviderProvidersBundledExtensions(TargetPlatform $targetPlatform, Package $piePackage, bool $forceInstallPackageVersion): void
+    {
+        if (! $piePackage->isBundledPhpExtension()) {
+            return;
+        }
+
+        $buildProvider           = $targetPlatform->phpBinaryPath->buildProvider();
+        $identifiedBuildProvider = false;
+        $note                    = '<options=bold,underscore;fg=red>Note:</> ';
+
+        if ($buildProvider === 'https://github.com/docker-library/php') {
+            $identifiedBuildProvider = true;
+            $this->output->writeln(sprintf(
+                '<comment>%sYou should probably use "docker-php-ext-install %s" instead</comment>',
+                $note,
+                $piePackage->extensionName()->name(),
+            ));
+        }
+
+        if ($buildProvider === 'Debian') {
+            $identifiedBuildProvider = true;
+            $this->output->writeln(sprintf(
+                '<comment>%sYou should probably use "apt install php%s-%s" or "apt install php-%s" (or similar) instead</comment>',
+                $note,
+                $targetPlatform->phpBinaryPath->majorMinorVersion(),
+                $piePackage->extensionName()->name(),
+                $piePackage->extensionName()->name(),
+            ));
+        }
+
+        if ($buildProvider === 'Remi\'s RPM repository <https://rpms.remirepo.net/> #StandWithUkraine') {
+            $identifiedBuildProvider = true;
+            $this->output->writeln(sprintf(
+                '<comment>%sYou should probably use "dnf install php-%s" instead</comment>',
+                $note,
+                $piePackage->extensionName()->name(),
+            ));
+        }
+
+        if ($identifiedBuildProvider && ! $forceInstallPackageVersion) {
+            throw BundledPhpExtensionRefusal::forPackage($piePackage);
+        }
+    }
 }
diff --git a/test/unit/DependencyResolver/ResolveDependencyWithComposerTest.php b/test/unit/DependencyResolver/ResolveDependencyWithComposerTest.php
@@ -30,6 +30,7 @@
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\MockObject\MockObject;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Console\Output\OutputInterface;
 
 #[CoversClass(ResolveDependencyWithComposer::class)]
 final class ResolveDependencyWithComposerTest extends TestCase
@@ -80,6 +81,7 @@ public function testPackageThatCanBeResolved(): void
         );
 
         $package = (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))($this->composer, $targetPlatform, new RequestedPackageAndVersion('asgrim/example-pie-extension', '^1.0'), false);
 
@@ -123,6 +125,7 @@ public function testPackageThatCannotBeResolvedThrowsException(array $platformOv
         $this->expectException(UnableToResolveRequirement::class);
 
         (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -161,6 +164,7 @@ public function testUnresolvedPackageCanBeInstalledWithForceOption(array $platfo
         $this->expectException(UnableToResolveRequirement::class);
 
         $package = (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -212,6 +216,7 @@ public function testZtsOnlyPackageCannotBeInstalledOnNtsSystem(): void
         $this->expectException(IncompatibleThreadSafetyMode::class);
         $this->expectExceptionMessage('This extension does not support being installed on a non-Thread Safe PHP installation');
         (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -260,6 +265,7 @@ public function testNtsOnlyPackageCannotBeInstalledOnZtsSystem(): void
         $this->expectException(IncompatibleThreadSafetyMode::class);
         $this->expectExceptionMessage('This extension does not support being installed on a Thread Safe PHP installation');
         (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -308,6 +314,7 @@ public function testExtensionCanOnlyBeInstalledIfOsFamilyIsCompatible(): void
         $this->expectException(IncompatibleOperatingSystemFamily::class);
         $this->expectExceptionMessage('This extension does not support the "linux" operating system family. It is compatible with the following families: "solaris", "darwin"');
         (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -356,6 +363,7 @@ public function testExtensionCanOnlyBeInstalledIfOsFamilyIsNotInCompatible(): vo
         $this->expectException(IncompatibleOperatingSystemFamily::class);
         $this->expectExceptionMessage('This extension does not support the "darwin" operating system family. It is incompatible with the following families: "darwin", "solaris".');
         (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))(
             $this->composer,
@@ -392,6 +400,7 @@ public function testPackageThatCanBeResolvedWithReplaceConflict(): void
         );
 
         $package = (new ResolveDependencyWithComposer(
+            $this->createMock(OutputInterface::class),
             $this->createMock(QuieterConsoleIO::class),
         ))($this->composer, $targetPlatform, new RequestedPackageAndVersion('asgrim/example-pie-extension', '^1.0'), false);
 

Original file line number	Diff line number	Diff line change
`@@ -163,6 +163,11 @@ public function extensionName(): ExtensionName`
`163`	`163`	`return $this->extensionName;`
`164`	`164`	`}`
`165`	`165`
	`166`	`+ public function isBundledPhpExtension(): bool`
	`167`	`+ {`
	`168`	`+ return str_starts_with($this->name(), 'php/');`
	`169`	`+ }`
	`170`	`+`
`166`	`171`	`public function name(): string`
`167`	`172`	`{`
`168`	`173`	`return $this->name;`