unusualdope/banner-manager

A Laravel package for managing banners with Blade directives, Flux UI admin interface, and optional translations

dev-main 2026-02-26 04:24 UTC

Requires

• php: ^8.2
• illuminate/support: ^10.0|^11.0|^12.0
• livewire/livewire: ^4.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Unusual Dope

README

A Laravel package for managing banners with Blade directives, Flux UI admin interface, and optional multi-language support.

Features

• Flux UI Integration: Modern, responsive admin interface using Flux components.
• Group Management: Organize banners into logical groups (e.g., Homepage Hero, Sidebar).
• Flexible Content: Manage images, titles, descriptions, links, and buttons.
• Optional Translations: Toggle between single-language and multi-language banners per banner.
• Smart Carousel: Default view automatically creates an auto-playing carousel for multiple banners.
• Caching: Optimized performance with automatic cache management.

Installation

The package is installed via local path repository in this project.

Database Setup

Run the migrations:

php artisan migrate

Or publish the migrations first:

php artisan vendor:publish --tag=banner-manager-migrations
php artisan migrate

Configuration

Publish the config file:

php artisan vendor:publish --tag=banner-manager-config

This will create config/banner-manager.php where you can configure:

• supported_locales: List of languages (e.g., ['it', 'en'])
• default_locale: Fallback language
• admin_route_prefix: URL prefix for admin routes (default: admin)
• default_view: Template for @cmsbanner directive

Usage

Admin Interface

Access the banner manager at: /admin/banner-manager

Managing Groups

1. Create Group: Click "Create Group" on the index page.
2. Edit Group: Click "Manage" on any group card. This takes you to the group edit page where you can also manage its banners.

Managing Banners

Banners are managed directly from their parent group's edit page.

1. Go to a group's edit page.
2. Scroll to the "Banners" section.
3. Add Banner: Click the "+" button to open the banner creation page.
4. Edit Banner: Click the pencil icon on any banner in the list.
5. Translations: Toggle "Enable translations" to switch between single-language and multi-language mode.
6. Sort Order: Banners are displayed based on the "Sort Order" field (lower numbers first).

Displaying Banners

Use the @cmsbanner Blade directive in your views:

1. Default View (Carousel)

Displays banners using the default package view. If multiple banners exist in the group, it automatically renders an auto-playing carousel with slide transitions.

@cmsbanner('homepage-hero')

2. Custom View

Pass a custom view path to render banners with your own HTML structure.

@cmsbanner('homepage-hero', ['view' => 'front.banner-manager.hero'])

3. Custom CSS Class

Add custom classes to the banner container.

@cmsbanner('sidebar-ads', ['class' => 'my-8 rounded-xl'])

Programmatic Usage

You can use the BannerService to retrieve banners directly in your controllers or PHP code:

use Unusualdope\BannerManager\Services\BannerService;

$service = app(BannerService::class);

// Get all banners for a group
$banners = $service->getBanners('homepage-hero');

// Get banners for a specific locale
$banners = $service->getBanners('homepage-hero', 'en');

// Clear cache for a group
$service->clearCache('homepage-hero');

Database Structure

banner_groups

• id, name, slug, description, is_active, timestamps

banners

• id, banner_group_id
• sort_order, is_active
• start_date, end_date
• is_translatable (boolean)
• timestamps

banner_translations

• id, banner_id, locale
• title, description
• image, link_url
• button_text, alt_text
• additional_data (JSON)
• timestamps

Publishing Views

To customize the default views:

php artisan vendor:publish --tag=banner-manager-views

This publishes views to resources/views/front/banner-manager/.