Statamic Cp Bar Laravel Package

Getting Started

• Install the addon with composer require 4rn0/statamic-cp-bar. Statamic addons are auto-discovered, so no manual provider registration is normally needed.
• Publish and review the config before touching anything else:

  php artisan vendor:publish --tag=cp-bar-config
  

  Look first at config/cp-bar.php — this is where enablement, environment gating and the bar's link set will live.
• First use case: log in to the Statamic CP as an admin, then browse the front-end of the site. The bar renders for authenticated control-panel users and gives one-click routes back into the CP and (where applicable) into the entry currently being viewed — the fastest day-to-day win is jumping from a rendered URL straight to its editable source instead of hunting through the collection tree.
• If the bar doesn't appear on first install, check in this order: the user is logged into the CP, the current environment is enabled in config, and the layout actually includes the addon's render tag/partial (see below).

Implementation Patterns

Layout injection vs. explicit tag. Depending on how the addon ships, the bar is either injected automatically into responses or rendered via a tag in your layout:

{{ if logged_in }}
    {{ cp_bar }}
{{ /if }}

@include('cp-bar::bar')

Prefer the explicit tag in Blade/Antlers layouts for multi-layout sites — automatic injection can behave inconsistently with Livewire, Inertia, or custom response handling.

Environment gating. Default the bar on for local and staging, and decide deliberately for production. For production, gate it behind role rather than disabling it entirely — editors benefit most from it, but you probably don't want it visible to every logged-in member. Combine config gating with a role/permission check:

// config/cp-bar.php
'enabled' => env('CP_BAR_ENABLED', true),
'allowed_roles' => ['super', 'editor'],

Editor workflow pattern. Point the "edit" action at the entry being rendered so the round-trip is content-driven rather than navigation-driven. If the addon exposes the current entry context, use it to build the CP deep link; if not, resolve it yourself in a view composer and pass it into the bar's link set. This is the single highest-value integration for a content team.

Multi-site setups. Where the bar builds a CP URL, confirm it carries the correct site handle — otherwise editors on a secondary site get bounced to the default site's edit screen and can silently edit the wrong localized entry. Test with at least two sites before rolling out.

Custom links. If the package supports registering items, treat the bar as an extensible menu rather than a fixed toolbar — add links to your own CP navigation (e.g. a custom dashboard, a cache-clear screen, a search index). Keep custom items in a service provider so they're reviewable, versioned and not buried in config.

Version note (v1.1.0). This is a minor release with no documented breaking changes. Nothing in your integration should require rework; do a standard composer update and re-check the bar renders on a representative front-end page (entry, taxonomy term, and a non-content route such as the homepage) since that's where contextual link logic is most likely to have been touched.

Gotchas and Tips

• Full-page caching is the classic failure mode. If you cache rendered HTML (Statamic static caching, response caching, CDN), the bar — or its absence — will be baked into the cached copy. Exclude authenticated requests from the cache, or inject the bar via a middleware/response hook that runs after cache retrieval. Never let a cached page ship the bar to an anonymous visitor.
• Don't leak the bar to non-CP users. Users who are logged in via a front-end auth guard but have no CP access should not see it. Check the control-panel authorisation, not merely logged_in.
• CSP and inline assets. A floating bar usually brings inline styles and/or a small JS bundle. Strict Content-Security-Policy headers will silently kill its interaction. Add the necessary style-src/script-src allowances (or a nonce) and test in the browser console, not just by eyeballing the page.
• Asset pipeline conflicts. If the addon publishes CSS/JS into the public directory, make sure it's excluded from your build/deploy artefacts, and that it isn't being purged when you run production builds. A bar that renders unstyled is usually a missing published asset, not a broken package.
• Z-index and layout collisions. Fixed-position toolbars fight with sticky headers, cookie banners and Livewire/Alpine overlays. If the bar is invisible, check stacking context before assuming it isn't rendering.
• Debugging checklist when the bar is missing: (1) config published and enabled true for the env, (2) cache cleared — php artisan config:clear && php artisan view:clear, (3) layout actually contains the tag, (4) user passes the role gate, (5) response isn't served from cache.
• Upgrade safety for a 1.x addon. Pin to ^1.1 rather than *, commit the lockfile, and skim the diff between tagged versions before deploying — the release notes here only link the compare view, so the actual change surface is in the commits. For an admin-facing addon the blast radius is small, but it renders on every page, so a regression is visible site-wide.
• Extension points worth favouring. Published views and a config-driven link list are the stable extension points; subclassing internal classes or patching vendor files will break on the next minor. If you need behaviour the config doesn't expose, wrap the tag in your own partial and control it there.