PHPackages                             lexical-scope/banner - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. lexical-scope/banner

ActiveLibrary

lexical-scope/banner
====================

Displays a informative banner to users with FilamentPHP

1.0.1(1mo ago)01↑2900%MITPHPPHP ^8.4

Since Mar 26Pushed 1mo agoCompare

[ Source](https://github.com/lexical-scope/banner)[ Packagist](https://packagist.org/packages/lexical-scope/banner)[ Docs](https://github.com/kenepa/banner)[ GitHub Sponsors](https://github.com/kenepa)[ RSS](/packages/lexical-scope-banner/feed)WikiDiscussions 1.x Synced 1mo ago

READMEChangelog (1)Dependencies (14)Versions (2)Used By (0)

Banner
------

[](#banner)

[![](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/filament-banner-banner.png)](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/filament-banner-banner.png)[![Latest Version on Packagist](https://camo.githubusercontent.com/77aa852811cb6fb55ad08e1987b155d7b68f870eed524e35c6cbb41c776de90d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b656e6570612f62616e6e65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kenepa/banner)[![Total Downloads](https://camo.githubusercontent.com/a55a1013c9715eb7ee4ad91d575dff8da194b310d476300459d8da6e975dcb59/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b656e6570612f62616e6e65722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/kenepa/banner)

Introduction
============

[](#introduction)

Filament Banner is a powerful Filament plugin that allows you to seamlessly integrate dynamic banners into your Filament-based application. With this plugin, you can easily create, manage, and display engaging banners that can be customized to your specific needs.

Demo:

#### Create banner

[](#create-banner)

[![](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/Banner_demo_1.gif)](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/Banner_demo_1.gif)

#### Create scoped banner

[](#create-scoped-banner)

A scoped banner is only visible on the selected resource pages. [![](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/banner_demo_2.gif)](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/banner_demo_2.gif)

Features
--------

[](#features)

- **Create Multiple Banners**: Easily create and manage multiple banners within your Filament application.
- **Customize Banner Look**: Tailor the appearance of your banners to match your brand and design.
- **Optional User Closing**: Allow users to close banners if desired.
- **Banner Scheduling**: Schedule your banners to be displayed at specific times.
- **Scoped Visibility**: Control the visibility of your banners by targeting specific pages or resources within your Filament application.
- **Render Location Control**: Select the desired locations where your banners will be displayed within your application.
- **Programmatic Banner Creation**: Utilize the BannerManager Facade to create banners programmatically.
- **Links (v0.1.0 and higher)**: Add links to your banners to direct users to specific pages.

Getting started
---------------

[](#getting-started)

Before we get started, it's important to know that banners can be stored in 2 ways: **cache** and **database**.

By default, the plugin stores the banner in the cache. If you want to persist the banners in the database, you'll need to follow the additional instructions.

### Cache only

[](#cache-only)

The cache option provides a quick and easy way to get started. It's suitable for displaying occasional or temporary banners, as it's faster to get started because doesn't require additional setup. However, banners stored in the cache will be lost if the cache is cleared.

### Database

[](#database)

The database option is for users who need to use banners more extensively or require persistent storage. Storing banners in the database ensures they don't get lost, allows for better management, and offers more scalability as your application grows. By providing both options, the plugin gives you the flexibility to choose the storage method that best fits your application's requirements.

Installation
------------

[](#installation)

1. **Install the package via composer:**

    ```
    composer require kenepa/banner
    ```
2. **Setup custom theme**

In order to compile the package views correctly, we need to [create a custom Filament theme](https://filamentphp.com/docs/4.x/styling/overview#creating-a-custom-theme) **first**, and then add the following path to its content. In the `theme.css` file of the theme, add the following line:

```
@source '../../../../vendor/kenepa/banner/resources/**/*.blade.php';
```

Compile your theme:

```
npm run build
```

Run the filament upgrade command:

```
php artisan filament:upgrade
```

3. **Add plugin to your panel**```
    use Kenepa\Banner\BannerPlugin;
    use Filament\Panel;

    public function panel(Panel $panel): Panel
    {
    return $panel
           // ...
         ->plugins([
            BannerPlugin::make()
         ]);
    }
    ```

Persists banners in database (optional)
---------------------------------------

[](#persists-banners-in-database-optional)

If you want to use the database storage option, you can follow these steps:

> Note: Your database must support JSON column type

1. **Publish & run migrations**You can publish and run the migrations with:

    ```
    php artisan vendor:publish --tag="banner-migrations"
    php artisan migrate
    ```
2. **Configure the plugin**

    Add the `persistsBannersInDatabase()` the banner plugin.

    ```
     use Kenepa\Banner\BannerPlugin;
     use Filament\Panel;

     public function panel(Panel $panel): Panel
     {
     return $panel
     // ...
     ->plugins([
         BannerPlugin::make()
             ->persistsBannersInDatabase()
     ]);
     }
    ```

Usage
-----

[](#usage)

### Using the UI to create banners

[](#using-the-ui-to-create-banners)

This package provides a comprehensive banner management system, allowing you to create, view, update, and delete banners to be displayed throughout your application.

[![](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/banner_manager_screenshot.png)](https://raw.githubusercontent.com/kenepa/Kenepa/main/art/Banner/banner_manager_screenshot.png)

### Programmatically create banners

[](#programmatically-create-banners)

If you want to programmatically create banners, you can use the `BannerManager` facade. The BannerManager uses a Banner Value Object. Because this package allows you to choose how you want to store the banner, I wanted a single way to represent a banner when interacting with the BannerManager. Looking for more information about what Value Objects are and why they could be useful, [I recommend this article](https://martinjoo.dev/value-objects-everywhere).

> Note: Functionality for the BannerManager is limited at the time because this is all that I needed for the project. But feel free to make PRs to extend its functionality.

You'll need to create a Value Object first to represent the banner.

```
$bannerData = new BannerData(
    id: 'banner_123',
    name: 'Promotional Banner',
    content: 'Check out our latest sale!',
    is_active: true,
    active_since: '2024-06-01',
    icon: 'heroicon-m-wrench',
    background_type: 'gradient',
    start_color: '#FF6B6B',
    end_color: '#FFD97D',
    start_time: '09:00',
    end_time: '18:00',
    can_be_closed_by_user: true,
    text_color: '#333333',
    icon_color: '#FFFFFF',
    render_location: 'header',
    scope: []
);
```

> You'll need generate the id of the banner your self. [Tip use `uniqid()`](https://www.php.net/manual/en/function.uniqid.php)

**Create**

Now you can create the Banner using the bannerData object.

```
use Kenepa\Banner\Facades\BannerManager;

BannerManager::store($bannerData);
```

**Get All**

```
use Kenepa\Banner\Facades\BannerManager;

$banners = BannerManager::getAll();
```

**Delete**

```
use Kenepa\Banner\Facades\BannerManager;

BannerManager::delete('banner_id_123');
```

**Update**

```
use Kenepa\Banner\Facades\BannerManager;

$updatedBannerData = \Kenepa\Banner\ValueObjects\BannerData::fromArray([
    // ID must be the same
    'id' => 'banner_id',
    'name' => 'updated title'
    // ... all other properties of the banner
]);

BannerManager::update($updatedBannerData);
```

Configuring the Banner Plugin
-----------------------------

[](#configuring-the-banner-plugin)

The `BannerPlugin` class provided by the package allows you to customize various aspects of the banner management system. This includes the plugin's title, subheading, navigation settings, and more.

To customize the plugin, you can use the static `BannerPlugin::make()` method and chain the various configuration methods together.

**Title and Subheading**

You can set the title and subheading of the banner manager page using the `title()` and `subheading()` methods, respectively.

```
BannerPlugin::make()
    ->title('My Banner Manager')
    ->subheading('Manage your website banners');
```

**Navigation Settings**

The plugin also allows you to customize the navigation settings, such as the icon, label, group, and sort order.

```
BannerPlugin::make()
    ->navigationIcon('heroicon-o-megaphone')
    ->navigationLabel('Banners')
    ->navigationGroup('Marketing')
    ->navigationSort(1);
```

- `navigationIcon()`: Sets the icon to be used in the navigation menu.
- `navigationLabel()`: Sets the label to be used in the navigation menu.
- `navigationGroup()`: Sets the group in which the plugin should be placed in the navigation menu.
- `navigationSort()`: Sets the sort order of the plugin in the navigation menu.

**Disable Banner manager**You can disable the banner manager altogether. For example, if you want to disable the banner manager for a different panel without having to set permissions for that page.

```
BannerPlugin::make()
    ->disableBannerManager()
```

Authorization
-------------

[](#authorization)

### Step 1.

[](#step-1)

By default, the banner manager is available for everyone. To restrict access, you'll need to add the ability (also known as "permission" within the context of the [Spatie Permission package](https://spatie.be/docs/laravel-permission/v6/introduction)) as shown below:

```
BannerPlugin::make()
    ->bannerManagerAccessPermission('banner-manager')
```

### Step 2.

[](#step-2)

**Example using [Laravel gates](https://laravel.com/docs/master/authorization)**Inside the `boot()` method of your service provider define a gate with the same name you have configured for the plugin.

```
// app/Providers/AppServiceProvider.php

   public function boot()
    {
        Gate::define('banner-manager', function (User $user) {
           return $user->email === 'admin@mail.com';
        });
    }
```

**Example using [spatie permission package](https://spatie.be/docs/laravel-permission/v6/introduction)**This example shows how to create a permission and assign it a users

```
$permission = Permission::create(['name' => 'banner-manager'])
auth()->user()->givePermissionTo($permission)
```

After the correct ability/permissions have been created and assigned, the banner manager will only be available to a select group of users.

Optional
--------

[](#optional)

### Publishing views

[](#publishing-views)

```
php artisan vendor:publish --tag="banner-views"
```

Testing
-------

[](#testing)

```
composer test
```

Upgrade Guide
-------------

[](#upgrade-guide)

### Upgrading from 0.x to 1.x

[](#upgrading-from-0x-to-1x)

#### Step 1: Theme Configuration (Required)

[](#step-1-theme-configuration-required)

**Breaking Change**: Filament v4 requires a different approach for including package assets.

**Remove from `tailwind.config.js` (if present):**

```
// Remove this from your tailwind.config.js content array:
'./vendor/kenepa/banner/resources/**/*.blade.php'
```

**Add to your custom theme CSS file:**

1. Create a custom theme if you don't have one ([Filament v4 theme docs](https://filamentphp.com/docs/4.x/panels/themes#creating-a-custom-theme))
2. Add this line to your theme's CSS file:

```
@source '../../../../vendor/kenepa/banner/resources/**/*.blade.php';
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Jehizkia](https://github.com/kenepa)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 83.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/1ff5413a07a7c477d7d3c5627c27f985e907da9ed3202ffc5f09af522263596f?d=identicon)[dcrawkstar](/maintainers/dcrawkstar)

---

Top Contributors

[![Jehizkia](https://avatars.githubusercontent.com/u/8775667?v=4)](https://github.com/Jehizkia "Jehizkia (95 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (5 commits)")[![devSviat](https://avatars.githubusercontent.com/u/178153165?v=4)](https://github.com/devSviat "devSviat (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")[![grafst](https://avatars.githubusercontent.com/u/8471055?v=4)](https://github.com/grafst "grafst (2 commits)")[![lexical-scope](https://avatars.githubusercontent.com/u/697620?v=4)](https://github.com/lexical-scope "lexical-scope (1 commits)")[![Cannonb4ll](https://avatars.githubusercontent.com/u/3110750?v=4)](https://github.com/Cannonb4ll "Cannonb4ll (1 commits)")[![ConnorHowell](https://avatars.githubusercontent.com/u/4037845?v=4)](https://github.com/ConnorHowell "ConnorHowell (1 commits)")[![fadymondy](https://avatars.githubusercontent.com/u/11937812?v=4)](https://github.com/fadymondy "fadymondy (1 commits)")[![a21ns1g4ts](https://avatars.githubusercontent.com/u/11599205?v=4)](https://github.com/a21ns1g4ts "a21ns1g4ts (1 commits)")

---

Tags

laravelbannerKenepa

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/lexical-scope-banner/health.svg)

```
[![Health](https://phpackages.com/badges/lexical-scope-banner/health.svg)](https://phpackages.com/packages/lexical-scope-banner)
```

###  Alternatives

[joaopaulolndev/filament-edit-profile

Filament package to edit profile

250258.1k34](/packages/joaopaulolndev-filament-edit-profile)[kenepa/banner

Displays a informative banner to users

9430.1k2](/packages/kenepa-banner)[guava/filament-knowledge-base

A filament plugin that adds a knowledge base and help to your filament panel(s).

206120.5k1](/packages/guava-filament-knowledge-base)[marcelweidum/filament-expiration-notice

Customize the livewire expiration notice

9169.0k4](/packages/marcelweidum-filament-expiration-notice)[guava/filament-modal-relation-managers

Allows you to embed relation managers inside filament modals.

7565.0k4](/packages/guava-filament-modal-relation-managers)[hydrat/filament-table-layout-toggle

Filament plugin adding a toggle button to tables, allowing user to switch between Grid and Table layouts.

6292.3k1](/packages/hydrat-filament-table-layout-toggle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)