[5.x] Add --clear option for starter-kit:export (#11079)

Author: jesseleite

src/Console/Commands/StarterKitExport.php

@@ -20,7 +20,9 @@ class StarterKitExport extends Command
      *
      * @var string
      */
-    protected $signature = 'statamic:starter-kit:export { path : Specify the path you are exporting to }';
+    protected $signature = 'statamic:starter-kit:export
+        { path : Specify the path you are exporting to }
+        { --clear : Clear out everything at target export path before exporting }';
 
     /**
      * The console command description.
@@ -42,7 +44,8 @@ public function handle()
             $this->askToCreateExportPath($path);
         }
 
-        $exporter = new StarterKitExporter($path);
+        $exporter = (new StarterKitExporter($path))
+            ->clear($this->option('clear'));
 
         try {
             $exporter->export();

src/StarterKits/Exporter.php

@@ -9,12 +9,14 @@
 use Statamic\StarterKits\Exceptions\StarterKitException;
 use Statamic\Support\Arr;
 use Statamic\Support\Str;
+use Statamic\Support\Traits\FluentlyGetsAndSets;
 
 class Exporter
 {
-    use InteractsWithFilesystem;
+    use FluentlyGetsAndSets, InteractsWithFilesystem;
 
     protected $exportPath;
+    protected $clear;
     protected $files;
     protected $vendorName;
     protected $modules;
@@ -29,6 +31,14 @@ public function __construct(string $exportPath)
         $this->files = app(Filesystem::class);
     }
 
+    /**
+     * Get or set whether to clear out everything at target export path before exporting.
+     */
+    public function clear(bool $clear = false): self|bool|null
+    {
+        return $this->fluentlyGetOrSet('clear')->args(func_get_args());
+    }
+
     /**
      * Export starter kit.
      *
@@ -40,6 +50,7 @@ public function export(): void
             ->validateExportPath()
             ->validateConfig()
             ->instantiateModules()
+            ->clearExportPath()
             ->exportModules()
             ->exportConfig()
             ->exportHooks()
@@ -132,6 +143,20 @@ protected function normalizeModuleKey(string $key, string $childKey): string
         return $key !== 'top_level' ? "{$key}.modules.{$childKey}" : $childKey;
     }
 
+    /**
+     * Optionally clear out everything at target export path before exporting.
+     */
+    protected function clearExportPath()
+    {
+        if (! $this->clear) {
+            return $this;
+        }
+
+        $this->files->cleanDirectory($this->exportPath);
+
+        return $this;
+    }
+
     /**
      * Export all the modules.
      */

src/StarterKits/Installer.php

@@ -63,8 +63,6 @@ public function __construct(string $package, ?Command $console = null, ?LicenseM
     public function branch(?string $branch = null): self|bool|null
     {
         return $this->fluentlyGetOrSet('branch')->args(func_get_args());
-
-        return $this;
     }
 
     /**
@@ -73,8 +71,6 @@ public function branch(?string $branch = null): self|bool|null
     public function fromLocalRepo(bool $fromLocalRepo = false): self|bool|null
     {
         return $this->fluentlyGetOrSet('fromLocalRepo')->args(func_get_args());
-
-        return $this;
     }
 
     /**
@@ -83,8 +79,6 @@ public function fromLocalRepo(bool $fromLocalRepo = false): self|bool|null
     public function withConfig(bool $withConfig = false): self|bool|null
     {
         return $this->fluentlyGetOrSet('withConfig')->args(func_get_args());
-
-        return $this;
     }
 
     /**
@@ -101,8 +95,6 @@ public function withoutDependencies(?bool $withoutDependencies = false): self|bo
     public function withUserPrompt(bool $withUserPrompt = false): self|bool|null
     {
         return $this->fluentlyGetOrSet('withUserPrompt')->args(func_get_args());
-
-        return $this;
     }
 
     /**
@@ -119,8 +111,6 @@ public function isInteractive($isInteractive = false): self|bool|null
     public function usingSubProcess(bool $usingSubProcess = false): self|bool|null
     {
         return $this->fluentlyGetOrSet('usingSubProcess')->args(func_get_args());
-
-        return $this;
     }
 
     /**

tests/StarterKits/ExportTest.php

@@ -149,6 +149,45 @@ public function it_can_export_as_to_different_destination_path()
         $this->cleanPaths($paths);
     }
 
+    #[Test]
+    public function it_can_clear_target_export_path_with_clear_option()
+    {
+        $paths = $this->cleanPaths([
+            base_path('one'),
+            base_path('two'),
+        ]);
+
+        // Imagine this exists from previous export
+        $this->files->makeDirectory($this->exportPath('one'), 0777, true, true);
+        $this->files->put($this->exportPath('one/file.md'), 'One.');
+
+        $this->files->makeDirectory(base_path('two'), 0777, true, true);
+        $this->files->put(base_path('two/file.md'), 'Two.');
+
+        $this->setExportPaths([
+            'two/file.md',
+        ]);
+
+        $this->assertFileExists($this->exportPath('one'));
+        $this->assertFileDoesNotExist($this->exportPath('two'));
+
+        $this->exportCoolRunnings();
+
+        // Our 'one' folder should exist after exporting normally
+        $this->assertFileExists($this->exportPath('one'));
+        $this->assertFileExists($this->exportPath('two'));
+
+        $this->exportCoolRunnings(['--clear' => true]);
+
+        // But 'one' folder should exist after exporting with `--clear` option
+        $this->assertFileDoesNotExist($this->exportPath('one'));
+        $this->assertFileExists($this->exportPath('two'));
+
+        $this->exportCoolRunnings();
+
+        $this->cleanPaths($paths);
+    }
+
     #[Test]
     public function it_copies_export_config()
     {
@@ -1533,12 +1572,12 @@ private function assertConfigSameOrder($expectedConfig)
         );
     }
 
-    private function exportCoolRunnings()
+    private function exportCoolRunnings($options = [])
     {
-        return $this->artisan('statamic:starter-kit:export', [
+        return $this->artisan('statamic:starter-kit:export', array_merge([
             'path' => '../cool-runnings',
             '--no-interaction' => true,
-        ]);
+        ], $options));
     }
 
     private function assertFileHasContent($expected, $path)