feat: force flag

README.md

@@ -28,7 +28,7 @@ use Esign\InstallCommand\ValueObjects\PublishableFolder;
 
 class MyInstallCommand extends InstallCommand
 {
-    protected $signature = 'my-install-command';
+    protected $signature = 'my-install-command {--force : Overwrite or re-append existing files}';
     protected $description = 'Publish my stubs and install my packages';
 
     protected function publishableFiles(): array
@@ -74,6 +74,34 @@ class MyInstallCommand extends InstallCommand
 }
 ```
 
+### Publishing behavior
+
+By default, file publishing is conservative:
+
+- `PublishableFile`: publishes the file only when the target file does not already exist.
+- `PublishableFolder`: evaluates files inside the folder individually. Missing files are published, existing files are skipped.
+- `AppendableFile`: appends content when the target file does not exist yet, or when the appendable content is not already present.
+
+If you run the command with `--force`, the installer becomes aggressive:
+
+- existing published files are overwritten
+- existing files inside published folders are overwritten
+- appendable content is appended again, even if it is already present
+
+### Publish overview
+
+After publishing files, the command prints an overview of what happened:
+
+```text
+📄 Publish overview: 3 published, 1 skipped.
+Published files:
+ + /path/to/source.stub -> /path/to/target.php
+Skipped files:
+ - /path/to/source.stub -> /path/to/target.php
+```
+
+This makes it easier to see which files were created, overwritten, appended, or skipped during installation.
+
 
 ### Testing
 

src/InstallCommand.php

@@ -11,8 +11,10 @@
 use Esign\InstallCommand\ValueObjects\NodePackage;
 use Esign\InstallCommand\ValueObjects\PublishableFile;
 use Esign\InstallCommand\ValueObjects\PublishableFolder;
+use Esign\InstallCommand\ValueObjects\PublishResult;
 use Illuminate\Console\Command;
 use Illuminate\Process\Exceptions\ProcessFailedException;
+use Illuminate\Support\Collection;
 
 abstract class InstallCommand extends Command
 {
@@ -46,40 +48,71 @@ public function handle(
     protected function installFiles(): void
     {
         $fileCollection = collect($this->publishableFiles());
+        $force = (bool) $this->option('force');
+        $publishResults = [];
 
         $this->info("🗄 Installing files...");
 
         $fileCollection
             ->filter(fn ($publishableFile) => $publishableFile instanceof PublishableFile)
-            ->each(function (PublishableFile $publishableFile) {
-                $this->fileInstaller->publishFile(
+            ->each(function (PublishableFile $publishableFile) use ($force, &$publishResults) {
+                $publishResults[] = $this->fileInstaller->publishFile(
                     path: $publishableFile->path,
-                    target: $publishableFile->target
+                    target: $publishableFile->target,
+                    force: $force
                 );
             });
 
         $fileCollection
             ->filter(fn ($publishableFile) => $publishableFile instanceof PublishableFolder)
-            ->each(function (PublishableFolder $publishableFolder) {
-                $this->fileInstaller->publishFolder(
+            ->each(function (PublishableFolder $publishableFolder) use ($force, &$publishResults) {
+                $folderPublishResults = $this->fileInstaller->publishFolder(
                     path: $publishableFolder->path,
-                    target: $publishableFolder->target
+                    target: $publishableFolder->target,
+                    force: $force
                 );
+
+                $publishResults = [...$publishResults, ...$folderPublishResults];
             });
 
         $fileCollection
             ->filter(fn ($publishableFile) => $publishableFile instanceof AppendableFile)
-            ->each(function (AppendableFile $appendableFile) {
-                $this->fileInstaller->appendToFile(
+            ->each(function (AppendableFile $appendableFile) use ($force, &$publishResults) {
+                $publishResults[] = $this->fileInstaller->appendToFile(
                     path: $appendableFile->path,
                     target: $appendableFile->target,
                     search: $appendableFile->search,
+                    force: $force
                 );
             });
 
+        $this->displayPublishResults(collect($publishResults));
+
         $this->info("✅ Successfully installed files.");
     }
 
+    protected function displayPublishResults(Collection $publishResults): void
+    {
+        $publishedResults = $publishResults->filter(fn (PublishResult $publishResult) => $publishResult->published);
+        $skippedResults = $publishResults->filter(fn (PublishResult $publishResult) => !$publishResult->published);
+
+        $this->info(sprintf(
+            '📄 Publish overview: %d published, %d skipped.',
+            $publishedResults->count(),
+            $skippedResults->count()
+        ));
+
+        if ($publishedResults->isNotEmpty()) {
+            $this->line('Published files:');
+            $publishedResults->each(fn (PublishResult $publishResult) => $this->line(" + {$publishResult->path} -> {$publishResult->target}"));
+        }
+
+        if ($skippedResults->isNotEmpty()) {
+            $this->line('Skipped files:');
+            $skippedResults->each(fn (PublishResult $publishResult) => $this->line(" - {$publishResult->path} -> {$publishResult->target}"));
+        }
+    }
+
     protected function installComposerPackages(): void
     {
         $composerPackageCollection = collect($this->composerPackages());

src/Installers/FileInstaller.php

@@ -2,16 +2,22 @@
 
 namespace Esign\InstallCommand\Installers;
 
+use Esign\InstallCommand\ValueObjects\PublishResult;
 use Illuminate\Filesystem\Filesystem;
+use SplFileInfo;
 
 class FileInstaller
 {
     public function __construct(
         protected Filesystem $filesystem,
     ) {}
 
-    public function publishFile(string $path, string $target): void
+    public function publishFile(string $path, string $target, bool $force = true): PublishResult
     {
+        if ($this->filesystem->exists($target) && !$force) {
+            return PublishResult::skipped(path: $path, target: $target);
+        }
+
         $this->filesystem->ensureDirectoryExists(
             path: dirname($target)
         );
@@ -20,31 +26,53 @@ public function publishFile(string $path, string $target): void
             path: $path,
             target: $target,
         );
+
+        return PublishResult::published(path: $path, target: $target);
     }
 
-    public function publishFolder(string $path, string $target): void
+    /** @return array<PublishResult> */
+    public function publishFolder(string $path, string $target, bool $force = true): array
     {
-        $this->filesystem->ensureDirectoryExists(
-            path: $target
-        );
+        $sourceDirectory = rtrim($path, DIRECTORY_SEPARATOR);
+        $targetDirectory = rtrim($target, DIRECTORY_SEPARATOR);
 
-        $this->filesystem->copyDirectory(
-            directory: $path,
-            destination: $target,
-        );
+        return collect($this->filesystem->allFiles($sourceDirectory))
+            ->map(function (SplFileInfo $sourceFile) use ($sourceDirectory, $targetDirectory, $force) {
+                $sourcePath = $sourceFile->getPathname();
+                $relativePath = ltrim(str_replace($sourceDirectory, '', $sourcePath), DIRECTORY_SEPARATOR);
+                $targetPath = $targetDirectory . DIRECTORY_SEPARATOR . $relativePath;
+
+                return $this->publishFile($sourcePath, $targetPath, $force);
+            })
+            ->all();
     }
 
-    public function appendToFile(string $path, string $target, ?string $search): void
+    public function appendToFile(string $path, string $target, ?string $search, bool $force = true): PublishResult
     {
+        $contentToAppend = $this->filesystem->get($path);
+
+        if (!$this->filesystem->exists($target)) {
+            $this->appendFileToEndOfFile(path: $path, target: $target);
+
+            return PublishResult::published(path: $path, target: $target);
+        }
+
+        if (!$force && $this->fileContainsString(path: $target, search: $contentToAppend)) {
+            return PublishResult::skipped(path: $path, target: $target);
+        }
+
         $noSearchResultSupplied = is_null($search);
         $searchResultNotFound = ! $this->fileContainsString(path: $target, search: $search);
 
         if ($noSearchResultSupplied || $searchResultNotFound) {
             $this->appendFileToEndOfFile(path: $path, target: $target);
-            return;
+
+            return PublishResult::published(path: $path, target: $target);
         }
 
         $this->appendFileAfterSearchResultInFile(path: $path, target: $target, search: $search);
+
+        return PublishResult::published(path: $path, target: $target);
     }
 
     public function appendFileToEndOfFile(string $path, string $target): void

src/ValueObjects/PublishResult.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Esign\InstallCommand\ValueObjects;
+
+class PublishResult
+{
+    public function __construct(
+        public string $path,
+        public string $target,
+        public bool $published,
+    ) {}
+
+    public static function published(string $path, string $target): self
+    {
+        return new self(path: $path, target: $target, published: true);
+    }
+
+    public static function skipped(string $path, string $target): self
+    {
+        return new self(path: $path, target: $target, published: false);
+    }
+}