Advanced Customization

Introduction & Warning

Danger lies ahead! Read this before you proceed.

This page covers advanced usage of potentially experimental and unstable features and is intended for developers who know what they are doing and can handle the risk of breaking things. The article will also cover things that you can do, but that you maybe should not. With great power comes great responsibility. You have been warned.

Documentation here will be mainly example driven, as it is assumed you have somewhat of an understanding of what you are doing already.

Emoji legend

Each section is marked with an emoji that indicates the level of risk. Note that pretty much all of these are experimental features, and are not at all supported. Use at your own risk.

  • 🧪 = Indicates experimental features bound to change at any time.
  • ⚠ = Exercise caution when using this feature.
  • 💔 = This could seriously break things

A note on file paths

When Hyde references files, especially when passing filenames between components, the file path is almost always relative to the root of the project. When an absolute path is required, the path is resolved through the Hyde::path() helper. Specifying absolute paths yourself will likely lead to unforeseen problems.

Customizing source directories 🧪

This may cause integrations such as the realtime compiler to break.

The source directory paths are stored in the PageModel objects. You can change them by modifying the static property, for example in a service provider.

Internally, the paths are registered in the HydeServiceProvider using the following method:

Filepath: Hyde\Framework\HydeServiceProvider
 1use Hyde\Framework\Concerns\RegistersFileLocations;
 2 
 3public function register(): void
 4{
 5    $this->registerSourceDirectories([
 6        BladePage::class => '_pages',
 7        MarkdownPage::class => '_pages',
 8        MarkdownPost::class => '_posts',
 9        DocumentationPage::class => '_docs',
10    ]);
11}

Customizing the output directory ⚠

Hyde deletes all files in the output directory before compiling the site. Don't set this path to a directory that contains important files!

If you want to store your compiled website in a different directory than the default _pages, you can change the path using the following configuration option in config/hyde.php. The path is expected to be relative to your project root.

Filepath: config/hyde.php
1return [
2    'output_directory' => 'docs',
3];

Setting an absolute path 💔

If you want to store the output website outside your project with an absolute path you may do so at your own risk using a service provider. This is not supported or recommended as it may cause unintentional file deletions.

Filepath: Boot method of a service provider
1StaticPageBuilder::$outputPath = '/var/www/my-project/';

Adding custom post-build hooks 🧪

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 this GitHub issue for up to date information.

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.

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.

1class SimpleHook extends AbstractBuildTask
2{
3    public function run(): void
4    {
5        $this->info('Hello World!');
6    }
7}

This will then output the following, where you can see that some extra output, including execution time tracking is added for us. We can of course customize this if we want, as you can see in the next example.

$ php hyde build
  Generic build task... Hello World! Done in 0.26ms

Full example

You can also set the description, and an optional then() method to run after the main hook has been executed.

 1<?php
 2 
 3namespace App\Actions;
 4 
 5use Hyde\Framework\Contracts\AbstractBuildTask;
 6 
 7class ExampleHook extends AbstractBuildTask
 8{
 9    public static string $description = 'Say hello';
10 
11    public function run(): void
12    {
13        $this->info('Hello World!');
14    }
15 
16    public function then(): void
17    {
18        $this->line('Goodbye World!');
19    }
20}
$ php hyde build
  Say hello... Hello World!
  Goodbye World!

Registering the hooks

An autoloading feature is planned, but for now, you will need to register the hooks somewhere. There is a convenient place to do this, which is in the main configuration file, config/hyde.php.

Filepath: config/hyde.php
1'post_build_tasks' => [
2    \App\Actions\SimpleHook::class,
3    \App\Actions\ExampleHook::class,
4],

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.