Module Development

Overview

A module is a folder with a module.json and a Laravel service provider. It can add pages to the business panel, the admin panel and the public site, store its own data, react to bookings and run scheduled tasks, all without editing Slotara.

Laravel 12

This page is the contract between Slotara and modules. Only what's listed here is stable. Anything else in Slotara is internal and may change in any release. Changing an item on this list is a breaking change: it bumps Slotara's major version, and modules declare which versions they support in module.json ("requires": {"product": "^1.8"}).

Quick Start

On a development copy of Slotara:

  1. Turn on developer mode in .env (loads unsigned modules from modules-dev/):

     LICENTRA_MODULES_DEV=true

  2. Get the example module: Admin → System → Modules → More → Download example module, then Upload module with the zip (or unzip it into modules-dev/). Or start from scratch:

     php artisan module:make invoices        # creates modules-dev/slotara-invoices/

  3. Create its tables and publish its CSS/images:

     php artisan module:migrate slotara-invoices

  4. Give it to a plan (Subscription Plans → Modules included) and open its pages.

{warning} Developer mode loads code that isn't checked. Never turn it on for a live site.

Anatomy of a Module

The example module, slotara-hello:

slotara-hello/
├── module.json                         identity, versions, what it touches
├── src/
│   ├── ModuleServiceProvider.php       entry point: routes, views, hooks, tasks, panel pages
│   ├── Models/Greeting.php             its own model
│   └── Filament/
│       ├── TenantPlugin.php            pages for the business panel (/manage)
│       ├── Tenant/Greetings.php        a page with a form
│       ├── AdminPlugin.php             pages for the platform admin (/admin)
│       └── Admin/Overview.php
├── routes/web.php                      public pages, under /slotara-hello/...
├── resources/views/                    view('slotara-hello::public')
├── lang/en/messages.php                __('slotara-hello::messages.title')
├── database/migrations/                its own tables
└── public/hello.css                    published to /modules/slotara-hello/hello.css

The provider:

class ModuleServiceProvider extends \Pacific\Licentra\Modules\Laravel\ModuleServiceProvider
{
    public function bootModule(): void
    {
        $this->loadModuleResources();                             // views + translations
        $this->loadModuleRoutes('routes/web.php', ['web']);       // under /slotara-hello, gated per plan

        $this->observe(SlotReservation::class, 'created', function (SlotReservation $booking) {
            Greeting::create(['tenant_id' => $booking->tenant_id, 'message' => "Thanks, {$booking->name}!"]);
        });

        $this->schedule(fn ($schedule) => $schedule->call(fn () => Greeting::prune())->daily());
    }

    public function filamentPlugins(string $panel): array
    {
        return match ($panel) {
            'tenant' => [TenantPlugin::make()],
            'admin'  => [AdminPlugin::make()],
            default  => [],
        };
    }
}

module.json

{
    "manifest": 1,
    "slug": "slotara-invoices",
    "url": "invoices",
    "name": "Invoices",
    "description": "Shown on the Modules page.",
    "version": "1.0.0",
    "product": "slotara",
    "requires": { "product": "^1.8", "licentra": "^1.6" },
    "namespace": "Modules\SlotaraInvoices\",
    "provider": "Modules\SlotaraInvoices\ModuleServiceProvider",
    "envato_item_id": null,
    "plan_feature": false,
    "capabilities": {
        "tables": ["slotara_invoices"],
        "outbound": [],
        "routes": ["GET /invoices/view/{token}"],
        "schedule": false
    }
}
Key Notes
slug slotara-{name}, lowercase. The same slug is used everywhere: folder, route names, view namespace, license.
url Optional. The address your pages use, e.g. invoices gives /invoices/... and /manage/invoices/..., so a white-labelled platform never shows "slotara" in its addresses. Without it, pages use the slug. If Slotara already uses that address, the module is switched off. Needs "licentra": "^1.6".
version x.y.z. An older version can never replace a newer one.
requires.product Slotara versions you support (^1.8, >=1.8 <2.0). On other versions the module is switched off, not broken.
namespace, provider PSR-4 root for src/; the provider must be inside it.
plan_feature true: sold per plan (a checkbox on plans and businesses). false: every business gets it.
capabilities What the module adds, shown to the admin before install. Be accurate; it isn't enforced.

Pages: Business, Admin and Public

Business panel and admin panel (Filament). Add pages and resources in a Filament plugin returned from filamentPlugins(). Every module page and resource must:

use Pacific\Licentra\Modules\Laravel\GatedByModule;

class Greetings extends \Filament\Pages\Page
{
    use GatedByModule;                                     // hidden unless the module runs and the plan includes it

    protected static string $module = 'slotara-hello';
    protected static ?string $slug = 'slotara-hello/greetings';   // must start with your url (or slug)
}

A page whose slug doesn't start with the module's url (or its slug when there's no url) gets the module switched off, so a module can never take over a Slotara page.

Public pages. Put routes in routes/web.php and load them with loadModuleRoutes(). Everything is placed under /{url}/ (your url, else the slug) and named {slug}.*:

// routes/web.php → GET /slotara-hello/{business}, route name "slotara-hello.public"
Route::get('/{tenant:slug}', fn (Tenant $tenant) => view('slotara-hello::public', compact('tenant')))
    ->name('public');

With a {tenant} parameter the plan check uses that business. Add 'auth' to the middleware list for logged-in pages.

Hooking into Slotara Safely

React to Slotara only through these helpers. If your callback throws, Slotara's own action (saving the booking, rendering the page) still completes; the error is logged and charged to your module.

Helper Example
observe($model, $events, $fn) $this->observe(SlotReservation::class, 'created', fn ($booking) => …)
listen($events, $fn) $this->listen(SomeEvent::class, fn ($event) => …)
composer($views, $fn) $this->composer('pages.for-businesses', fn ($view) => $view->with(…))
schedule($fn) $this->schedule(fn ($s) => $s->call(fn () => …)->daily())

A module is switched off when it throws while starting, causes 3 PHP crashes in 10 minutes, causes 3 errors on Slotara's pages (code hooked in some other way), or causes 10 errors in 10 minutes on its own pages, hooks or tasks. 404s, validation errors and redirects to login don't count.

Data and Businesses

  • Give your models App\Models\Traits\BelongsToTenant: in the business panel, queries only return the current business's rows and tenant_id is filled in on create.
  • Outside the business panel (hooks, public pages, tasks) use Model::withoutGlobalScope('tenant') and filter by tenant_id yourself.
  • Current business: App\Support\TenantContext::current(), or auth()->user()->tenant.
  • Prefix your tables with the slug in snake case (slotara_invoices_…) and link them to tenants.id. Never add columns to Slotara's tables.
  • Migrations run when the module is installed or updated, never during Slotara's own updates. Uninstalling keeps the tables unless the admin chooses to delete the data.

The Module API (v1)

Area Stable API
Provider Extend Pacific\Licentra\Modules\Laravel\ModuleServiceProvider: register(), bootModule(), filamentPlugins($panel), loadModuleRoutes(), loadModuleResources(), observe(), listen(), composer(), schedule(), modulePath()
Filament Panel ids admin and tenant; GatedByModule trait; page/resource slugs {url} or {url}/…
Business App\Support\TenantContext, App\Models\Traits\BelongsToTenant
Plan gating plan_feature in module.json; app(\Pacific\Licentra\Modules\Laravel\TenantGate::class)->allows($slug, request())
Models App\Models\Tenant, User, Service, Provider, SlotReservation (a booking), SubscriptionPlan: read, relate, and observe created / updated / deleted
Settings Read Slotara settings via App\Models\Setting only
Packages Only what Slotara already requires (Laravel 12, Filament 5, Livewire 3). Modules can't ship a vendor/ folder.

Rules

  • Store everything per business (tenant_id).
  • Never edit files outside your module folder.
  • Keep capabilities accurate.
  • Static files go in public/; only CSS, JS, images, fonts and JSON are published (never PHP).

Testing

Run your module's tests through Slotara's test runner, loading the module from a scratch folder so your real modules-dev/ is never touched. The Invoices add-on's tests/InvoicesModuleTest.php shows the setup:

php artisan test ../slotara-invoices/tests/InvoicesModuleTest.php

Releasing

  1. In the Licentra admin, add a product: slug slotara-{name}, Add-on for: Slotara, pricing Envato (with its CodeCanyon item ID) or Free.

  2. Bump version in module.json, then from the Slotara folder:

     vendor/bin/licentra-release module modules-dev/slotara-{name} --upload

    This signs the module with your release key, uploads it, and also writes slotara-{name}-x.y.z.licentra-module.zip, a signed package admins can install with Upload module.

  3. Publish the release in the Licentra admin. Every licensed Slotara shows it under Available add-ons (or as an update).