Flexyadminframe Bundle Laravel Package

Getting Started

This is a pre-1.0 package (0.1.x), so treat the README as the primary source of truth and pin the exact version in composer.json ("vendor/package": "0.1.6.1") until the API stabilises.

1. Install and publish. composer require the package, then run php artisan vendor:publish --provider="...ServiceProvider" to expose the config and any front-end assets. Check config/ for the published file before writing any code — the persistence behaviour described below is driven from there or from a hard-coded default.
2. Where to look first. In order: the published config, the package's Blade/view or component namespace (usually registered as x-package::... or a vendor-prefixed component), and the service provider's boot() for any asset/session registration. The navigation-tab feature is almost certainly a small Blade partial plus a persistence layer (session, cookie, or localStorage), so the whole surface area is small.
3. First use case. Wrapping your admin/settings navigation in the package's tab component so the active tab survives a page reload or a round-trip to a detail page and back. That alone removes a common chunk of bespoke Alpine/vanilla JS from every project.

Start with a single nav block in a staging environment, confirm the tab state persists across a hard refresh, then roll it out.

Implementation Patterns

Declarative tabs in Blade. Define tabs in the template and let the package own the "which one is active" state. Keep tab labels/keys semantic and stable (billing, team, api-keys) rather than index-based — you'll want those keys to survive reordering and to match your route names.

Server-render the active state. Prefer a pattern where the server resolves the active tab (from session or a query string) and renders the correct panel, with the client-side layer only handling optimistic toggling. This keeps deep links, back-button behaviour, and non-JS fallbacks working.

Route-driven vs. state-driven tabs. Two viable integrations:

• Route-driven: each tab maps to a URL; the package only supplies styling and the "remembered" behaviour is a convenience on top of real navigation. More robust, better for bookmarking and analytics.
• Panel-driven: tabs swap content in place. Cheaper, but you inherit the persistence semantics wholesale — which is exactly what changed in this release.

Consistent layout wrapper. Put the component in a single layout partial (e.g. resources/views/layouts/partials/nav-tabs.blade.php) rather than repeating it per page. Given this release makes tab memory site-wide, a shared wrapper makes the resulting behaviour predictable instead of accidentally per-page.

Testing. Write one feature test that hits two different pages and asserts the remembered tab resolves as expected. That single test is the cheapest guard against exactly the kind of regression fixed in 0.1.6.1, and against it flipping back in a later release.

Inertia/Livewire projects. If your tab state lives in a client store, mirror the package's storage key so both agree — otherwise you get a flash of the wrong tab on first paint. Resolve state once, at layout level.

Gotchas and Tips

v0.1.6.1 is a behaviour change, not just a bug fix. Previously the remembered tab was scoped to a specific page; now it is remembered for the whole site. If you have multiple independent tab strips (e.g. Settings and Billing both using the component with a profile tab), selecting one may now pre-select the other. Audit every place the component is used after upgrading, and namespace your tab keys per strip if the package exposes a key/group option. If it doesn't, that's your main extension point — wrap the component and pass distinct keys yourself.

Existing user sessions carry over. Users who already have a stored value will land on a remembered tab site-wide immediately after deploy. Expect a small wave of "why does it open on the wrong tab" reports; it isn't a regression, it's the intended new behaviour. Worth a line in your release notes.

Clearing state while debugging. Persistence is likely session- or storage-backed. When you can't explain the active tab, clear the session (php artisan session:clear / a fresh browser profile) before assuming a code bug. Confirm which backend is in use by inspecting the config rather than guessing.

Asset publishing. Front-end changes in a patch release may not appear without re-running vendor:publish --force (or your asset build). If the fix seems absent, check public/vendor/... timestamps first.

Versioning expectations. At 0.1.x, patch numbers are being used for user-visible behaviour changes. Read every changelog entry, keep a composer.lock committed, and avoid ^0.1 if you have multiple tab strips relying on the old scoping.

Extension points to check before forking. Config options for storage driver/key, a key/group discriminator per tab set, and any events or hooks around tab activation. If the config exposes only a boolean "remember tabs" flag, the practical workaround is to wrap the component and pass explicit keys per context.