Addon Modules

Addons are the freest type. Core has no conventions it looks for inside one, so you’re writing a normal Laravel and Inertia feature that happens to live in Modules/Addons/.

Read Fundamentals first if you haven’t.

Generate it

php artisan make:module LoyaltyRewards --type=addon
php artisan module:enable LoyaltyRewards
php artisan module:migrate LoyaltyRewards
php artisan octane:reload
php artisan module:doctor LoyaltyRewards

What you get

Modules/Addons/LoyaltyRewards/
├── module.json                 with permissions declared
├── app/
│   ├── Providers/
│   ├── Http/Controllers/SettingsController
│   └── Models/LoyaltyRewardsCredential   rename or delete this
├── database/migrations/
└── routes/                     web, api, settings

The generated credentials model assumes you talk to an external API. If you don’t, delete it and its migration, and swap the settings controller over to a key-value settings table instead.

How addons differ

	Service modules	Gateways	Addons
Classes core looks for	~12	1	none
Registration	By name	Explicit	you drive it

Everything happens through four things: routes you register, listeners on core events, Inertia pages in register.ts, and your own tables.

Hooking into core

Events are the main integration point. Register them in EventServiceProvider:

protected $listen = [
    \App\Events\ServicePaymentCompleted::class => [AwardPurchasePoints::class],
    \App\Events\ServiceRenewalInitiated::class => [AwardRenewalPoints::class],
    \Illuminate\Auth\Events\Registered::class => [GiveSignupBonus::class],
];

The full list is in Fundamentals.

Two things to get right there: keep configureEmailVerification() as a no-op, and never list a listener that already lives in app/Listeners.

Queue your listeners:

class AwardPurchasePoints implements ShouldQueue
{
    public function handle(ServicePaymentCompleted $event): void { /* ... */ }
}

An addon that throws inside a synchronous listener can break checkout for everyone.

Affiliates is the best reference here. It listens to registration, payment and renewal, and does payouts off the back of them.

Running code on every request

Your provider’s boot code runs once per Octane worker, not once per request, so anything that looks at the incoming request belongs in middleware. Append it to the web group from your provider:

use Illuminate\Contracts\Http\Kernel;

protected function bootModule(): void
{
    $this->app->make(Kernel::class)->appendMiddlewareToGroup('web', CaptureRewardCode::class);
}

Affiliates captures ?ref= codes this way. Share Inertia props from a middleware like this too, never from the provider. See Running under Octane.

Settings

Flat fields
Custom UI
Key-value store

Keep the generated SettingsController and just change the fields. You get a full admin page with no React. See the settings section.

Like Forms does with its 12 pages. Write your own controller and page, then register it:

resources/js/register.ts

registerModulePages({
    'LoyaltyRewards/Settings': () => import('./Pages/Admin/Settings.tsx'),
    'LoyaltyRewards/Dashboard': () => import('./Pages/User/Dashboard.tsx'),
});

A small table and model is the usual pattern:

class LoyaltySetting extends Model
{
    protected $table = 'loyalty_settings';
    protected $fillable = ['key', 'value'];

    public static function get(string $key, mixed $default = null): mixed
    {
        return static::where('key', $key)->value('value') ?? $default;
    }
}

Seed sensible defaults so the module works the moment it’s enabled. Affiliates does this with AffiliateSettingsSeeder.If the settings are read on every page, memoize them with RuntimeSnapshot rather than a static property, which would go stale for the life of the worker:

public static function all(): array
{
    return RuntimeSnapshot::remember('loyalty:settings', fn () => static::pluck('value', 'key')->all());
}

Saving from your admin page refreshes it in every worker, because admin saves bump the runtime version. If a job or command writes settings, call RuntimeSnapshot::bump() after it.

User-facing routes

routes/web.php

Route::middleware(['auth', 'verified', CheckUserSuspension::class])->group(function () {
    Route::get('/rewards', [RewardsController::class, 'index'])->name('rewards.index');
    Route::post('/rewards/redeem', [RewardsController::class, 'redeem'])->name('rewards.redeem');
});

Admin routes and their permissions are already set up by the generator. See Admin permissions if you need to add more.

There’s no manifest hook for sidebar links. They come from the SidebarLink table, which admins manage in the admin panel.

So either seed a row when your module is enabled, which is friendlier, or document the URL and let the admin add it:

use App\Models\SidebarLink;
use App\Support\RuntimeSnapshot;
use App\Support\SidebarIconLibrary;

SidebarLink::firstOrCreate(
    ['href' => '/rewards'],
    [
        'label' => 'Rewards',
        'category_label' => 'user',
        'role_category' => 'user',
        'category_order' => 2,
        'sort_order' => SidebarLink::getNextSortOrder(),
        'icon' => 'gift',
        'icon_type' => SidebarIconLibrary::TYPE,
        'is_active' => true,
        'allowed_roles' => [],
    ],
);

RuntimeSnapshot::bump();

category_label and role_category place the link in a sidebar group (general and user are the default ones). icon is a name from the built-in icon library. The sidebar is memoized per worker, so the bump() makes the link appear straight away instead of within a minute.

Commands and cron

protected function moduleCommands(): array
{
    return [ExpireLoyaltyPoints::class];
}

protected function moduleSchedule(Schedule $schedule): void
{
    $schedule->command('loyalty:expire-points')->daily();
}

Use moduleSchedule() or routes/console.php, not both.

Touching core data

Adding a column to users or services is fine. Make it nullable and the migration idempotent:

if (! Schema::hasColumn('users', 'loyalty_points')) {
    Schema::table('users', fn (Blueprint $t) => $t->unsignedInteger('loyalty_points')->default(0));
}

Never change or drop a core column, and don’t edit App\Models\User. Point a relationship at it from your own model instead:

class LoyaltyAccount extends Model
{
    public function user(): BelongsTo
    {
        return $this->belongsTo(\App\Models\User::class);
    }
}

If you need more than one field, prefer a side table with a foreign key. It keeps your module removable.

Test it

php artisan module:doctor LoyaltyRewards

Enable it

From Admin, Modules. Migrations run, defaults seed, the workers reload, the admin page loads.

Trigger each event you listen to

Check the side effects.

Disable it, and confirm the app still works completely

Nothing in core should depend on your tables, listeners or routes.

Re-enable it

No duplicate rows, no failed migrations.

Step 3 is the one people skip and the one that breaks production.

Worth reading

LoyaltyProgram

Small and event-driven.

News

Content CRUD with admin and public pages.

Affiliates

Listeners, payouts, a console command, 4 React pages.

Forms

The most frontend-heavy, 12 pages.

Affiliates, Blog, KnowledgeBase and News still use an older hand-written service provider. Copy their features, not their providers.

GETTING STARTED

MAKE YOUR OWN

SPARTAN THEMES

Generate it

How addons differ

Hooking into core

Running code on every request

Settings

User-facing routes

Navigation

Commands and cron

Touching core data

Test it

Worth reading

LoyaltyProgram

News

Affiliates

Forms

​Generate it

​How addons differ

​Hooking into core

​Running code on every request

​Settings

​User-facing routes

​Navigation

​Commands and cron

​Touching core data

​Test it

​Worth reading

LoyaltyProgram

News

Affiliates

Forms

Generate it

How addons differ

Hooking into core

Running code on every request

Settings

User-facing routes

Navigation

Commands and cron

Touching core data

Test it

Worth reading