Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:In here, we will register our extension class name in the
getPageClasses
method: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: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 thisby implementing the
discoverPages
method in our extension class, and from there inject pages retrieved from our API.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 theregisterExtension
method of theHydeKernel
singleton instance, which you can access via the
Hyde\Hyde
facade, or via the service container.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 whenthe package is installed in a HydePHP project!
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?