Allow to disable the main script

doc/configuration.md

@@ -82,8 +82,19 @@ configuration file is given or the current working directory otherwise.
 
 ## Main (`main`)
 
-The main (`string`) setting is used to specify the file (relative to [`base-path`][base-path]) that will be run when the
-PHAR is executed from the command line (To not confuse with the [stub][stub] which is the PHAR bootstrapping file).
+The main (`string`|`false`) setting is used to specify the file (relative to [`base-path`][base-path]) that will be run
+when the PHAR is executed from the command line (To not confuse with the [stub][stub] which is the PHAR bootstrapping
+file).
+
+When you have a main script file that can be used as a [stub][stub], you can disable the main script by setting it to
+false:
+
+```
+{
+    "stub": "bin/acme.php",
+    "main": false
+}
+```
 
 When the parameter is not given, Box tries to guess the binary of the application with the `composer.json` file. If the
 [Composer `bin`][composer-bin] is set, Box will pick the first value provided. Otherwise it will fallback on the

res/schema.json

@@ -154,7 +154,7 @@
         },
         "main": {
             "description": "The file path to the main script.",
-            "type": "string"
+            "type": ["boolean", "string"]
         },
         "map": {
             "description": "The mapping of file system paths to phar paths.",

src/Configuration.php

@@ -43,6 +43,7 @@
 use function file_exists;
 use function Humbug\PhpScoper\create_scoper;
 use function is_array;
+use function is_bool;
 use function is_file;
 use function is_link;
 use function is_readable;
@@ -150,8 +151,8 @@ private function __construct(
         array $compactors,
         ?int $compressionAlgorithm,
         ?int $fileMode,
-        string $mainScriptPath,
-        string $mainScriptContents,
+        ?string $mainScriptPath,
+        ?string $mainScriptContents,
         MapFile $fileMapper,
         $metadata,
         string $tmpOutputPath,
@@ -178,6 +179,12 @@ private function __construct(
             )
         );
 
+        if (null === $mainScriptPath) {
+            Assertion::null($mainScriptContents);
+        } else {
+            Assertion::notNull($mainScriptContents);
+        }
+
         $this->file = $file;
         $this->alias = $alias;
         $this->basePath = $basePath;
@@ -418,13 +425,28 @@ public function getFileMode(): ?int
         return $this->fileMode;
     }
 
+    public function hasMainScript(): bool
+    {
+        return null !== $this->mainScriptPath;
+    }
+
     public function getMainScriptPath(): string
     {
+        Assertion::notNull(
+            $this->mainScriptPath,
+            'Cannot retrieve the main script path: no main script configured.'
+        );
+
         return $this->mainScriptPath;
     }
 
     public function getMainScriptContents(): string
     {
+        Assertion::notNull(
+            $this->mainScriptPath,
+            'Cannot retrieve the main script contents: no main script configured.'
+        );
+
         return $this->mainScriptContents;
     }
 
@@ -1062,11 +1084,8 @@ function (SplFileInfo $fileInfo): ?bool {
     }
 
     /**
-     * @param string   $basePath
      * @param string[] $files
      * @param string[] $directories
-     * @param string   $mainScriptPath
-     * @param Closure  $blacklistFilter
      * @param string[] $excludedPaths
      * @param string[] $devPackages
      *
@@ -1076,7 +1095,7 @@ private static function retrieveAllFiles(
         string $basePath,
         array $files,
         array $directories,
-        string $mainScriptPath,
+        ?string $mainScriptPath,
         Closure $blacklistFilter,
         array $excludedPaths,
         array $devPackages
@@ -1090,7 +1109,6 @@ function (string $packagePath) use ($basePath): string {
 
         $finder = Finder::create()
             ->files()
-            ->notPath(make_path_relative($mainScriptPath, $basePath))
             ->filter($blacklistFilter)
             ->exclude($relativeDevPackages)
             ->ignoreVCS(true)
@@ -1152,6 +1170,10 @@ function (string $packagePath) use ($basePath): string {
             ->notName('build.xml*')
         ;
 
+        if (null !== $mainScriptPath) {
+            $finder->notPath(make_path_relative($mainScriptPath, $basePath));
+        }
+
         $finder->append($files);
         $finder->in($directories);
 
@@ -1320,7 +1342,7 @@ private static function retrieveFileMode(stdClass $raw): ?int
         return null;
     }
 
-    private static function retrieveMainScriptPath(stdClass $raw, string $basePath, ?array $decodedJsonContents): string
+    private static function retrieveMainScriptPath(stdClass $raw, string $basePath, ?array $decodedJsonContents): ?string
     {
         if (isset($raw->main)) {
             $main = $raw->main;
@@ -1333,11 +1355,24 @@ private static function retrieveMainScriptPath(stdClass $raw, string $basePath,
             }
         }
 
+        if (is_bool($main)) {
+            Assertion::false(
+                $main,
+                'Cannot "enable" a main script: either disable it with `false` or give the main script file path.'
+            );
+
+            return null;
+        }
+
         return self::normalizePath($main, $basePath);
     }
 
-    private static function retrieveMainScriptContents(string $mainScriptPath): string
+    private static function retrieveMainScriptContents(?string $mainScriptPath): ?string
     {
+        if (null === $mainScriptPath) {
+            return null;
+        }
+
         $contents = file_contents($mainScriptPath);
 
         // Remove the shebang line: the shebang line in a PHAR should be located in the stub file which is the real
@@ -1429,12 +1464,14 @@ private static function retrieveMetadata(stdClass $raw)
     /**
      * @return string[] The first element is the temporary output path and the second the real one
      */
-    private static function retrieveOutputPath(stdClass $raw, string $basePath, string $mainScriptPath): array
+    private static function retrieveOutputPath(stdClass $raw, string $basePath, ?string $mainScriptPath): array
     {
         if (isset($raw->output)) {
             $path = $raw->output;
         } else {
-            if (1 === preg_match('/^(?<main>.*?)(?:\.[\p{L}\d]+)?$/', $mainScriptPath, $matches)) {
+            if (null !== $mainScriptPath
+                && 1 === preg_match('/^(?<main>.*?)(?:\.[\p{L}\d]+)?$/', $mainScriptPath, $matches)
+            ) {
                 $path = $matches['main'].'.phar';
             } else {
                 // Last resort, should not happen

src/Console/Command/Build.php

@@ -17,8 +17,8 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Component\Console\Style\SymfonyStyle;
-use const E_USER_DEPRECATED;
 use function trigger_error;
+use const E_USER_DEPRECATED;
 
 /**
  * @deprecated

src/Console/Command/Compile.php

@@ -37,11 +37,6 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\VarDumper\Cloner\VarCloner;
 use Symfony\Component\VarDumper\Dumper\CliDumper;
-use const DATE_ATOM;
-use const KevinGH\Box\BOX_ALLOW_XDEBUG;
-use const PHP_EOL;
-use const POSIX_RLIMIT_INFINITY;
-use const POSIX_RLIMIT_NOFILE;
 use function array_shift;
 use function count;
 use function decoct;
@@ -62,6 +57,11 @@
 use function sprintf;
 use function strlen;
 use function substr;
+use const DATE_ATOM;
+use const KevinGH\Box\BOX_ALLOW_XDEBUG;
+use const PHP_EOL;
+use const POSIX_RLIMIT_INFINITY;
+use const POSIX_RLIMIT_NOFILE;
 
 /**
  * @final
@@ -392,8 +392,17 @@ private function addFiles(Configuration $config, Box $box, BuildLogger $logger,
         );
     }
 
-    private function registerMainScript(Configuration $config, Box $box, BuildLogger $logger): string
+    private function registerMainScript(Configuration $config, Box $box, BuildLogger $logger): ?string
     {
+        if (false === $config->hasMainScript()) {
+            $logger->log(
+                BuildLogger::QUESTION_MARK_PREFIX,
+                'No main script path configured'
+            );
+
+            return null;
+        }
+
         $main = $config->getMainScriptPath();
 
         $logger->log(
@@ -447,7 +456,7 @@ private function registerRequirementsChecker(Configuration $config, Box $box, Bu
         return true;
     }
 
-    private function registerStub(Configuration $config, Box $box, string $main, bool $checkRequirements, BuildLogger $logger): void
+    private function registerStub(Configuration $config, Box $box, ?string $main, bool $checkRequirements, BuildLogger $logger): void
     {
         if ($config->isStubGenerated()) {
             $logger->log(

src/PhpSettingsHandler.php

@@ -17,13 +17,13 @@
 use Composer\XdebugHandler\Process;
 use Composer\XdebugHandler\XdebugHandler;
 use Psr\Log\LoggerInterface;
-use const PHP_EOL;
 use function function_exists;
 use function getenv;
 use function ini_get;
 use function KevinGH\Box\FileSystem\append_to_file;
 use function sprintf;
 use function trim;
+use const PHP_EOL;
 
 /**
  * @private

tests/ConfigurationFileTest.php

@@ -17,12 +17,12 @@
 use Generator;
 use InvalidArgumentException;
 use KevinGH\Box\Json\JsonValidationException;
-use const DIRECTORY_SEPARATOR;
 use function file_put_contents;
 use function KevinGH\Box\FileSystem\dump_file;
 use function KevinGH\Box\FileSystem\make_path_absolute;
 use function KevinGH\Box\FileSystem\rename;
 use function KevinGH\Box\FileSystem\symlink;
+use const DIRECTORY_SEPARATOR;
 
 /**
  * @covers \KevinGH\Box\Configuration