Skip to content

Commit

Permalink
Merge pull request #459 from hydephp/refactor-build-tasks
Browse files Browse the repository at this point in the history
Rename build hooks to build tasks
  • Loading branch information
caendesilva authored Sep 1, 2022
2 parents 043405e + 2ec5357 commit 1100a10
Show file tree
Hide file tree
Showing 6 changed files with 44 additions and 39 deletions.
9 changes: 6 additions & 3 deletions RELEASE_NOTES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 10 additions & 11 deletions docs/digging-deeper/advanced-customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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
Expand All @@ -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';

Expand All @@ -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`.
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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(
Expand Down
2 changes: 1 addition & 1 deletion packages/framework/src/Contracts/AbstractBuildTask.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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();
Expand All @@ -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();
Expand All @@ -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()
{
Expand All @@ -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()
{
Expand All @@ -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()
{
Expand All @@ -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()
{
Expand All @@ -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()
{
Expand Down Expand Up @@ -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'));
}

Expand All @@ -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
Expand Down

0 comments on commit 1100a10

Please sign in to comment.