Building Display Plugins for the Site Store Pro Storefront

Display plugins let you inject custom HTML blocks — banners, carousels, promotional widgets, trust badges, or any storefront component — into the page layout via shortcodes. You can ship a plugin as part of the application source (a built-in plugin) or drop it into the root /plugins/ directory without touching core files (a drop-in plugin). Both approaches implement the same DisplayPlugin interface.

The DisplayPlugin Interface

Every display plugin must implement the following contract:

namespace App\Plugins\Contracts;

use App\Models\Plugin;

interface DisplayPlugin
{
    public function slug(): string;
    public function name(): string;
    public function render(array $params, Plugin $plugin): string;
}

Method	Description
`slug()`	Unique shortcode identifier used to invoke the plugin in templates
`name()`	Human-readable name shown in the admin plugin list
`render()`	Returns the HTML string to output at the shortcode location

The $params array carries any inline shortcode attributes, and the $plugin model gives you access to the persisted plugin settings configured in the admin panel.

Creating a Built-in Plugin

Built-in plugins live inside the application source tree and are registered through the service provider.

Create the Plugin Class

Add your class to app/Plugins/Display/, implementing DisplayPlugin:

<?php
namespace App\Plugins\Display;

use App\Models\Plugin;
use App\Plugins\Contracts\DisplayPlugin;

class MyCustomPlugin implements DisplayPlugin
{
    public function slug(): string
    {
        return 'my-custom';
    }

    public function name(): string
    {
        return 'My Custom Plugin';
    }

    public function render(array $params, Plugin $plugin): string
    {
        $text = $plugin->getSetting('banner_text', 'Hello, world!');
        return "<div class=\"custom-banner\">{$text}</div>";
    }
}

Open app/Providers/PluginServiceProvider.php and register your class inside the boot() method:

$manager->register(\App\Plugins\Display\MyCustomPlugin::class);

Add the Database Record and Options

Add a seeder entry for your plugin in database/seeders/PluginSeeder.php, then run:

php artisan db:seed --class=PluginSeeder

This inserts the plugin record and its configurable option fields into the plugins, plugin_options, and plugin_settings tables.

Creating a Drop-in Plugin

Drop-in plugins live in the root /plugins/ directory and require no changes to application source files. The PluginManager discovers them automatically on boot.

The PluginManager scans /plugins/*/plugin.json on every boot. As soon as you add a valid plugin directory with a plugin.json file, the platform detects it, syncs its settings to the database, and registers its shortcode — no restart or cache clear needed in development.

Directory Structure

plugins/
  my-banner-plugin/
    plugin.json
    MyBannerPlugin.php

plugin.json Schema

The plugin.json manifest describes your plugin and declares its configurable options:

{
  "class": "MyBannerPlugin",
  "name": "My Banner Plugin",
  "version": "1.0",
  "type": "display",
  "shortcode": "my-banner",
  "description": "Drop-in promotional banner plugin",
  "author": "Store Dev",
  "options": [
    {
      "field_name": "banner_text",
      "field_label": "Banner Text",
      "field_type": "input",
      "field_required": "yes",
      "sort_order": 10,
      "field_default_value": "Welcome to our store!"
    }
  ]
}

Field	Description
`class`	PHP class name (without namespace) inside the plugin directory
`type`	Must be `"display"` for display plugins
`shortcode`	The tag used to embed the plugin in templates, e.g. `[my-banner]`
`options`	Array of configurable fields exposed in the admin panel

Plugin PHP Class

Place your class file alongside plugin.json in the plugin directory:

<?php

class MyBannerPlugin implements \App\Plugins\Contracts\DisplayPlugin
{
    public function slug(): string
    {
        return 'my-banner';
    }

    public function name(): string
    {
        return 'My Banner Plugin';
    }

    public function render(array $params, \App\Models\Plugin $plugin): string
    {
        $text = $plugin->getSetting('banner_text', 'Welcome to our store!');
        return "<div class=\"promo-banner\">{$text}</div>";
    }
}

Plugin Model Helper Methods

The Plugin model injected into render() provides convenience methods for reading and writing plugin settings. All three are available to both built-in and drop-in plugins.

// Retrieve a single setting with a fallback default
Plugin::getSetting(string $key, mixed $default): mixed

// Retrieve all settings as a key => value array
Plugin::getSettings(): array

// Persist one or more settings at once
Plugin::saveSettings(array $settings): void

Usage examples:

// Retrieve a single setting with a fallback default
$value = $plugin->getSetting('banner_text', 'Default Text');

// Retrieve all settings as a key => value array
$settings = $plugin->getSettings();

// Persist one or more settings at once
$plugin->saveSettings(['banner_text' => 'New Promo Text']);

// Query all active display plugins
$activeDisplay = Plugin::scopeActive()->scopeOfType('display')->get();

Database Tables

Site Store Pro uses three tables to manage plugin state:

Table	Key Columns	Purpose
`plugins`	`api_id`, `filename`, `type`, `shortcode`, `activation_status`	Plugin registry and activation state
`plugin_options`	`field_name`, `field_type`, `field_editor`, `field_default_value`	Option field definitions
`plugin_settings`	`field_name`, `field_value`	Persisted admin-configured values

Live Search API

Site Store Pro exposes a public JSON endpoint that powers the storefront’s real-time search typeahead. You can call this endpoint directly from custom frontend components or headless integrations.

GET /api/live-search-api?q={query}

Parameter	Type	Description
`q`	`string`	The search term entered by the user

Example request:

GET /api/live-search-api?q=running+shoes

Example response:

[
  {
    "id": 42,
    "name": "Pro Running Shoes",
    "slug": "pro-running-shoes",
    "price": "89.99",
    "image": "https://cdn.example.com/products/pro-running-shoes.jpg"
  },
  {
    "id": 57,
    "name": "Trail Running Shoes",
    "slug": "trail-running-shoes",
    "price": "109.99",
    "image": "https://cdn.example.com/products/trail-running-shoes.jpg"
  }
]

The endpoint searches across product names and returns an array of matching product objects. It is unauthenticated and rate-limited by the standard Laravel throttle middleware. For full-text search configuration options, see Search & Events.

Installation

Extending the Platform

Core Services

Building Display Plugins for the Site Store Pro Storefront

The DisplayPlugin Interface

Creating a Built-in Plugin

Creating a Drop-in Plugin

Directory Structure

plugin.json Schema

Plugin PHP Class

Plugin Model Helper Methods

Database Tables

Live Search API

​The DisplayPlugin Interface

​Creating a Built-in Plugin

​Creating a Drop-in Plugin

​Directory Structure

​plugin.json Schema

​Plugin PHP Class

​Plugin Model Helper Methods

​Database Tables

​Live Search API

The DisplayPlugin Interface

Creating a Built-in Plugin

Creating a Drop-in Plugin

Directory Structure

plugin.json Schema

Plugin PHP Class

Plugin Model Helper Methods

Database Tables

Live Search API