Popup Card Laravel Package

Getting Started

Install the package with Composer and run the publish step so you get the config file, migrations, and front-end assets in place:

composer require <vendor>/<package>   # 2.0.6
php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
php artisan migrate

Look at these three places first, in this order:

1. config/<package>.php — the defaults for rendering, caching, and (as of 2.0.6) preview behaviour.
2. The published migrations — they tell you the shape of the popup record (status, schedule, targeting columns) faster than any doc.
3. The package's Blade view/component directory — that's where you'll be overriding markup.

Your first use case should be the smallest end-to-end loop: create a single popup record, render it on one page, and confirm it appears. As of 2.0.6, do that loop entirely through Popup Preview instead of publishing to a staging environment — build the popup, hit Preview, iterate on copy and layout, and only flip it to published once it looks right. That single feature removes the publish → deploy → check → unpublish cycle that used to eat most of the feedback time on this kind of package.

Note that 2.0.6 is a patch release on the 2.x line. There are no breaking changes, no deprecations, and no config or migration changes implied. Upgrading is a composer update and, if you cache config, a php artisan config:clear.

Implementation Patterns

Treat the preview as your development loop, not a QA step. The healthy workflow with 2.0.6 is: author the popup as a draft, preview it repeatedly while tuning, then publish. If your team currently maintains a "staging popup" record purely for review, retire it — the preview replaces it and eliminates the risk of a review popup leaking into production data.

Renderer in the layout, targeting in the model. Keep the render call in your base layout (a single Blade component or directive near the end of <body>), and keep all "should this show?" logic in the popup record's own fields — schedule window, page/route targeting, audience. Resisting the urge to wrap the render call in your own @if conditions is what keeps the package's built-in caching effective.

Preview needs a guard, not just a route. Preview necessarily renders unpublished content, which means it bypasses whatever published/active scoping the front-end renderer applies. Gate it behind the package's authorization callback (or a can check in the config) so it's restricted to authenticated staff, and explicitly disable it in the production config if the package exposes that switch. This is the one place where a convenience feature can become an information leak.

Overrides via publish tags, not edits in vendor/. Publish only the views you actually need to change. Overriding the wrapper view to add your own container classes or analytics attributes is normal; forking the JS is a maintenance trap, because a patch bump can silently diverge from your copy.

Drive content from your own models. Rather than hand-writing popup copy in an admin, hydrate popups from Eloquent records (promotions, announcements, onboarding steps) and let a scheduled command or observer keep them in sync. This makes preview far more useful: you preview the popup as it will render for real data, not for lorem ipsum.

Test the render, not the admin. A feature test that hits a route and asserts the popup markup is present catches far more regressions than testing the CRUD layer. Cover three cases: published popup renders, draft popup does not render on the public route, and draft popup does render through the preview path for an authorized user.

Gotchas and Tips

• Preview ≠ published. Because preview renders draft content, layout issues can appear in preview that vanish once published (or vice versa) if your published scoping also filters by schedule or audience. Always do one final check on a published record before signing off.
• Config cache. After changing anything in config/<package>.php — including preview settings — run php artisan config:clear. A stale cached config is the single most common cause of "the setting isn't taking effect."
• Asset cache busting. If popups render with stale styles after upgrading to 2.0.6, clear compiled views and republish assets (view:clear, plus your asset build). Preview may render correct markup with outdated CSS, which is confusing to debug.
• Frequency and session state. Popups that are shown-once or dismissed-per-session use session/cookie state. Previewing repeatedly can trip that logic and make a popup look broken when it's actually correctly suppressed. Test suppression in a fresh session, not the one you've been previewing in.
• Migrations on existing installs. Nothing in 2.0.6 requires a migration, but if you're coming from 1.x, check the migrations directory against your migrations table before running migrate blind.
• Debugging order. Popup not rendering? Check, in order: is the render call actually in the layout being used (not a different layout for that route), is the record published and inside its schedule window, is the target route matching as you expect, and is cached markup being served? Preview bypasses several of these checks, so a popup that previews fine can still fail all four on the public route.
• Extension point worth knowing. The authorization/preview-gate callback is the right hook for team-based access control; the render pipeline is the right hook for injecting analytics. Avoid reaching into the package's internals for either.