Zum Inhalt springen
Ergon Code

Ergon CMS · Dokumentation

Plugins

The layout of an Ergon CMS plugin, its provider and hooks, admin screens, and how a plugin adds its own endpoints to the Site API.

Die Entwickler-Dokumentation gibt es auf Englisch.

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()).