Merge pull request #1656 from hydephp/build-task-skip-feature

Add a skip feature to build tasks

RELEASE_NOTES.md

@@ -14,6 +14,7 @@ This serves two purposes:
 - Added a `Hyde::route()` helper to the `Hyde` facade in https://github.com/hydephp/develop/pull/1591
 - Added new global helper functions (`asset()`, `route()`, `url()`) in https://github.com/hydephp/develop/pull/1592
 - Added a new `Feature` enum to improve the `Features` facade in https://github.com/hydephp/develop/pull/1650
+- Added a helper to `->skip()` build tasks in https://github.com/hydephp/develop/pull/1656
 
 ### Changed
 - The `features` array in the `config/hyde.php` configuration file is now an array of `Feature` enums in https://github.com/hydephp/develop/pull/1650

docs/advanced-features/build-tasks.md

@@ -173,3 +173,22 @@ public function handle(): void
     $this->output->writeln('This is a line of text');
 }
 ```
+
+### Skipping tasks
+
+>info This feature was added in HydePHP v1.6.0
+
+If you for some reason need to skip the task during its execution, you can call the `skip()` method.
+
+```php
+public function handle(): void
+{
+    if ($this->someCondition() !== true) {
+        $this->skip('Some condition was not met');
+
+        // The task will not be executed past this point
+    }
+}
+```
+
+This will then halt the execution of the task, and display a notice with the message you provided to the console.

packages/framework/src/Framework/Features/BuildTasks/BuildTask.php

@@ -49,8 +49,14 @@ public function run(?OutputStyle $output = null): int
             $this->handle();
             $this->printFinishMessage();
         } catch (Throwable $exception) {
-            $this->writeln('<error>Failed</error>');
-            $this->writeln("<error>{$exception->getMessage()}</error>");
+            if ($exception instanceof BuildTaskSkippedException) {
+                $this->writeln('<bg=yellow>Skipped</>');
+                $this->writeln("<fg=gray> > {$exception->getMessage()}</>");
+            } else {
+                $this->writeln('<error>Failed</error>');
+                $this->writeln("<error>{$exception->getMessage()}</error>");
+            }
+
             $this->exitCode = $exception->getCode();
         }
 
@@ -84,6 +90,16 @@ public function writeln(string $message): void
         $this->output?->writeln($message);
     }
 
+    /**
+     * Write a fluent message to the output that the task is skipping and halt the execution.
+     *
+     * @throws \Hyde\Framework\Features\BuildTasks\BuildTaskSkippedException
+     */
+    public function skip(string $reason = 'Task was skipped'): void
+    {
+        throw new BuildTaskSkippedException($reason);
+    }
+
     /** Write a fluent message to the output that the task created the specified file. */
     public function createdSiteFile(string $path): static
     {

packages/framework/src/Framework/Features/BuildTasks/BuildTaskSkippedException.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Features\BuildTasks;
+
+use RuntimeException;
+
+class BuildTaskSkippedException extends RuntimeException
+{
+    public function __construct(string $message = 'Task was skipped', int $code = 0)
+    {
+        parent::__construct($message, $code);
+    }
+}

packages/framework/tests/Unit/BuildTaskSkippedExceptionTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Hyde\Framework\Testing\Unit;
+
+use Hyde\Framework\Features\BuildTasks\BuildTaskSkippedException;
+use Hyde\Testing\UnitTestCase;
+
+/**
+ * @covers \Hyde\Framework\Features\BuildTasks\BuildTaskSkippedException
+ */
+class BuildTaskSkippedExceptionTest extends UnitTestCase
+{
+    public function testItCanBeInstantiated()
+    {
+        $exception = new BuildTaskSkippedException();
+
+        $this->assertInstanceOf(BuildTaskSkippedException::class, $exception);
+    }
+
+    public function testItThrowsAnExceptionWithDefaultMessage()
+    {
+        $this->expectException(BuildTaskSkippedException::class);
+        $this->expectExceptionMessage('Task was skipped');
+
+        throw new BuildTaskSkippedException();
+    }
+
+    public function testItThrowsAnExceptionWithCustomMessage()
+    {
+        $this->expectException(BuildTaskSkippedException::class);
+        $this->expectExceptionMessage('Custom message');
+
+        throw new BuildTaskSkippedException('Custom message');
+    }
+
+    public function testDefaultExceptionCode()
+    {
+        $exception = new BuildTaskSkippedException();
+
+        $this->assertSame(0, $exception->getCode());
+    }
+
+    public function testCustomExceptionCode()
+    {
+        $exception = new BuildTaskSkippedException('Custom message', 123);
+
+        $this->assertSame(123, $exception->getCode());
+    }
+}

packages/framework/tests/Unit/BuildTaskUnitTest.php

@@ -184,6 +184,32 @@ public function testWithExecutionTime()
         $this->assertSame(' in 1,234.56ms', $task->buffer[0]);
     }
 
+    public function testTaskSkipping()
+    {
+        $task = tap(new BufferedTestBuildTask(), function (BufferedTestBuildTask $task) {
+            $task->mockHandle(function (BufferedTestBuildTask $task) {
+                $task->skip();
+            })->run();
+        });
+
+        $this->assertSame(0, $task->property('exitCode'));
+        $this->assertSame('<bg=yellow>Skipped</>', $task->buffer[1]);
+        $this->assertSame('<fg=gray> > Task was skipped</>', $task->buffer[2]);
+    }
+
+    public function testTaskSkippingWithCustomMessage()
+    {
+        $task = tap(new BufferedTestBuildTask(), function (BufferedTestBuildTask $task) {
+            $task->mockHandle(function (BufferedTestBuildTask $task) {
+                $task->skip('Custom reason');
+            })->run();
+        });
+
+        $this->assertSame(0, $task->property('exitCode'));
+        $this->assertSame('<bg=yellow>Skipped</>', $task->buffer[1]);
+        $this->assertSame('<fg=gray> > Custom reason</>', $task->buffer[2]);
+    }
+
     public function testExceptionHandling()
     {
         $task = new BufferedTestBuildTask();
@@ -217,7 +243,7 @@ class InspectableTestBuildTask extends BuildTask
     public function handle(): void
     {
         if (isset($this->mockHandle)) {
-            ($this->mockHandle)();
+            ($this->mockHandle)($this);
         } else {
             $this->wasHandled = true;
         }
@@ -248,9 +274,11 @@ public function mockClock(float $time): void
         $this->mockedEndTime = $time;
     }
 
-    public function mockHandle(Closure $handle): void
+    public function mockHandle(Closure $handle): static
     {
         $this->mockHandle = $handle;
+
+        return $this;
     }
 
     protected function stopClock(): float