Hookshelper Laravel Package

Technical Evaluation

Architecture fit

• This is a developer-experience utility, not a product dependency. It registers a Filament panel plugin that injects a toggle button into a render hook and, when clicked, reveals every render hook available on the current page. It touches no models, routes, middleware, or persistence.
• Fit is narrow and clean: it consumes Filament's public plugin contract (->plugins([HooksHelperPlugin::make()])) and its render-hook system. No core patching, no service overrides, no database footprint.
• Value is concentrated in the UI composition/debugging loop — answering "which hook do I extend, and is it actually firing on this page?" That is a real recurring cost on any team building Filament panels, and it is currently answered by reading Filament docs and guessing.
• It is only meaningful on Filament panels. Zero applicability to vanilla Laravel, Inertia, or non-Filament admin surfaces. Treat it as scope-limited tooling, not platform infrastructure.

Integration feasibility

• Effectively a one-hour change: composer require, one line in the Panel provider, optional config publish. No migration, no schema, no data backfill, no coordinated release.
• Config surface is small and legible: render_hook (anchor placement, defaults to global-search.before with the panels:: prefix auto-applied), icon, tiny_toggle. Views and translations are publishable but optional.
• Onboarding cost is near zero for anyone who has registered a Filament plugin before. The only conceptual prerequisite is understanding what a render hook is.

Technical risk

• Dev-only by intent, production-risky by accident. The package has no built-in environment guard. If registered unconditionally in a panel provider, the toggle button ships to production and exposes internal hook names to anyone who can reach the panel header. This is the single most important risk and it is entirely within our control.
• Silent failure on anchor drift. Placement is bound to a named hook. If the panel disables global search, or Filament renames/moves that hook in a future major, the button disappears without an error. Symptom is "the tool stopped existing," which teams discover weeks later.
• Filament major-version coupling. Changelog traces v3 → v4 → v5 support as discrete releases. Each Filament major is a potential break requiring an upstream release we do not control.
• Publishing drift. Publishing views or translations copies upstream files into our repo; subsequent package upgrades will not update them. Recommend publishing config only.
• Bus factor and validation. Single maintainer, one credited contributor, 27 stars, 0 dependents, and version labels that are internally inconsistent (a 1.0.0 "initial release" alongside 0.1.0, plus future-dated release metadata). Nothing here is alarming for a dev utility, but it does mean we should not treat version numbers as a maturity signal and should expect no SLA.
• License is MIT — no legal friction, fork-friendly if needed.

Key questions

1. Which Filament major(s) are our panels on today, and is there a v6 upgrade on the roadmap that would strand this?
2. How do we enforce dev-only — ->local()/app()->isLocal() conditional, or require-dev? (Recommend both.)
3. Which panels actually use global-search.before as a live anchor? Each panel may need a different render_hook.
4. Who owns the decision to remove this if it goes stale, and what triggers it?
5. What is our acceptance signal — is it "time to locate a hook for a new component" or onboarding time for a Filament newcomer?
6. Is the toggle acceptable if a non-developer (designer, QA) has panel access in staging? Hook names are internal detail.

Integration Approach

Stack fit

• Required: Laravel + Filament (v4 or v5 per changelog; confirm against composer.lock rather than the README). No additional runtime libraries.
• Compatible with Filament's default Blade/Tailwind/Alpine surface — the toggle sits in the topbar and inherits panel styling.
• Fits our existing dev-tooling pattern (debug bars, Telescope, Ignition): additive, per-environment, disposable.

Migration path

1. Verify the Filament major in each target panel and confirm a tagged release supports it.
2. Install as a dev dependency: composer require --dev agencetwogether/hookshelper, pinned to an exact version to make upgrades deliberate.
3. Publish config only: php artisan vendor:publish --tag="hookshelper-config". Skip views and translations — they create upgrade drift for no benefit.
4. Register conditionally in each Panel provider, gated on local/staging. Never unconditional.
5. Tune placement per panel: set render_hook to an anchor that exists in that panel, and tiny_toggle => true if the topbar is crowded.
6. Document removal in the panel README: delete the plugin line, composer remove --dev agencetwogether/hookshelper, delete the config. Two minutes.

Compatibility

• Anchor on a Filament major and re-verify at each Filament upgrade as a standing checklist item, alongside the usual upgrade test pass.
• Expect zero conflicts with other plugins; the button occupies one render-hook slot in the topbar. Visual collision with other topbar injections is the only realistic friction — test on the busiest panel first.

Sequencing

1. Week 1 — Spike (1 dev, ~2 hours). Install on one non-critical staging panel. Measure time-to-hook-identification against the current docs-reading baseline on two or three real tasks.
2. Week 2 — Gate and standardize. Add the environment guard, pin the version, write the two-line removal note into the panel README.
3. Week 3 — Roll out to remaining dev panels, one at a time, verifying the anchor hook per panel.
4. Later — Review at next Filament upgrade. Keep or drop based on whether it was actually used; a tool nobody opened in a quarter should be removed, not maintained.

Operational Impact

Maintenance

• Genuinely low: no migrations, no scheduled work, no data. The real maintenance load is version-tracking against Filament majors — a checklist item at upgrade time, not ongoing work.
• Budget roughly one to two hours per Filament major upgrade to verify a compatible release exists and the anchor hook still resolves. If upstream lags, the fallback is trivial (see Support).
• Published config is the only artifact we own. Keep it minimal so upgrades stay clean.

Support

• Upstream is a single maintainer with a small audience and no support commitment. We should treat it as community-supported, best-effort, and set that expectation before adoption.
• Contingency is cheap and should be pre-agreed: the code path we depend on is a Blade partial plus an Alpine toggle. If upstream goes stale, a fork is a few hours of work, and outright removal costs nothing except the loss of the convenience. This is exactly the risk profile where "buy" (adopt) is correct — the downside is bounded at near zero.
• No security exposure beyond internal hook-name disclosure, which is gated by dev-only registration.

Scaling

• No scaling concern in the intended mode: the button is one render-hook slot in the panel topbar, and clicking it is a client-side reveal.
• If registered unconditionally across many panels, every authenticated page render in production carries an extra partial and toggle component, and the panel topbar becomes a place users can enumerate hook names. That is the failure mode to design out, not a load issue.
• Scales horizontally with the panels it is installed in, one install per panel provider — no central configuration to drift.

Failure modes

Ramp-up

• For a Filament-fluent developer: minutes. Install, one line, done.
• For a developer new to Filament hooks: this is arguably the highest-value part of the adoption — it shortens the conceptual ramp on Filament's hook model by making the abstraction visible on a live page instead of in docs. Worth pairing with onboarding material.
• For non-developers (designers, QA): no ramp-up needed, but be explicit that the toggle is a read/debug affordance, not a layout editor — it does not change configuration, persist anything, or ship to users.
• Leadership-facing framing should stay modest: a low-cost, low-risk, easily-reversible developer convenience that reduces time-to-hook-identification and shortens Filament onboarding. Do not position it as an architecture or performance lever.