PHPackages                             elshaden/popup-card - 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. [Mail & Notifications](/categories/mail)
4. /
5. elshaden/popup-card

ActiveLibrary[Mail & Notifications](/categories/mail)

elshaden/popup-card
===================

A customizable popup modal card for Laravel Nova that automatically displays to users when they access your dashboard or resource pages.

2.0.6(9mo ago)32MITPHPPHP ^8.0|^8.1|^8.2

Since Feb 23Pushed 9mo ago1 watchersCompare

[ Source](https://github.com/Elshaden/popup-card)[ Packagist](https://packagist.org/packages/elshaden/popup-card)[ Docs](https://github.com/elshaden/popup-card)[ RSS](/packages/elshaden-popup-card/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (18)Used By (0)

Laravel Nova Popup Card
=======================

[](#laravel-nova-popup-card)

[![Latest Version on Packagist](https://camo.githubusercontent.com/8fc8e077d5a995ac1ef317c017df65df6dec73304d8973df523d97c3d5e6cc7d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f656c73686164656e2f706f7075702d636172642e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/elshaden/popup-card)[![Total Downloads](https://camo.githubusercontent.com/f971ddb8221b35548a2894eca8a2c6c2dd4024450c4a78dffbcd0c7204629ae0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f656c73686164656e2f706f7075702d63617264)](https://packagist.org/packages/elshaden/popup-card)[![License](https://camo.githubusercontent.com/b8cadaa967891081f8f165695470689986c028821dd8a040132f6e661795dc0d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c7565)](https://github.com/elshaden/popup-card/blob/main/LICENSE.md)[![GitHub Stars](https://camo.githubusercontent.com/3776eaf1125dea7114a7054e828947e251b61a7cce959ed547af07285d6f8ebc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f656c73686164656e2f706f7075702d63617264)](https://github.com/elshaden/popup-card/stargazers)

A customizable popup modal card for Laravel Nova that automatically displays to users when they access your dashboard or resource pages. Perfect for welcome messages, announcements, notifications, and more.

🌟 Features
----------

[](#-features)

- **Automatic Display**: Shows popup cards to users when they access specified pages
- **User Tracking**: Remembers which users have seen which popups
- **Do Not Show Again**: Users can opt out of seeing specific popups again
- **Customizable Content**: Full HTML support for rich content in popups
- **Configurable Width**: Choose from multiple width options (1/4, 1/3, 1/2, 2/3, 3/4, full)
- **Targeted Display**: Show different popups on different pages or to specific users
- **Admin Interface**: Manage all your popup cards through a Nova resource
- **Database Storage**: All popup cards and user interactions are stored in the database
- **Configurable Tables**: Customize database table names to fit your application

Example
-------

[](#example)

Here's an example of how a welcome popup from ACME Company might look:

 [![ACME Welcome Popup](docs/images/sample.png)](docs/images/sample.png)

*Note: Create this image based on the specifications in docs/images/sample-popup-instructions.md*

Compatibility
-------------

[](#compatibility)

- Laravel Nova 4.x and 5.x
- PHP > = 8.0 up To 8.4
- Laravel >=9.x up to 12.x

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

[](#installation)

You can install the package in Laravel Nova app that uses Nova via composer:

```
composer require elshaden/popup-card
```

Package Registration
--------------------

[](#package-registration)

The package will be automatically registered using Laravel's package auto-discovery. However, if you have disabled auto-discovery, you need to manually register the package's service provider in your `config/app.php` file:

```
'providers' => [
    // ...
    Elshaden\PopupCard\CardServiceProvider::class,
],
```

Configuration
-------------

[](#configuration)

You can publish the config file with:

```
   php artisan vendor:publish --provider="Elshaden\PopupCard\CardServiceProvider" --tag="popup-card-config"
```

### Database Table Configuration

[](#database-table-configuration)

The package allows you to customize the database table names and foreign keys used by the popup card system. This is useful if you need to avoid table name conflicts or follow specific naming conventions in your application.

Available configuration options:

```
// config/popup_card.php

// The name of the main table for popup cards
'table_name' => 'popup_cards',

// The name of the pivot table between users and popup cards
'pivot_table' => 'cards_users',

// The foreign key for the user in the pivot table
'user_foreign_key' => 'user_id',

// The foreign key for the popup card in the pivot table
'popup_card_foreign_key' => 'popup_card_id',
```

#### Example: Customizing Table Names

[](#example-customizing-table-names)

If you want to use custom table names, you can modify these values in your published configuration file:

```
// config/popup_card.php

// Use a custom table name for popup cards
'table_name' => 'my_custom_popup_cards',

// Use a custom pivot table name
'pivot_table' => 'my_custom_popup_card_user',
```

After changing these values, make sure to run the migrations to create the tables with your custom names.

#### Configuration Content

[](#configuration-content)

```
 /*
    |--------------------------------------------------------------------------
    | General Settings
    |--------------------------------------------------------------------------
    */

    // Whether the popup modal is enabled.
    'enabled' => true,

    // Modal size (1/4, 1/3, 1/2, 2/3, 3/4, full)
    'card_width' => '1/2',

    // Enable or disable showing the users in the PopupCards Resource
    'show_seen_by_users'=>false,

    // Enable or disable showing the user count in the PopupCards Resource
    'show_users_count'=>true,

    /*
    |--------------------------------------------------------------------------
    | Database Table Settings
    |--------------------------------------------------------------------------
    */

    // The name of the main table for popup cards
    'table_name' => 'popup_cards',

    /*
    |--------------------------------------------------------------------------
    | User Model and Relationship Settings
    |--------------------------------------------------------------------------
    */

    // The model class to use for users
    'user_model' => 'App\Models\User',

    // The name of the pivot table between users and popup cards
    'pivot_table' => 'cards_users',

    // The foreign key for the user in the pivot table
    'user_foreign_key' => 'user_id',

    // The foreign key for the popup card in the pivot table
    'popup_card_foreign_key' => 'popup_card_id',

    'user_nova_resource'=> 'App\Nova\User',
```

Migrations
----------

[](#migrations)

You can publish the migration with:

```
php artisan vendor:publish --provider="Elshaden\PopupCard\CardServiceProvider" --tag="popup-card-migrations"
```

After publishing the migration, you can create the necessary database tables by running the migrations:

```
php artisan migrate
```

This will create two tables:

- `popup_cards`: Stores all your popup cards with their content and settings
- `cards_users`: Pivot table that tracks which users have seen which popup cards

Usage
-----

[](#usage)

### Basic Setup

[](#basic-setup)

1. **Add the Trait to Your User Model**

You **MUST** add the `HasPopupCards` trait to your user model. This enables tracking which users have seen which popups:

```
use Elshaden\PopupCard\Traits\HasPopupCards;

class User extends Authenticatable
{
    use HasPopupCards;

    // rest of your model...
}
```

2. **Register the Resource in Nova's Menu**

Add the PopupCard resource to your Nova menu to manage popup cards:

```
use Elshaden\PopupCard\Nova\PopupCardResource;

Nova::mainMenu(function (Request $request) {
    return [
        // Other menu items...
        MenuItem::resource(PopupCardResource::class)->canSee(fn()=>config('popup_card.enabled')),
        // More menu items...
    ];
});
```

### Adding Popup Cards to Pages

[](#adding-popup-cards-to-pages)

You can add popup cards to your dashboard or any resource page. The popup will automatically display when users visit that page.

> **Important**: The name you use in the `->name()` method must match the name of an existing popup card in your database. You need to create the popup card first using the Nova admin panel before you can display it in your code.

#### Dashboard Example

[](#dashboard-example)

```
use Elshaden\PopupCard\PopupCard;

public function cards(Request $request)
{
    return [
        // Other cards...
        (new PopupCard())->name('welcome-message')->width('1/2'),
    ];
}
```

In this example, a popup card with the name "welcome-message" must already exist in your database.

#### Resource Example

[](#resource-example)

```
use Elshaden\PopupCard\PopupCard;

public function cards(Request $request)
{
    return [
        // Other cards...
        (new PopupCard())->name('user-instructions')->width('1/3'),
    ];
}
```

Similarly, a popup card with the name "user-instructions" must already exist in your database.

### Customizing Display Conditions

[](#customizing-display-conditions)

You can control who sees the popup using Nova's `canSee()` method:

```
use Elshaden\PopupCard\PopupCard;

public function cards(Request $request)
{
    return [
        // Other cards...
        (new PopupCard())
            ->name('2fa-reminder')
            ->width('1/3')
            ->canSee(function () use ($request) {
                // Only show to users without 2FA enabled
                return !$request->user()->hasTwoFactorEnabled();
            }),
    ];
}
```

In this example, a popup card with the name "2fa-reminder" must already exist in your database. This popup would only be shown to users who don't have two-factor authentication enabled.

### Width Options

[](#width-options)

You can customize the width of your popup card using one of these options:

- `'1/4'` - 25% of screen width
- `'1/3'` - 33% of screen width
- `'1/2'` - 50% of screen width
- `'2/3'` - 66% of screen width
- `'3/4'` - 75% of screen width
- `'full'` - 100% of screen width

### How It Works: Complete Workflow

[](#how-it-works-complete-workflow)

Here's a step-by-step explanation of how the popup card system works:

1. **Create a Popup Card in Nova Admin Panel**

    - Navigate to the PopupCard resource in your Nova admin panel
    - Click "Create Popup Card"
    - Fill in the required fields:

        - **Name**: A unique identifier (e.g., "2fa-reminder") - this is crucial!
        - **Title**: The title displayed at the top of the popup
        - **Body**: The content of the popup (supports HTML)
    - Set "Published" and "Active" to true
    - Save the popup card

        2. **Reference the Popup Card in Your Code**

        - In your dashboard or resource file, add the PopupCard to the cards method
        - Use the **exact same name** you specified in the admin panel:
        - Optionally add conditions using `canSee()` to control who sees the popup

        ```
          public function cards(): array
         {
            return [
               //....
                 (new PopupCard())->name('2fa-reminder')->width('1/3')
               //...
             ];
         }
        ```
2. **User Experience**

    - When a user visits the page, the system checks if there's an active popup card with the specified name
    - If found and the user hasn't seen it before, the popup is displayed
    - The user can close the popup or choose not to see it again

This name-based reference system allows you to create different popup cards for different parts of your application and control them centrally through the Nova admin panel.

### Managing Popup Cards

[](#managing-popup-cards)

Using the PopupCard resource in Nova, you can:

- Create new popup cards with custom titles and content
- Edit existing popup cards
- Publish or unpublish popup cards
- View which users have seen each popup

#### Creating Popup Cards

[](#creating-popup-cards)

When creating a popup card in the Nova admin panel

1. The **name** field must be unique for each popup card
2. This name is used to reference the popup card in your code via the `->name()` method
3. The popup card must be created in the admin panel **before** it can be displayed in your code

#### User Interaction

[](#user-interaction)

The system will automatically show the latest active and published popup card to users when they access the page where the popup is configured. Users can:

- Close the popup card
- Choose to not see the popup again by checking the "Do Not Show Again" option

Testing
-------

[](#testing)

This package includes a comprehensive test suite. To run the tests:

1. Install development dependencies:

```
composer install --dev
```

2. Run the tests:

```
vendor/bin/phpunit
```

### Available Test Suites

[](#available-test-suites)

- **Unit Tests**: Test individual components in isolation

    ```
    vendor/bin/phpunit --testsuite=Unit
    ```
- **Feature Tests**: Test API endpoints and integration

    ```
    vendor/bin/phpunit --testsuite=Feature
    ```

### Test Coverage

[](#test-coverage)

Generate a test coverage report:

```
vendor/bin/phpunit --coverage-html coverage
```

For more detailed information about testing, including how to run tests from a project that has installed this package (using either PHPUnit or Pest PHP), refer to the [README-testing.md](README-testing.md) file.

If you encounter any issues while using this package, please check the [README-troubleshooting.md](README-troubleshooting.md) file for common solutions.

License
-------

[](#license)

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

Credits
-------

[](#credits)

- [Elshaden](https://github.com/elshaden) - Package Creator and Maintainer

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

[](#contributing)

Please feel free to fork this package and contribute by submitting a pull request to enhance the functionalities. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on how to contribute.

Security
--------

[](#security)

If you discover any security related issues, please email  instead of using the issue tracker. All security vulnerabilities will be promptly addressed.

Support
-------

[](#support)

Thank you for using this package! If you encounter any issues or have questions:

1. Check the [README-troubleshooting.md](README-troubleshooting.md) file for common solutions
2. Search the [issue tracker](https://github.com/elshaden/popup-card/issues) to see if your issue has already been reported
3. Open a new issue with a clear description and reproduction steps if needed

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance57

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~9 days

Recently: every ~0 days

Total

17

Last Release

288d ago

Major Versions

0.1.6 → 1.0.02025-04-19

1.0.4 → 2.0.02025-07-27

### Community

Maintainers

![](https://www.gravatar.com/avatar/b2b7d966d6b72d533ef1afdb7b498c9bf306fc480fb6563bcd8cdf47c21b1a27?d=identicon)[Elshaden](/maintainers/Elshaden)

---

Top Contributors

[![Elshaden](https://avatars.githubusercontent.com/u/33955172?v=4)](https://github.com/Elshaden "Elshaden (28 commits)")

---

Tags

laravelnotificationmodalpopupcardnovalaravel-nova announcement

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/elshaden-popup-card/health.svg)

```
[![Health](https://phpackages.com/badges/elshaden-popup-card/health.svg)](https://phpackages.com/packages/elshaden-popup-card)
```

###  Alternatives

[inspheric/nova-email-field

A Laravel Nova email field.

33456.9k1](/packages/inspheric-nova-email-field)[markwalet/nova-modal-response

A Laravel Nova asset for Modal responses on an action.

14720.0k](/packages/markwalet-nova-modal-response)[coreproc/nova-notification-feed

A Laravel Nova package that adds a notification feed in your Nova app.

10149.1k](/packages/coreproc-nova-notification-feed)[norman-huth/nova-assets-changer

Change Nova resources

2570.1k](/packages/norman-huth-nova-assets-changer)[naif/nova-push-notification

A Laravel Nova tool to send push notifications via OneSignal

166.4k](/packages/naif-nova-push-notification)[jstoone/nova-mailman

Conveniently route all emails to a local mailbox.

454.1k](/packages/jstoone-nova-mailman)

PHPackages © 2026

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