Skip to content

Add-ons

Extend the Shopper admin panel with self-contained addons, register routes, sidebar items, Livewire components, views, and settings without modifying core files.

Addons are the recommended way to package Shopper extensions. An addon is a self-contained unit that registers its routes, Livewire components, sidebar entries, views, and settings items through the ShopperPanel. When an addon is disabled, none of its assets are registered.

Creating an Addon

An addon is a class that implements Shopper\Contracts\ShopperAddon. Extend Shopper\Addon\BaseAddon: it implements the contract and provides getName(), boot() and isEnabled(), so you only write getId() and register(). The contract has five methods:

MethodReturnDescription
getId()stringUnique kebab-case identifier (my-addon), also the addon's key in config/shopper/addons.php
getName()stringDisplay name; BaseAddon derives it from getId() automatically (loyalty-points becomes Loyalty Points)
register(ShopperPanel $panel)voidCalled by Shopper::addon() when the addon is enabled, bind routes, components, views, settings
boot(ShopperPanel $panel)voidCalled when Shopper boots, after all addons are registered, use for cross-addon dependencies; empty in BaseAddon
isEnabled()boolBaseAddon reads config('shopper.addons.<id>'), defaulting to true

A minimal addon looks like this:

namespace App\Addons;

use Shopper\Addon\BaseAddon;
use Shopper\ShopperPanel;

final class AnalyticsAddon extends BaseAddon
{
    public function getId(): string
    {
        return 'analytics';
    }

    public function register(ShopperPanel $panel): void
    {
        $panel->addonRoutes(fn () => require __DIR__.'/../routes/analytics.php');

        $panel->addonLivewireComponents([
            'analytics-dashboard' => \App\Livewire\Analytics\Dashboard::class,
            'analytics-report' => \App\Livewire\Analytics\Report::class,
        ]);

        $panel->addonViews('analytics', __DIR__.'/../resources/views');
    }
}

Registering an Addon

Register the addon in the register() method of your application's service provider using the Shopper facade:

use App\Addons\AnalyticsAddon;
use Shopper\Facades\Shopper;

public function register(): void
{
    Shopper::addon(new AnalyticsAddon);
}

Shopper loads the routes, sidebar classes, Livewire components, views and settings items of its addons, then calls their boot() method, when its own service provider boots. Laravel boots package service providers before your application's providers, so an addon registered in AppServiceProvider::boot() comes too late: its routes, sidebar entries, components, views and settings items are skipped without any error. Calling Shopper::addon() in register() avoids this.

The AddonManager checks isEnabled() before registering. If the addon is disabled via config, register() is never called and nothing is loaded. Registering two enabled addons with the same ID throws a LogicException.

What an Addon Can Register

Routes

Shopper loads addon routes inside its admin route group, so do not add a prefix, a name prefix or middleware yourself. Each route gets the admin panel prefix (shopper.admin.prefix, cpanel by default) and domain, the shopper. name prefix, and the middleware of the admin pages, including the ones listed in shopper.routes.middleware (see Middleware). The routes below answer at /cpanel/analytics and /cpanel/analytics/{report}, and their names are shopper.analytics.index and shopper.analytics.report:

use Illuminate\Support\Facades\Route;

$panel->addonRoutes(function () {
    Route::get('/analytics', AnalyticsDashboard::class)->name('analytics.index');
    Route::get('/analytics/{report}', AnalyticsReport::class)->name('analytics.report');
});

Call addonRoutes() in register(): Shopper loads its routes before it calls the addons' boot() method, so routes declared in boot() are never loaded. To render a Livewire page inside the admin layout, give the component Shopper's layout, as shown in Using Livewire Components.

Livewire Components

Shopper registers each alias with a shopper- prefix, like its own components. The component below is rendered with <livewire:shopper-analytics-dashboard />:

$panel->addonLivewireComponents([
    'analytics-dashboard' => \App\Livewire\Analytics\Dashboard::class,
]);

Pass a class that extends Shopper\Sidebar\AbstractAdminSidebar and adds its menu groups in extendWith(). Shopper registers it as a listener of the Shopper\Sidebar\SidebarBuilder event, as described in the sidebar extension guide. Link its items to the full route names, such as shopper.analytics.index:

$panel->addonSidebar(\App\Sidebar\AnalyticsSidebar::class);

Blade Views

Register a view namespace so your Blade views are accessible as analytics::dashboard:

$panel->addonViews('analytics', __DIR__.'/../resources/views');

Settings Items

Add cards to the Settings page. Each key is a class that extends Shopper\Settings\Setting (see Creating a Custom Setting), mapped to a boolean controlling its visibility:

$panel->addonSettingItems([
    \App\Settings\AnalyticsSetting::class => true,
]);

Permissions

Declare the permissions your addon introduces:

$panel->addonPermissions([
    'browse_analytics',
    'export_analytics',
]);

In 2.x, Shopper only keeps this list, which Shopper::addonManager()->getPermissions() returns. It does not create the permissions or give them to any role, so create them yourself, for example in a migration, as shown in Creating Custom Permissions.

Styles and Scripts

Inject additional CSS or JS assets into the admin panel's layout:

$panel->addonStyles([asset('css/analytics.css')]);

$panel->addonScripts([asset('js/analytics.js')]);

A URL that starts with http:// or https:// is used as is. Any other path goes through asset(), so 'css/analytics.css' works too.

Disabling an Addon

Set the addon's ID to false in config/shopper/addons.php (published by php artisan shopper:install):

return [
    'analytics' => false,
];

When set to false, BaseAddon::isEnabled() returns false and the addon's register() method is never called. Routes, components, sidebar entries, and assets are not loaded.

Checking if an Addon is Active

use Shopper\Facades\Shopper;

Shopper::hasAddon('analytics');

$addon = Shopper::getAddon('analytics');
$addon->getName();

hasAddon() returns false for an addon that is disabled or was never registered, and getAddon() throws a LogicException for it. Shopper::addonManager()->all() returns the active addons as a collection keyed by ID.

Full Example: A Loyalty Points Addon

Here is a complete addon that adds a loyalty points feature to the Shopper admin:

namespace App\Addons;

use Illuminate\Support\Facades\Blade;
use Illuminate\Support\Facades\Route;
use Shopper\Addon\BaseAddon;
use Shopper\ShopperPanel;
use Shopper\View\CustomerRenderHook;

final class LoyaltyAddon extends BaseAddon
{
    public function getId(): string
    {
        return 'loyalty';
    }

    public function register(ShopperPanel $panel): void
    {
        $panel->addonRoutes(function () {
            Route::prefix('loyalty')->name('loyalty.')->group(function () {
                Route::get('/', \App\Livewire\Loyalty\Index::class)->name('index');
                Route::get('/tiers', \App\Livewire\Loyalty\Tiers::class)->name('tiers');
            });
        });

        $panel->addonLivewireComponents([
            'loyalty-index' => \App\Livewire\Loyalty\Index::class,
            'loyalty-tiers' => \App\Livewire\Loyalty\Tiers::class,
            'loyalty-customer-points' => \App\Livewire\Loyalty\CustomerPoints::class,
        ]);

        $panel->addonViews('loyalty', __DIR__.'/../resources/views');

        $panel->addonSidebar(\App\Sidebar\LoyaltySidebar::class);

        $panel->addonPermissions([
            'browse_loyalty',
            'edit_loyalty',
        ]);

        $panel->addonSettingItems([
            \App\Settings\LoyaltySetting::class => true,
        ]);
    }

    public function boot(ShopperPanel $panel): void
    {
        $panel->renderHook(
            CustomerRenderHook::SHOW_TABS_END,
            fn (): string => Blade::render('<livewire:shopper-loyalty-customer-points />'),
        );
    }
}

The routes answer at /cpanel/loyalty and /cpanel/loyalty/tiers and are named shopper.loyalty.index and shopper.loyalty.tiers. A render hook returns HTML, so the Livewire tag goes through Blade::render().

Register it once in the register() method of your service provider:

use Shopper\Facades\Shopper;

Shopper::addon(new LoyaltyAddon);

Last updated on

Edit on GitHub