HydePage API Reference

This article covers advanced information, and you are expected to already be familiar with Page Models and OOP

Abstract

This page contains the full API references for the built-in HydePage classes. Most users will not need to know about the inner workings of classes, but if you're interested in extending HydePHP, or just curious, this page is for you. It is especially useful if you're looking to implement your own page classes, or if you are creating advanced Blade templates.

About the reference

This document is heavily based around the actual source code, as I believe the best way to understand the code is to read it. However, large parts of the code are simplified for brevity and illustration. The code is not meant to be copy-pasted, but rather used as a reference so that you know what to look for in the actual source code, if you want to dig deeper.

Inheritance

Since all HydePages extend the base HydePage class, those shared methods are only listed once, under the HydePage class documentation which is conveniently located just below this section.

Class	Description
HydePage	The base class for all Hyde pages.
BaseMarkdownPage	The base class for all Markdown pages.
InMemoryPage	Extendable class for in-memory pages.
BladePage	Class for Blade pages.
MarkdownPage	Class for Markdown pages.
MarkdownPost	Class for Markdown posts.
DocumentationPage	Class for documentation pages.
HtmlPage	Class for HTML pages.

HydePage

The base class for all Hyde pages. All other page classes extend this class.

Unlike other frameworks, you generally don't instantiate pages yourself in Hyde. Instead, the page models act as blueprints defining information for Hyde to know how to parse a file, and what data around it should be generated.

To get a parsed file instance, you'd typically just create a source file, and you can then access the parsed file from the HydeKernel's page index.

In Blade views, you can always access the current page instance being rendered using the $page variable.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`HydePage`	`Hyde\Pages\Concerns`	Open in GitHub	Live API Docs

Base Structure

/**
 * The base class for all Hyde pages. Here simplified for the sake of brevity.
 */
abstract class HydePage
{
    /**
     * The directory in which source files are stored. Relative to the project root.
     */
    public static string $sourceDirectory;

    /**
     * The output subdirectory to store compiled HTML. Relative to the _site output directory.
     */
    public static string $outputDirectory;

    /**
     * The file extension of the source files.
     */
    public static string $fileExtension;

    /**
     * The default template to use for rendering the page.
     */
    public static string $template;

    /**
     * The page instance identifier.
     */
    public readonly string $identifier;

    /**
     * The page instance route key.
     */
    public readonly string $routeKey;

    /**
     * The parsed front matter.
     */
    public FrontMatter $matter;

    /**
     * The generated page metadata.
     */
    public PageMetadataBag $metadata;

    /**
     * The generated page navigation data.
     */
    public NavigationData $navigation;
}

Methods

Heads up! The following methods are defined in the HydePage class, and are thus available to all page classes. Since the HydePage class is abstract, you cannot instantiate it directly, and many of the static methods are also only callable from the child classes.

`make()`

Create a new page instance. Static alias for the constructor.

HydePage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): static

`isDiscoverable()`

Returns whether the page type is discoverable through auto-discovery.

HydePage::isDiscoverable(): bool

`get()`

Get a page instance from the Kernel's page index by its identifier.

HydePage::get(string $identifier): static

Throws: \Hyde\Framework\Exceptions\FileNotFoundException If the page does not exist.

`parse()`

Parse a source file into a new page model instance.

/** @param string $identifier The identifier of the page to parse. */
HydePage::parse(string $identifier): static // New page model instance for the parsed source file.

Throws: \Hyde\Framework\Exceptions\FileNotFoundException If the file does not exist.

`files()`

Get an array of all the source file identifiers for the model.

Note that the values do not include the source directory or file extension.

HydePage::files(): array<string>

`all()`

Get a collection of all pages, parsed into page models.

HydePage::all(): \Hyde\Foundation\Kernel\PageCollection<static>

`sourceDirectory()`

Get the directory where source files are stored for the page type.

HydePage::sourceDirectory(): string

`outputDirectory()`

Get the output subdirectory to store compiled HTML files for the page type.

HydePage::outputDirectory(): string

`fileExtension()`

Get the file extension of the source files for the page type.

HydePage::fileExtension(): string

`setSourceDirectory()`

Set the output directory for the page type.

HydePage::setSourceDirectory(string $sourceDirectory): void

`setOutputDirectory()`

Set the source directory for the page type.

HydePage::setOutputDirectory(string $outputDirectory): void

`setFileExtension()`

Set the file extension for the page type.

HydePage::setFileExtension(string $fileExtension): void

`sourcePath()`

Qualify a page identifier into file path to the source file, relative to the project root.

HydePage::sourcePath(string $identifier): string

`outputPath()`

Qualify a page identifier into a target output file path, relative to the _site output directory.

HydePage::outputPath(string $identifier): string

`path()`

Get an absolute file path to the page's source directory, or a file within it.

HydePage::path(string $path): string

`pathToIdentifier()`

Format a filename to an identifier for a given model. Unlike the basename function, any nested paths within the source directory are retained in order to satisfy the page identifier definition.

/** @param string $path Example: index.blade.php */
HydePage::pathToIdentifier(string $path): string // Example: index

`baseRouteKey()`

Get the route key base for the page model.

This is the same value as the output directory.

HydePage::baseRouteKey(): string

`__construct()`

Construct a new page instance.

$page = new HydePage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): void

`compile()`

Compile the page into static HTML.

$page->compile(): string // The compiled HTML for the page.

`toArray()`

Get the instance as an array.

$page->toArray(): array

`getSourcePath()`

Get the path to the instance source file, relative to the project root.

$page->getSourcePath(): string

`getOutputPath()`

Get the path where the compiled page will be saved.

$page->getOutputPath(): string // Path relative to the site output directory.

`getRouteKey()`

Get the route key for the page.

The route key is the page URL path, relative to the site root, but without any file extensions. For example, if the page will be saved to _site/docs/index.html, the key is docs/index.

Route keys are used to identify page routes, similar to how named routes work in Laravel, only that here the name is not just arbitrary, but also defines the output location, as the route key is used to determine the output path which is $routeKey.html.

$page->getRouteKey(): string

`getRoute()`

Get the route object for the page.

$page->getRoute(): Hyde\Support\Models\Route

`getLink()`

Format the page instance to a URL path, with support for pretty URLs if enabled.

Note that the link is always relative to site root, and does not contain ../ segments.

$page->getLink(): string

`getIdentifier()`

Get the page model's identifier property.

The identifier is the part between the source directory and the file extension. It may also be known as a 'slug', or previously 'basename', but it retains the nested path structure if the page is stored in a subdirectory.

For example, the identifier of a source file stored as '_pages/about/contact.md' would be 'about/contact', and 'pages/about.md' would simply be 'about'.

$page->getIdentifier(): string

`getBladeView()`

Get the Blade template/view key for the page.

$page->getBladeView(): string

`title()`

Get the page title to display in HTML tags like <title> and <meta> tags.

$page->title(): string

`metadata()`

Get the generated metadata for the page.

$page->metadata(): Hyde\Framework\Features\Metadata\PageMetadataBag

`showInNavigation()`

Can the page be shown in the navigation menu?

$page->showInNavigation(): bool

`navigationMenuPriority()`

Get the priority of the page in the navigation menu.

$page->navigationMenuPriority(): int

`navigationMenuLabel()`

Get the label of the page in the navigation menu.

$page->navigationMenuLabel(): string

`navigationMenuGroup()`

Get the group of the page in the navigation menu, if any.

$page->navigationMenuGroup(): string

`getCanonicalUrl()`

Get the canonical URL for the page to use in the <link rel="canonical"> tag.

It can be explicitly set in the front matter using the canonicalUrl key, otherwise it will be generated based on the site URL and the output path, unless there is no configured base URL, leading to this returning null.

$page->getCanonicalUrl(): string

`data()`

Get a value from the computed page data, or fallback to the page's front matter, then to the default value.

$page->data(string $key, mixed $default): \Hyde\Markdown\Models\FrontMatter|mixed

`matter()`

Get the front matter object, or a value from within.

$page->matter(string $key, mixed $default): \Hyde\Markdown\Models\FrontMatter|mixed

`has()`

See if a value exists in the computed page data or the front matter.

$page->has(string $key): bool

BaseMarkdownPage

The base class for all Markdown-based page models, with additional helpers tailored for Markdown pages.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`BaseMarkdownPage`	`Hyde\Pages\Concerns`	Open in GitHub	Live API Docs

Base Structure

/**
 * The base class for all Markdown-based page models. Here simplified for the sake of brevity.
 */
abstract class BaseMarkdownPage extends HydePage
{
    public Markdown $markdown;

    public static string $fileExtension = '.md';
}

Methods

`make()`

Create a new page instance. Static alias for the constructor.

BaseMarkdownPage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, Hyde\Markdown\Models\Markdown|string $markdown): static

`__construct()`

Construct a new page instance.

$page = new BaseMarkdownPage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, Hyde\Markdown\Models\Markdown|string $markdown): void

`markdown()`

Return the document's Markdown object.

$page->markdown(): Hyde\Markdown\Models\Markdown

`compile()`

Compile the page into static HTML.

$page->compile(): string // The compiled HTML for the page.

`save()`

Save the Markdown page object to disk by compiling the front matter array to YAML and writing the body to the file.

$page->save(): $this

InMemoryPage

Before we take a look at the common page classes, you'll usually use, let's first take a look at one that's quite interesting.

This class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize Hyde autodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.

You can learn more about the InMemoryPage class in the InMemoryPage documentation.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`InMemoryPage`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

As the class is not discoverable, the static path properties are not initialized. Instead, you solely rely on the contents/view properties.

You can also define macros which allow you to both add methods to the instance, but also to overload some built-in ones like the compile method.

/**
 * The InMemoryPage class, here simplified for the sake of brevity.
 */
class InMemoryPage extends HydePage
{
    public static string $sourceDirectory;
    public static string $outputDirectory;
    public static string $fileExtension;

    protected string $contents;
    protected string $view;

    /** @var array<string, callable> */
    protected array $macros = [];
}

Methods

`make()`

Static alias for the constructor.

InMemoryPage::make(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter, string $contents, string $view): static

`__construct()`

Create a new in-memory/virtual page instance.

The in-memory page class offers two content options. You can either pass a string to the $contents parameter, Hyde will then save that literally as the page's contents. Alternatively, you can pass a view name to the $view parameter, and Hyde will use that view to render the page contents with the supplied front matter during the static site build process.

Note that $contents take precedence over $view, so if you pass both, only $contents will be used. You can also register a macro with the name 'compile' to overload the default compile method.

If the identifier for an in-memory page is "foo/bar" the page will be saved to "_site/foo/bar.html". You can then also use the route helper to get a link to it by using the route key "foo/bar". Take note that the identifier must be unique to prevent overwriting other pages. all this data will be passed to the view rendering engine.

Parameter $view: The view key or Blade file for the view to use to render the page contents.
Parameter $matter: The front matter of the page. When using the Blade view rendering option,

$page = new InMemoryPage(string $identifier, \Hyde\Markdown\Models\FrontMatter|array $matter, string $contents, string $view): void

`getContents()`

Get the contents of the page. This will be saved as-is to the output file when this strategy is used.

$page->getContents(): string

`getBladeView()`

Get the view key or Blade file for the view to use to render the page contents when this strategy is used.

$page->getBladeView(): string

`compile()`

Get the contents that will be saved to disk for this page.

In order to make your virtual page easy to use we provide a few options for how the page can be compiled. If you want even more control, you can register a macro with the name 'compile' to overload the method, or simply extend the class and override the method yourself, either in a standard or anonymous class.

$page->compile(): string

`macro()`

Unlike most macros you might be used to, these are not static, meaning they belong to the instance. If you have the need for a macro to be used for multiple pages, you should create a custom page class instead.

$page->macro(string $name, callable $macro): void

`hasMacro()`

Determine if a macro with the given name is registered for the instance.

$page->hasMacro(string $method): bool

`__call()`

Dynamically handle macro calls to the class.

$page->__call(string $method, array $parameters): mixed

BladePage

Page class for Blade pages.

Blade pages are stored in the _pages directory and using the .blade.php extension. They will be compiled using the Laravel Blade engine the _site/ directory.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`BladePage`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

class BladePage extends HydePage
{
    public static string $sourceDirectory = '_pages';
    public static string $outputDirectory = '';
    public static string $fileExtension = '.blade.php';
}

Methods

`__construct()`

No description provided.

/** @param string $identifier The identifier, which also serves as the view key. */
$page = new BladePage(string $identifier, Hyde\Markdown\Models\FrontMatter|array $matter): void

`getBladeView()`

Get the Blade template/view key for the page.

$page->getBladeView(): string

`compile()`

Compile the page into static HTML.

$page->compile(): string // The compiled HTML for the page.

MarkdownPage

Page class for Markdown pages.

Markdown pages are stored in the _pages directory and using the .md extension. The Markdown will be compiled to HTML using a minimalistic layout to the _site/ directory.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`MarkdownPage`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

class MarkdownPage extends BaseMarkdownPage
{
    public static string $sourceDirectory = '_pages';
    public static string $outputDirectory = '';
    public static string $template = 'hyde::layouts/page';
}

Methods

This class does not define any additional methods.

MarkdownPost

Page class for Markdown blog posts.

Markdown posts are stored in the _posts directory and using the .md extension. The Markdown will be compiled to HTML using the blog post layout to the _site/posts/ directory.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`MarkdownPost`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

class MarkdownPost extends BaseMarkdownPage
{
    public static string $sourceDirectory = '_posts';
    public static string $outputDirectory = 'posts';
    public static string $template = 'hyde::layouts/post';

    public ?string $description;
    public ?string $category;
    public ?DateString $date;
    public ?PostAuthor $author;
    public ?FeaturedImage $image;
}

Methods

`getLatestPosts()`

No description provided.

MarkdownPost::getLatestPosts(): \Hyde\Foundation\Kernel\PageCollection<\Hyde\Pages\MarkdownPost>

`toArray()`

No description provided.

$page->toArray(): array

DocumentationPage

Page class for documentation pages.

Documentation pages are stored in the _docs directory and using the .md extension. The Markdown will be compiled to HTML using the documentation page layout to the _site/docs/ directory.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`DocumentationPage`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

class DocumentationPage extends BaseMarkdownPage
{
    public static string $sourceDirectory = '_docs';
    public static string $outputDirectory = 'docs';
    public static string $template = 'hyde::layouts/docs';
}

Methods

`home()`

No description provided.

DocumentationPage::home(): Hyde\Support\Models\Route

`homeRouteName()`

No description provided.

DocumentationPage::homeRouteName(): string

`hasTableOfContents()`

No description provided.

DocumentationPage::hasTableOfContents(): bool

`getOnlineSourcePath()`

No description provided.

$page->getOnlineSourcePath(): string|false

`getTableOfContents()`

Generate Table of Contents as HTML from a Markdown document body.

$page->getTableOfContents(): string

`getRouteKey()`

Get the route key for the page.

If flattened outputs are enabled, this will use the identifier basename so nested pages are flattened.

$page->getRouteKey(): string

`getOutputPath()`

Get the path where the compiled page will be saved.

If flattened outputs are enabled, this will use the identifier basename so nested pages are flattened.

$page->getOutputPath(): string

HtmlPage

Page class for HTML pages.

HTML pages are stored in the _pages directory and using the .html extension. These pages will be copied exactly as they are to the _site/ directory.

Quick Reference

Class Name	Namespace	Source Code	API Docs
`HtmlPage`	`Hyde\Pages`	Open in GitHub	Live API Docs

Base Structure

class HtmlPage extends HydePage
{
    public static string $sourceDirectory = '_pages';
    public static string $outputDirectory = '';
    public static string $fileExtension = '.html';
}

Methods

`contents()`

No description provided.

$page->contents(): string

`compile()`

No description provided.

$page->compile(): string

`getBladeView()`

No description provided.

$page->getBladeView(): string