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:
| Method | Return | Description |
|---|---|---|
getId() | string | Unique kebab-case identifier (my-addon), also the addon's key in config/shopper/addons.php |
getName() | string | Display name; BaseAddon derives it from getId() automatically (loyalty-points becomes Loyalty Points) |
register(ShopperPanel $panel) | void | Called by Shopper::addon() when the addon is enabled, bind routes, components, views, settings |
boot(ShopperPanel $panel) | void | Called when Shopper boots, after all addons are registered, use for cross-addon dependencies; empty in BaseAddon |
isEnabled() | bool | BaseAddon 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,
]);Sidebar Navigation
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