Column Toggler Laravel Package

Getting Started

• Confirm the target is Nova, not Filament. The package’s public description incorrectly calls it a Filament package; the repo, changelog, and integration surface are Laravel Nova. Do not install it expecting Filament table support.
• Lock the Nova-version line before installing. v0.3.0 adds Nova 5 support. If you are still on Nova 4, pin the v0.2.x line. Check the package composer.json yourself rather than trusting marketplace metadata.
• Install with an explicit constraint, not a floating *:

composer require dcasia/column-toggler:^0.3.0
# Nova 4:
# composer require dcasia/column-toggler:^0.2.0

• Register the tool globally in app/Providers/NovaServiceProvider.php:

use DigitalCreative\ColumnToggler\ColumnToggler;

public function tools()
{
    return [
        new ColumnToggler(),
    ];
}

• Publish config/assets only if the README instructs it. Typical Nova tool packages expose a service provider publish command; run that, then php artisan nova:publish if Nova’s asset pipeline requires it. Keep the published config in version control if you customize labels/icons/defaults.
• First use case: pick a high-traffic, wide index resource — Orders, Users, Audit Logs — with 8+ columns. Load the index, locate the column toggle control in the Nova header, hide a few columns, refresh, and confirm the preference persists. If the control does not appear, check tool registration, Nova version constraints, published assets, and browser console errors before changing code.
• Where to look first: NovaServiceProvider::tools(), the package composer.json for Nova constraints, config/column-toggler.php if published, browser devtools localStorage, and the Nova index header DOM.

Implementation Patterns

• Default to global enablement for internal admin users. Register the tool once and let operators tailor dense index tables themselves. This is the package’s sweet spot: low-effort, internal-only, reversible.
• Limit exposure by user or environment by conditionally registering the tool:

public function tools()
{
    $tools = [];

    if (request()->user()?->isAdmin()) {
        $tools[] = new ColumnToggler();
    }

    return $tools;
}

If the tool exposes canSee(), use that instead of branching in tools().

• Use it for cosmetic column visibility, not authorization. Hiding a column does not remove data from the query or API response. For real access control, use Nova field canSee() / hideFromIndex() and policy checks.
• Combine with Nova filters, sorting, and pagination deliberately. Test toggling after applying filters and paging. The common failure is not data loss but a control that disappears or stops responding when custom index components or header-injecting tools are present.
• Validate alongside custom index components. The toggler renders into the standard Nova header slot. Custom index headers, custom tools, or other header-injecting packages are the known collision point. Test in staging on representative resources.
• Use Nova fields for role-level defaults; use this package for user-level overrides. If finance should default to different columns than support, set that in the resource via hideFromIndex() or canSee() per role. Do not stretch this package into per-role default column sets — it persists in browser localStorage, not server-side.
• When adding a new column, test how the toggler treats it. Existing users’ stored preferences may or may not include the new column depending on how the package keys preferences. Document whether new columns default visible or hidden, and verify after resource changes.
• Keep failure degraded. If the package breaks after a Nova upgrade, operators should fall back to the full column set. That is acceptable for internal admin tooling; do not put this package in customer-facing workflows.
• Pin and review on Nova upgrades. Add this package to the Nova-upgrade checklist. On each Nova major release, verify the toggle renders, assets compile, and preferences still load. The 0.x semver line means a minor bump can carry compatibility breaks.
• Day-to-day debugging workflow: reproduce in staging, check browser console for JS errors, inspect localStorage keys for the resource, confirm the column name has not changed, then verify tool registration and package/Nova version alignment.

Gotchas and Tips

• Filament mismatch: the package description says Filament; the code is Nova. Treat the repo and changelog as source of truth.
• Nova 4 vs Nova 5 split: v0.3.0 is the Nova 5 compatibility release. Nova 4 environments should pin v0.2.x. Mixing lines is the highest-probability failure — catch it with explicit constraints and a staging check.
• 0.x semver risk: pin the version. A minor release can carry a breaking change. Prefer ^0.3.0 with deliberate review, or an exact pin if you want maximum stability.
• localStorage is not server-side persistence: preferences are per browser and per resource. They do not follow users across devices, incognito sessions, or cleared site data. Tell users this up front to avoid a follow-on “my columns reset” request cycle.
• Column renames can orphan preferences: if a column name changes, stored visibility may not map cleanly. Verify after resource refactors. Provide a documented reset path: clear site data or use a private window.
• Not access control: hiding a column is cosmetic. Sensitive data still loads. Use Nova authorization, policies, and field-level visibility for compliance.
• Custom header collisions: if the toggle button does not render, check whether another tool or custom index component occupies the header slot. Validate alongside any existing index customization before rollout.
• Asset pipeline failures: missing published assets, stale Nova assets, or compiled JS errors can make the control disappear. Check browser console 404s, run the package publish command, and clear Nova caches.
• Single-maintainer dependency: no vendor SLA, no stated automated test coverage against Nova 5, and a bursty release cadence. Keep a named internal owner and an exit plan. An in-house toggle is small enough that build-vs-buy should be a deliberate call.
• Scope boundary: this is not saved views, per-role default column sets, export, shared filter presets, or server-side preference persistence. Those are a materially larger product problem; do not promise them from this package.