PHPackages                             effina/larastitial - 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. [Utility & Helpers](/categories/utility)
4. /
5. effina/larastitial

ActiveLibrary[Utility & Helpers](/categories/utility)

effina/larastitial
==================

A Laravel package for managing interstitials (modals, full-page redirects, inline content blocks) with configurable triggers, audience targeting, and frequency control.

1.0.7(6mo ago)0262MITPHPPHP ^8.2CI failing

Since Dec 17Pushed 6mo agoCompare

[ Source](https://github.com/effina/Larastitial)[ Packagist](https://packagist.org/packages/effina/larastitial)[ RSS](/packages/effina-larastitial/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (5)Versions (3)Used By (0)

Larastitial
===========

[](#larastitial)

A Laravel package for managing interstitials (modals, full-page redirects, inline content blocks) with configurable triggers, audience targeting, frequency control, and optional admin UI.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 10.x, 11.x, or 12.x

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

[](#installation)

```
composer require effina/larastitial
```

Run the install command:

```
php artisan larastitial:install
```

Or manually publish and migrate:

```
php artisan vendor:publish --tag=larastitial-config
php artisan vendor:publish --tag=larastitial-migrations
php artisan migrate
```

### Middleware Registration

[](#middleware-registration)

The package automatically registers its middleware to the `web` middleware group. If auto-registration doesn't work (common in Laravel 11+), manually register it:

**Laravel 11+ (`bootstrap/app.php`):**

```
use effina\Larastitial\Http\Middleware\CheckInterstitials;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->appendToGroup('web', CheckInterstitials::class);
    })
    // ...
```

**Laravel 10 (`app/Http/Kernel.php`):**

```
protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \effina\Larastitial\Http\Middleware\CheckInterstitials::class,
    ],
];
```

To verify the middleware is registered:

```
dd(app('router')->getMiddlewareGroups()['web']);
```

Quick Start
-----------

[](#quick-start)

### 1. Create an Interstitial

[](#1-create-an-interstitial)

Visit `/admin/interstitials` to use the built-in admin UI, or create one programmatically:

```
use effina\Larastitial\Models\Interstitial;

Interstitial::create([
    'name' => 'welcome-message',
    'title' => 'Welcome!',
    'type' => 'modal',
    'content' => 'Thanks for signing up!',
    'trigger_event' => \Illuminate\Auth\Events\Login::class,
    'audience_type' => 'authenticated',
    'frequency' => 'once',
]);
```

### 2. Configure Event Listeners

[](#2-configure-event-listeners)

In `config/larastitial.php`, enable the events you want to trigger interstitials:

```
'event_listeners' => [
    \Illuminate\Auth\Events\Login::class,
    \Illuminate\Auth\Events\Registered::class,
],
```

### 3. Display in Your Views

[](#3-display-in-your-views)

For modals, add this to your layout:

```
@interstitials('modal')

@endinterstitials
```

For inline content:

```
@interstitial('inline', 'sidebar-promo')
```

Interstitial Types
------------------

[](#interstitial-types)

### Modal

[](#modal)

Overlay dialogs that appear on top of the current page.

### Full Page

[](#full-page)

Redirects user to a dedicated interstitial page before continuing.

### Inline

[](#inline)

Renders content within the page at named slots.

Triggers
--------

[](#triggers)

- **Event-based**: Trigger on Laravel events (Login, Registered, custom events)
- **Route-based**: Trigger on specific routes (supports wildcards)
- **Scheduled**: Show only within date/time ranges
- **Manual**: Queue interstitials programmatically

Audience Targeting
------------------

[](#audience-targeting)

- **All users**: Show to everyone
- **Authenticated**: Logged-in users only
- **Guests**: Non-authenticated visitors only
- **Roles**: Users with specific roles
- **Custom**: Implement your own condition class

Frequency Control
-----------------

[](#frequency-control)

- **Always**: Show every time conditions are met
- **Once**: Show once per user, ever
- **Once per session**: Show once per browser session
- **Every X days**: Show again after specified days

Frontend Modes
--------------

[](#frontend-modes)

Configure in `config/larastitial.php`:

```
'frontend' => 'blade', // blade, livewire, inertia, headless
```

### Headless/API Mode

[](#headlessapi-mode)

For SPAs, use the JSON API:

```
GET /api/interstitials/applicable?context=page_load
GET /api/interstitials/{uuid}
POST /api/interstitials/{uuid}/action
POST /api/interstitials/{uuid}/respond

```

Using the Facade
----------------

[](#using-the-facade)

```
use effina\Larastitial\Facades\Larastitial;

// Get applicable interstitials
$interstitials = Larastitial::getApplicable($user, 'page_load');

// Check if should show
if (Larastitial::shouldShow($interstitial, $user)) {
    // Display interstitial
}

// Mark as viewed
Larastitial::markViewed($interstitial, $user, 'completed');

// Record form response
Larastitial::recordResponse($interstitial, $user, $request->all());
```

User Model Trait
----------------

[](#user-model-trait)

Add the trait to your User model for convenience methods:

```
use effina\Larastitial\Traits\HasInterstitials;

class User extends Authenticatable
{
    use HasInterstitials;
}

// Then use:
$user->hasViewedInterstitial($id);
$user->hasCompletedInterstitial($id);
$user->getViewedInterstitialIds();
```

Custom Audience Conditions
--------------------------

[](#custom-audience-conditions)

Create a class implementing `AudienceCondition`:

```
use effina\Larastitial\Contracts\AudienceCondition;
use effina\Larastitial\Models\Interstitial;

class HasCompletedProfile implements AudienceCondition
{
    public function passes(?Authenticatable $user, Interstitial $interstitial): bool
    {
        return $user && $user->profile_completed_at !== null;
    }
}
```

Then reference it in your interstitial's `audience_condition` field.

Multi-Tenancy
-------------

[](#multi-tenancy)

Enable in config:

```
'multi_tenant' => [
    'enabled' => true,
    'column' => 'tenant_id',
    'resolver' => \App\Services\TenantResolver::class,
],
```

Implement the resolver:

```
use effina\Larastitial\Contracts\TenantResolver;

class TenantResolver implements TenantResolver
{
    public function resolve(): int|string|null
    {
        return auth()->user()?->tenant_id;
    }
}
```

Testing
-------

[](#testing)

Use the fake for testing:

```
use effina\Larastitial\Facades\Larastitial;

public function test_interstitial_triggers_on_login(): void
{
    $fake = Larastitial::fake();

    $interstitial = Interstitial::factory()->create();
    $fake->shouldTrigger($interstitial);

    // ... perform action

    $fake->assertTriggered($interstitial->name);
}
```

Use the factory for creating test data:

```
use effina\Larastitial\Models\Interstitial;

$interstitial = Interstitial::factory()
    ->modal()
    ->forAuthenticated()
    ->showOnce()
    ->triggeredByEvent(\Illuminate\Auth\Events\Login::class)
    ->create();
```

Events
------

[](#events)

Listen to these events for custom logic:

- `InterstitialTriggered` - When an interstitial should be shown
- `InterstitialViewed` - When user sees an interstitial
- `InterstitialDismissed` - When user dismisses
- `InterstitialCompleted` - When user completes (CTA/form)
- `InterstitialResponseSubmitted` - When form is submitted

Commands
--------

[](#commands)

```
# Install package
php artisan larastitial:install

# Publish specific resources
php artisan larastitial:publish --config
php artisan larastitial:publish --views
php artisan larastitial:publish --all

# Clean up old view records
php artisan larastitial:cleanup --days=90
```

Customization
-------------

[](#customization)

### Publishing Views

[](#publishing-views)

```
php artisan vendor:publish --tag=larastitial-views
```

Views are published to `resources/views/vendor/larastitial/`.

### Custom Styling

[](#custom-styling)

The package ships with minimal, unstyled components. Publish the views and customize to match your application's design system.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) for details.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance66

Regular maintenance activity

Popularity15

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

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 ~0 days

Total

2

Last Release

198d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/60788208?v=4)[bigmre](/maintainers/bigmre)[@BigMrE](https://github.com/BigMrE)

---

Top Contributors

[![erikcaineolson](https://avatars.githubusercontent.com/u/3111583?v=4)](https://github.com/erikcaineolson "erikcaineolson (9 commits)")

---

Tags

laravelmodalsonboardingannouncementspopupsinterstitials

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/effina-larastitial/health.svg)

```
[![Health](https://phpackages.com/badges/effina-larastitial/health.svg)](https://phpackages.com/packages/effina-larastitial)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/ai

The official AI SDK for Laravel.

1.0k3.2M194](/packages/laravel-ai)[illuminate/queue

The Illuminate Queue package.

21332.6M1.6k](/packages/illuminate-queue)[api-platform/laravel

API Platform support for Laravel

58170.8k14](/packages/api-platform-laravel)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45444.2k1](/packages/pressbooks-pressbooks)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

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