Filament Bookmarks Menu Laravel Package

Getting Started

1. Confirm Filament compatibility first. The last tagged release is June 2023 (Filament v2 era, with early v3 support at best). Before installing, run composer require stafe-group-ab/filament-bookmarks-menu in a branch and check what composer show stafe-group-ab/filament-bookmarks-menu resolves against your filament/filament constraint. If it conflicts, that is your answer on whether to proceed.
2. Install and publish.

   composer require stafe-group-ab/filament-bookmarks-menu
   php artisan vendor:publish --tag="filament-bookmarks-menu-config"
   php artisan vendor:publish --tag="filament-bookmarks-menu-migrations"
   php artisan migrate
   

   Publish tags are the usual convention — confirm the exact tag names in the README before assuming.
3. Register the plugin on the panel (v3 style):

   public function panel(Panel $panel): Panel
   {
       return $panel
           // ...
           ->plugin(FilamentBookmarksMenuPlugin::make());
   }
   

   On Filament v2 the registration step differs (service provider / package config entry) — follow the README for your major version.
4. Wire the user side. The package stores per-user bookmarks, so your App\Models\User almost certainly needs the package trait (e.g. HasBookmarks) to expose the relation. Check the migration stub for the foreign key type before migrating.
5. Where to look first: the README's config example (it defines the shape of a global bookmark: label, URL, icon, optional group), then src/*Plugin.php and the migration stub. The package is small — reading it end-to-end takes ten minutes and saves an hour of guessing.
6. First use case: add one global bookmark in config/filament-bookmarks-menu.php pointing at your busiest resource index, load the panel, and confirm it renders. Then click the "bookmark this page" affordance on a record edit page and confirm it persists per user across sessions. That two-step proves both halves of the feature.

Implementation Patterns

• Drive global bookmarks from route names, not literal URLs. Hardcoding /admin/orders breaks the moment you change the panel path, add a domain, or introduce tenancy. Use route('filament.admin.resources.orders.index') or the resource's getUrl() so panel prefixes are resolved at runtime.
• Treat the global list as a "pinned navigation" layer. The highest-value use is surfacing the 3–6 resources each role lives in (support → tickets, finance → invoices) so people stop hunting through a 20-item sidebar. Group them if the config supports groups; otherwise keep the list short enough that grouping doesn't matter.
• Per-user bookmarks are a "recently used" substitute. Because bookmarks are user-created and persistent, they pair well with Filament's global search: users search once, bookmark the record, and the menu becomes their personal shortlist. Consider adding an "add current page" header action on your record pages so capture is one click, not a URL copy-paste.
• Scope by panel deliberately. Register the plugin only on panels whose guard's user model has the trait. In multi-panel apps (admin + customer), a shared bookmarks table means a customer's bookmark can point at an admin URL — scope rows by panel via an added panel_id column, or use separate tables per guard.
• Multi-tenant caveat handled at write time. If your panel is tenant-aware, capture the tenant identifier alongside the URL (in the label or an extra column) so a bookmark created under Tenant A is either hidden or clearly labelled when Tenant B is active.
• Extend the config programmatically when you need dynamic entries. If bookmarks must vary by permission or by tenant, resolve them in a service provider or a small custom class that filters the config array before the menu renders — then authorise each entry (Gate::allows) rather than trusting the config.
• Reuse the model outside the menu. The underlying Bookmark model + user->bookmarks relation is queryable. A dashboard widget ("Your shortcuts") built from the same relation is a few lines and gives the feature a second surface without new storage.
• Dedupe on write. Clicking "bookmark" twice usually produces two identical rows. Wrap creation in firstOrCreate(['user_id' => ..., 'url' => ...]) or add a unique index, and you avoid a menu full of duplicates.

Gotchas and Tips

• Migration is not optional and not auto-run. The most common "it renders nothing / it 500s" report is a missing published migration. Also check the user_id column type against your users table — UUID/ULID primary keys need the stub edited before migrate.
• Filament major-version drift is the real risk. June 2023 predates most of the v3 API stabilisation. Plugin registration signatures, menu registration, and heroicon naming all changed across v2→v3. Pin filament/filament in composer.json, upgrade deliberately, and read the plugin's composer.json constraints rather than the README badge.
• Stored URLs go stale silently. Rename a resource slug or change the panel path and every bookmark 404s with no warning. If the schema only stores a URL string, that is a permanent architectural cost — either accept it (short-lived links, re-add) or fork to store route_name + JSON params and resolve at render time.
• Config caching bites dynamic bookmarks. Anything computed in a service provider or closure won't refresh under php artisan config:cache. Either keep the menu purely config-driven and clear cache on deploy, or compute bookmarks in a Menu/render hook instead of the config file.
• Unknown icons fail quietly. A heroicon that doesn't exist in your Filament version renders as blank space, not an exception — so "the icon is broken" looks like a CSS bug. Verify names against your installed heroicons set.
• Multiple guards need the trait on every user model. The menu renders against the panel guard. If you have User and Admin models, Admin needs the trait too or the menu silently omits the user section.
• Debugging checklist when the menu is absent: (1) plugin registered on the current panel, (2) panel has top navigation or the user menu enabled, (3) config published and not cached from a prior state, (4) migrations run, (5) trait present on the resolved user model.
• Views are overridable. vendor:publish --tag="filament-bookmarks-menu-views" is the cheapest way to change markup, ordering, or add a "manage bookmarks" link without forking PHP.
• Budget for adoption risk. 24 stars and no release in over a year means no security patches and no Filament v4 path. Copy the migration into your app so you own the schema, and if you depend on the feature, plan to vendor the plugin into packages/ (path repository) rather than waiting on upstream. The codebase is small enough that this is a half-day job, not a rewrite.