Merge pull request #459 from hydephp/refactor-build-tasks

Rename build hooks to build tasks

RELEASE_NOTES.md

@@ -9,14 +9,17 @@ This release contains breaking changes regarding the PostBuildTasks that may req
 - Build tasks are now automatically registered when placed in the app/Actions directory and end with BuildTask.php
 
 ### Changed
-- Renamed HydeSmartDocs.php to SemanticDocumentationArticle.php
+- **Breaking changes to build hooks/tasks**:
+  - Rename BuildHookService to BuildTaskService
+  - AbstractBuildTask::handle and BuildTaskContract::handle now returns null by default instead of void. It can also return an exit code
+  - The way auxiliary build actions are handled internally has been changed to use build tasks, see [PR #453](https://github.com/hydephp/develop/pull/453)
+  - The documentation has been updated to consistently refer to these as tasks instead of hooks
 - The RSS feed related generators are now only enabled when there are blog posts
   - This means that no feed.xml will be generated, nor will there be any references (like meta tags) to it when there are no blog posts
 - The documentation search related generators are now only enabled when there are documentation pages
   - This means that no search.json nor search.html nor any references to them will be generated when there are no documentation pages
-- AbstractBuildTask::handle and BuildTaskContract::handle now returns null by default instead of void. It can also return an exit code.
-- The way auxiliary build actions are handled internally has been changed, see [PR #453](https://github.com/hydephp/develop/pull/453)
 - The methods in InteractsWithDirectories.php are now static, this does not affect existing usages
+- Renamed HydeSmartDocs.php to SemanticDocumentationArticle.php
 
 ### Deprecated
 - Deprecated ActionCommand.php as it is no longer used

docs/digging-deeper/advanced-customization.md

@@ -73,17 +73,16 @@ If you want to store the output website outside your project with an absolute pa
 StaticPageBuilder::$outputPath = '/var/www/my-project/';
 ```
 
-## Adding custom post-build hooks 🧪
->info This feature should not be in danger of breaking things. However, it was added very recently and the implementation may change at any moment. See <a href=" https://github.com/hydephp/develop/issues/79">this GitHub issue</a> for up to date information.
+## Adding custom post-build tasks
 
-Since v0.40.0 you can create custom post-build hooks. These hooks are code that is executed automatically after the site has been built using the `php hyde build` command.
+These tasks are code that is executed automatically after the site has been built using the `php hyde build` command. The built-in features in Hyde like sitemap generation and RSS feeds are created using tasks like these.
 
 ### Minimal example
 
 Here is a minimal example to get you started. For all these examples we assume you put the file in the `App/Actions` directory, but you can put them anywhere.
 
 ```php
-class SimpleHook extends AbstractBuildTask
+class SimpleTask extends AbstractBuildTask
 {
     public function run(): void
     {
@@ -102,7 +101,7 @@ This will then output the following, where you can see that some extra output, i
 
 ### Full example
 
-You can also set the description, and an optional `then()` method to run after the main hook has been executed.
+You can also set the description, and an optional `then()` method to run after the main task has been executed. The then method is great if you want to display a status message.
 
 ```php
 <?php
@@ -111,7 +110,7 @@ namespace App\Actions;
 
 use Hyde\Framework\Contracts\AbstractBuildTask;
 
-class ExampleHook extends AbstractBuildTask
+class ExampleTask extends AbstractBuildTask
 {
     public static string $description = 'Say hello';
 
@@ -134,18 +133,18 @@ class ExampleHook extends AbstractBuildTask
 </pre>
 
 
-### Registering the hooks
+### Registering the tasks
 
-There are a few ways to register these hooks so Hyde can find them. There is a convenient place to do this, which is in the main configuration file, `config/hyde.php`.
+There are a few ways to register these tasks so Hyde can find them. There is a convenient place to do this, which is in the main configuration file, `config/hyde.php`.
 
 ```php
 // filepath config/hyde.php
 'post_build_tasks' => [
-    \App\Actions\SimpleHook::class,
-    \App\Actions\ExampleHook::class,
+    \App\Actions\SimpleTask::class,
+    \App\Actions\ExampleTask::class,
 ],
 ```
 
-If you are developing an extension, I recommend you do this in the `boot` method of a service provider so that it can be loaded automatically. Do this by adding the fully qualified class name to the `BuildHookService::$postBuildTasks` array.
+If you are developing an extension, I recommend you do this in the `boot` method of a service provider so that it can be loaded automatically. Do this by adding the fully qualified class name to the `BuildTaskService::$postBuildTasks` array.
 
 Hyde can also autoload them if you store the files in the `app/Actions` directory and the names end in `BuildTask.php`. For example `app/Actions/ExampleBuildTask.php`.

packages/framework/src/Commands/HydeBuildStaticSiteCommand.php

@@ -8,8 +8,8 @@
 use Hyde\Framework\Actions\PostBuildTasks\GenerateSitemap;
 use Hyde\Framework\Helpers\Features;
 use Hyde\Framework\Hyde;
-use Hyde\Framework\Services\BuildHookService;
 use Hyde\Framework\Services\BuildService;
+use Hyde\Framework\Services\BuildTaskService;
 use Hyde\Framework\Services\DiscoveryService;
 use Illuminate\Support\Facades\Config;
 use LaravelZero\Framework\Commands\Command;
@@ -97,7 +97,7 @@ protected function runPreBuildActions(): void
      */
     public function runPostBuildActions(): void
     {
-        $service = new BuildHookService($this->output);
+        $service = new BuildTaskService($this->output);
 
         if ($this->option('run-prettier')) {
             $this->runNodeCommand(

packages/framework/src/Contracts/AbstractBuildTask.php

@@ -7,7 +7,7 @@
 use Illuminate\Console\OutputStyle;
 
 /**
- * @see \Hyde\Framework\Testing\Feature\Services\BuildHookServiceTest
+ * @see \Hyde\Framework\Testing\Feature\Services\BuildTaskServiceTest
  */
 abstract class AbstractBuildTask implements BuildTaskContract
 {

packages/framework/src/Services/BuildHookService.php → packages/framework/src/Services/BuildTaskService.php

@@ -7,12 +7,15 @@
 use Illuminate\Console\OutputStyle;
 
 /**
- * @see \Hyde\Framework\Testing\Feature\Services\BuildHookServiceTest
+ * This service manages the build tasks that are called after the site has been compiled using the build command.
+ *
+ * @see \Hyde\Framework\Testing\Feature\Services\BuildTaskServiceTest
  */
-class BuildHookService
+class BuildTaskService
 {
     /**
-     * Offers a hook for packages to add custom build tasks.
+     * Information for package developers: This offers a hook for packages to add custom build tasks.
+     * Make sure to add the fully qualified class name to the array and doing so by merging the array, not overwriting it.
      */
     public static array $postBuildTasks = [];
 

packages/framework/tests/Feature/Services/BuildHookServiceTest.php → packages/framework/tests/Feature/Services/BuildTaskServiceTest.php

@@ -4,20 +4,20 @@
 
 use Hyde\Framework\Contracts\AbstractBuildTask;
 use Hyde\Framework\Hyde;
-use Hyde\Framework\Services\BuildHookService;
+use Hyde\Framework\Services\BuildTaskService;
 use Hyde\Testing\TestCase;
 use Illuminate\Support\Facades\File;
 
 /**
- * @covers \Hyde\Framework\Services\BuildHookService
+ * @covers \Hyde\Framework\Services\BuildTaskService
  * @covers \Hyde\Framework\Contracts\AbstractBuildTask
  * @covers \Hyde\Framework\Actions\PostBuildTasks\GenerateSitemap
  * @covers \Hyde\Framework\Actions\PostBuildTasks\GenerateRssFeed
  * @covers \Hyde\Framework\Actions\PostBuildTasks\GenerateSearch
  *
  * @backupStaticAttributes enabled
  */
-class BuildHookServiceTest extends TestCase
+class BuildTaskServiceTest extends TestCase
 {
     /**
      * @covers \Hyde\Framework\Commands\HydeBuildStaticSiteCommand::runPostBuildActions
@@ -35,11 +35,11 @@ public function test_build_command_can_run_post_build_tasks()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runPostBuildTasks
+     * @covers \Hyde\Framework\Services\BuildTaskService::runPostBuildTasks
      */
     public function test_run_post_build_tasks_runs_configured_tasks_does_nothing_if_no_tasks_are_configured()
     {
-        BuildHookService::$postBuildTasks = [];
+        BuildTaskService::$postBuildTasks = [];
 
         $service = $this->makeService();
         $service->runPostBuildTasks();
@@ -48,37 +48,37 @@ public function test_run_post_build_tasks_runs_configured_tasks_does_nothing_if_
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::getPostBuildTasks
+     * @covers \Hyde\Framework\Services\BuildTaskService::getPostBuildTasks
      */
     public function test_get_post_build_tasks_returns_array_merged_with_config()
     {
-        BuildHookService::$postBuildTasks = ['foo'];
+        BuildTaskService::$postBuildTasks = ['foo'];
         config(['hyde.post_build_tasks' => ['bar']]);
 
         $service = $this->makeService();
         $this->assertEquals(['bar', 'foo'], $service->getPostBuildTasks());
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::getPostBuildTasks
+     * @covers \Hyde\Framework\Services\BuildTaskService::getPostBuildTasks
      */
     public function test_get_post_build_tasks_merges_duplicate_keys()
     {
-        BuildHookService::$postBuildTasks = ['foo'];
+        BuildTaskService::$postBuildTasks = ['foo'];
         config(['hyde.post_build_tasks' => ['foo']]);
 
         $service = $this->makeService();
         $this->assertEquals(['foo'], $service->getPostBuildTasks());
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runPostBuildTasks
+     * @covers \Hyde\Framework\Services\BuildTaskService::runPostBuildTasks
      */
     public function test_run_post_build_tasks_runs_configured_tasks()
     {
         $task = $this->makeTask();
 
-        BuildHookService::$postBuildTasks = [get_class($task)];
+        BuildTaskService::$postBuildTasks = [get_class($task)];
 
         $service = $this->makeService();
         $service->runPostBuildTasks();
@@ -87,7 +87,7 @@ public function test_run_post_build_tasks_runs_configured_tasks()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::run
+     * @covers \Hyde\Framework\Services\BuildTaskService::run
      */
     public function test_run_method_runs_task_by_class_name_input_and_returns_self()
     {
@@ -102,7 +102,7 @@ public function test_run_method_runs_task_by_class_name_input_and_returns_self()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runIf
+     * @covers \Hyde\Framework\Services\BuildTaskService::runIf
      */
     public function test_run_if_runs_task_if_supplied_boolean_is_true()
     {
@@ -117,7 +117,7 @@ public function test_run_if_runs_task_if_supplied_boolean_is_true()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runIf
+     * @covers \Hyde\Framework\Services\BuildTaskService::runIf
      */
     public function test_run_if_does_not_run_task_if_supplied_boolean_is_false()
     {
@@ -132,7 +132,7 @@ public function test_run_if_does_not_run_task_if_supplied_boolean_is_false()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runIf
+     * @covers \Hyde\Framework\Services\BuildTaskService::runIf
      */
     public function test_run_if_runs_task_if_supplied_callable_returns_true()
     {
@@ -149,7 +149,7 @@ public function test_run_if_runs_task_if_supplied_callable_returns_true()
     }
 
     /**
-     * @covers \Hyde\Framework\Services\BuildHookService::runIf
+     * @covers \Hyde\Framework\Services\BuildTaskService::runIf
      */
     public function test_run_if_does_not_run_task_if_supplied_callable_returns_false()
     {
@@ -183,7 +183,7 @@ public function test_find_tasks_in_app_directory_method_discovers_tasks_in_app_d
         File::makeDirectory(Hyde::path('app/Actions'));
         Hyde::touch('app/Actions/FooBuildTask.php');
 
-        $this->assertEquals(['App\Actions\FooBuildTask'], BuildHookService::findTasksInAppDirectory());
+        $this->assertEquals(['App\Actions\FooBuildTask'], BuildTaskService::findTasksInAppDirectory());
         File::deleteDirectory(Hyde::path('app/Actions'));
     }
 
@@ -209,9 +209,9 @@ public function run(): void {
         File::deleteDirectory(Hyde::path('app/Actions'));
     }
 
-    protected function makeService(): BuildHookService
+    protected function makeService(): BuildTaskService
     {
-        return new BuildHookService();
+        return new BuildTaskService();
     }
 
     protected function makeTask(): AbstractBuildTask