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. You'll also likely need to update route key names in your templates.
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.php1return [2 'output_directory' => 'docs',3];
Setting an absolute path#
Since Hyde v0.64.0-beta, the site output directory will always be resolved within the project root. If you want to compile the site to an absolute path outside your project, it's instead recommended that you use a build task to copy the files to the desired location automatically after the site has been compiled.
Adding custom post-build tasks#
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.
Maybe you want to create your own, to for example upload the site to FTP or copy the files to a public directory? It's easy to do, here's how!
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 SimpleTask extends AbstractBuildTask2{3 public function run(): void4 {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 task has been executed. The then method is great if you want to display a status message.
1<?php 2 3namespace App\Actions; 4 5use Hyde\Framework\Concerns\AbstractBuildTask; 6 7class ExampleTask extends AbstractBuildTask 8{ 9 public static string $description = 'Say hello';10 11 public function run(): void12 {13 $this->info('Hello World!');14 }15 16 public function then(): void17 {18 $this->line('Goodbye World!');19 }20}
$ php hyde build Say hello... Hello World! Goodbye World!
Registering the tasks#
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
.
Filepath: config/hyde.php1'post_build_tasks' => [2 \App\Actions\SimpleTask::class,3 \App\Actions\ExampleTask::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 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
.