Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the Extensions API #1465

Merged
merged 8 commits into from
Nov 16, 2023
Merged

Document the Extensions API #1465

merged 8 commits into from
Nov 16, 2023

Conversation

caendesilva
Copy link
Member

@caendesilva caendesilva commented Nov 16, 2023

The Extensions API

Introduction

The Extensions API a powerful interface designed for package developers who want to extend the functionality of HydePHP.

Using the API, you can hook directly into the HydePHP Kernel and extend sites with custom page types and new features.

This documentation page functions heavily through examples, so it's recommended that the sections are read in order.

Prerequisites

Before creating your extension, it will certainly be helpful if you first become familiar with
the basic internal architecture of HydePHP, as well as how the auto-discovery system works,
so you can understand how your code works with the internals.

The why and how of the Extensions API

HydePHP being a static site generator, the Extensions API is centered around Page Models,
which you are hopefully already familiar with, otherwise you should read up on them first.

What the Extensions API does is to allow you to create custom page types, and tell HydePHP how to discover them.
This may sound like a small thing, but it's actually incredibly powerful as the page models are the foundation
of HydePHP's functionality. They tell the system how to discover pages, how to render them,
and how they interact with the site.

Any other functionality you want to add to HydePHP, such as new commands or configuration options,
can be added the same way as you would in Laravel, and are thus not part of our API.
See the Laravel package development guide for more.

Creating your Extension class

The entry-point for your extension is your Extensions class. Within this, you can register the custom page classes.
If needed, you can also register discovery handlers which can run custom logic at various parts of the boot process.

In this article we will create an extension that registers a new type of page, a JsonPageExtension.

The first step is to create a class that extends the HydeExtension class:

use Hyde\Foundation\Concerns\HydeExtension;

class JsonPageExtension extends HydeExtension {
    //
}

In here, we will register our extension class name in the getPageClasses method:

class JsonPageExtension extends HydeExtension {
    public static function getPageClasses(): array {
        return [
            JsonPage::class,
        ];
    }
}

Hyde will then use the information from the JsonPage class to automatically discover the pages when booting the Kernel.
For example, if you specify the file extension and source directory, that is all Hyde needs to know to discover the pages.

If our pages need more complex discovery logic, we can create custom handlers. so let's take a quick look at that next.

Discovery handlers

The discovery handlers lets you run code at various points of the booting process. This is usually only needed if your
page models cannot provide the information required for Hyde run the standard auto-discovery, and thus need custom logic.

Usually in these cases, you would only need to add files to the Kernel FileCollection,
though the HydeExtension class offers following three discovery handlers, in case you need them:

/** Runs during file discovery */
public function discoverFiles(FileCollection $collection): void;

/** Runs during page discovery */
public function discoverPages(PageCollection $collection): void;

/** Runs during route discovery */
public function discoverRoutes(RouteCollection $collection): void;

Any of these can be implemented in your extension class, and they will be called during the discovery. As you can see,
the instance of the discovery collection is injected into the method for you to interact with.

Discovery handler example

Let's go crazy and implement a discovery handler to collect JsonPage files from an external API! We will do this
by implementing the discoverPages method in our extension class, and from there inject pages retrieved from our API.

class JsonPageExtension extends HydeExtension {
    public function discoverPages(PageCollection $collection): void {
        $pages = Http::get('https://example.com/my-api')->collect();

        $pages->each(function (array $page) use ($collection): void {
            $collection->addPage(JsonPage::fromArray($page));
        });
    }
}

Since the discovery steps are handled sequentially, the added pages will automatically be discovered as routes without
us having to implement that handler method. As we inject the page objects directly, we bypass the need of the FileCollection.

Registering your extension

Now that we have our extension class, we need to register it with HydePHP.

It's important that your class is registered before the HydeKernel boots. Therefore, an excellent place for this is the
register method of your extensions service provider, where you call the registerExtension method of the HydeKernel
singleton instance, which you can access via the Hyde\Hyde facade, or via the service container.

use Hyde\Hyde;
use Hyde\Foundation\HydeKernel;
use Illuminate\Support\ServiceProvider;

class JsonPageExtensionServiceProvider extends ServiceProvider {
    public function register(): void {
        // Via the service container:
        $this->app->make(HydeKernel::class)->registerExtension(JsonPageExtension::class);

        // Or via the facade:
        Hyde::registerExtension(JsonPageExtension::class);
    }
}

Packaging your extension

To make your extension available to other HydePHP users, you can make it into a Composer package,
and publish it to Packagist for others to install.

If you register your service provider in your package's composer.json file, your extension automatically be enabled when
the package is installed in a HydePHP project!

{
  "extra": {
    "laravel": {
      "providers": [
        "My\\Namespace\\JsonPageExtensionServiceProvider"
      ]
    }
  }
}

Telling the world about your extension

Next up, why not send us a Tweet at @HydeFramework and tell us about your extension,
so we can feature it?

@caendesilva caendesilva temporarily deployed to pr-documentation-1465 November 16, 2023 17:50 — with GitHub Actions Inactive
Copy link

codecov bot commented Nov 16, 2023

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (64bb5df) 100.00% compared to head (ab6c966) 100.00%.

Additional details and impacted files
@@              Coverage Diff              @@
##              master     #1465     +/-   ##
=============================================
  Coverage     100.00%   100.00%             
- Complexity      1728      3456   +1728     
=============================================
  Files            180       360    +180     
  Lines           4693      9386   +4693     
=============================================
+ Hits            4693      9386   +4693     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@caendesilva caendesilva marked this pull request as ready for review November 16, 2023 18:07
@caendesilva caendesilva merged commit c0df45b into master Nov 16, 2023
21 checks passed
@caendesilva caendesilva deleted the document-extensions-api branch November 16, 2023 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant