A plugin is a folder under platform/plugins/<slug>/ with a manifest, a service provider and whatever Laravel pieces it needs. The CMS finds it, autoloads it, runs its migrations and boots it when it is activated.
Layout
platform/plugins/opening-hours/
├── plugin.json
├── src/Providers/OpeningHoursServiceProvider.php
├── src/Http/Controllers/… src/Models/…
├── routes/web.php public pages (web middleware)
├── routes/admin.php admin pages (web middleware; add auth + permission:…)
├── routes/api.php staff API, under /api
├── routes/site.php Site API, under /api/site/v1
├── routes/site.openapi.php the words for the Site API description
├── database/migrations/
├── resources/views/ view namespace = the slug: view('opening-hours::…')
├── resources/lang/ translation namespace = the slug
├── resources/js/Pages/ admin screens (Vue + Inertia)
└── tests/Feature/
plugin.json
{
"id": "acme/opening-hours",
"name": "Opening Hours",
"namespace": "Acme\\OpeningHours",
"provider": "Acme\\OpeningHours\\Providers\\OpeningHoursServiceProvider",
"version": "1.0.0",
"author": "Acme",
"description": "Opening hours as a page block and in the Site API.",
"minimumCoreVersion": "1.0.0",
"licensed": false,
"uuid": "…",
"catalog": "Content"
}
licensed: true means the plugin only boots when the site's licence key includes its uuid. Until then it is installed but asleep: its views and migrations load, its routes and menu items do not, and the Plugins screen says why.
The provider
final class OpeningHoursServiceProvider extends PluginServiceProvider
{
protected string $shortName = 'opening-hours';
protected function bootModule(): void
{
add_filter('admin.menu', fn (Collection $items) => $items->push(
new MenuItem('opening-hours', __('Opening hours'), '/admin/opening-hours', 'clock', 40, 'opening-hours.manage')));
add_filter('acl.permissions', fn (Collection $items) => $items->push(
new PermissionDefinition('opening-hours.manage', 'Manage opening hours', 'Content')));
add_filter('blocks.renderers', function (array $renderers): array {
$renderers['opening_hours'] = fn (array $data) => view('opening-hours::blocks.hours', ['data' => $data])->render();
return $renderers;
});
}
}
PluginServiceProvider loads routes/*.php, migrations, views, translations and public/ assets on its own; bootModule() only runs when the plugin is allowed to start.
Hooks
Plugins talk to the core and to each other through actions and filters:
add_action('commerce.order.paid', fn (Order $order) => …); // something happened
add_filter('commerce.gateways', fn (array $g) => [...$g, new MyGateway]); // change a value
do_action('opening-hours.changed', $hours); // offer your own
$value = apply_filters('opening-hours.today', $value, $date);
Common ones:
| Hook | Kind | What for |
|---|---|---|
admin.menu |
filter | items in the admin sidebar |
acl.permissions |
filter | permissions for roles |
blocks.renderers |
filter | how a page block type renders |
plugin.settings.schema |
filter | a settings form for the plugin, stored for you |
search.sources |
filter | make the plugin's content searchable |
sitemap.urls |
filter | URLs for sitemap.xml |
content.locked |
filter | "is this item locked for the current visitor?" |
flow.triggers |
filter | events the Flow automation plugin can start from |
site_api.features |
filter | what the Site API's /bootstrap says the site offers |
site_api.can_view / site_api.paywall |
filter | who may read an item through the Site API, and what unlocks it |
site_api.product, site_api.order, site_api.booking, site_api.profile |
filter | extra fields in those Site API answers |
site_api.session_user |
action | a customer signed in inside an app session (merge guest data) |
site_api.session |
action | a Site API request started an app session (drop per-session caches) |
Your plugin in the Site API
Add routes/site.php. Its routes are registered under /api/site/v1 with the Site API's middleware: JSON errors, locale, rate limits, ETags, idempotency keys and request logging. Route names start with site..
use Ergon\Api\Site\SiteApi;
use Illuminate\Support\Facades\Route;
Route::get('/opening-hours', fn () => SiteApi::ok(OpeningHours::week()))->name('site.opening-hours');
// Needs a signed-in customer; site.session gives the request the app's server session (cart, coupons …).
Route::post('/opening-hours/remind-me', RemindController::class)
->middleware(['site.customer', 'site.session', 'throttle:10,1'])->name('site.opening-hours.remind');
Answer with the helpers, so every endpoint looks the same to an app:
| Helper | Gives |
|---|---|
SiteApi::ok($data) / SiteApi::created($data) |
{"data": …} with 200 / 201 |
SiteApi::paginated($paginator, fn ($item) => …) |
data, meta (page, per_page, total, last_page), links |
SiteApi::error($code, $message, $status, $fields) |
{"error": {"code", "message", "fields"}} |
SiteApi::money($cents, $currency) |
{"amount", "currency", "formatted"} |
SiteApi::image($media) |
url, alt, width, height and the responsive sizes |
SiteApi::date($value) |
ISO 8601 or null |
SiteApi::fromWeb(fn () => …, fn () => $data) |
runs a website action that answers with a redirect and a flash message, and answers JSON instead |
SiteApi::denied($model, $user) |
null, or the 403 paywall answer |
CustomerPush::send($userId, $type, $title, $body, $path) |
inbox entry plus push to the customer's app |
Then tell apps the feature exists and describe the endpoints:
// in bootModule()
add_filter('site_api.features', fn (array $f) => $f + ['opening_hours' => ['enabled' => true]]);
// routes/site.openapi.php
return [
'site.opening-hours' => ['summary' => 'Opening hours this week'],
'site.opening-hours.remind' => ['summary' => 'Remind me when it opens', 'body' => ['day' => 'string:date*']],
];
Each site's /api/site/v1/openapi.json is built from the routes that really exist there, so an app generator sees exactly the active plugins. A test in the core fails when a site. route has no words.
Rules for Site API endpoints
- Reuse the website's own logic (the same service, or the web controller through
SiteApi::fromWeb), never a second copy of the rules. - A guest proves ownership with the key the create call returned (
access,t); a signed-in customer with their token. Anything else answers 404. - Money in cents, times in ISO 8601 UTC, images through
SiteApi::image. - Writes that cost money or send something accept an
Idempotency-Key— the middleware does it for you.
Tests
Plugin tests are Pest/PHPUnit feature tests under tests/Feature. Boot the plugin the way activation does (autoload, migrations, provider) in setUp(); the core's tests have helpers (SiteApiTestHelpers::bootPlugins(), signedInCustomer()).