Statamic Feedback Laravel Package

Getting Started

This is a Statamic addon (Control Panel + Antlers), so treat installation as a Statamic workflow rather than a pure Laravel package: composer require the package, then confirm the service provider is auto-discovered and the addon appears under Tools → Addons in the CP. Publish the config (php artisan vendor:publish --tag=...) before touching anything else — widget position, screenshot/pin toggles, listing column, and the YAML storage path all live there and are the fastest way to understand the surface area.

Where to look first, in order:

1. Config file — it's the map of every feature flag in the release notes.
2. Permissions (CP → Users → Roles) — four granular permissions ship: view, create, delete own, manage all. Set these before inviting testers, otherwise everyone is effectively an admin over feedback.
3. The Antlers tag — the single-tag frontend integration is the whole frontend story.
4. Storage path — point it at a persistent, backed-up location and confirm a test submission writes a YAML file.

First use case: add the tag to your base layout, open a page, pin a comment to a nav element, @mention a teammate, and verify (a) the YAML file appeared, (b) the entry's feedback count column incremented, (c) the unread badge and toast fired for the mentioned user. That single loop exercises storage, entry linking, notifications, and permissions at once.

Implementation Patterns

Environment-gated frontend widget. Don't ship the tag unconditionally. Wrap it so it only renders for authenticated CP users or in staging:

{{ if environment == 'staging' || logged_in }}
    {{ feedback_widget }}
{{ /if }}

Given the widget allows public comments and mentions, this is the difference between a review tool and an open guestbook on a marketing site.

Stable pin targets. Pins resolve via CSS selectors, so selector stability is an architectural concern, not a detail. Adopt a convention — data-feedback="hero-cta" on any element reviewers are likely to annotate — rather than pinning to utility classes or nth-child paths that Tailwind/Vue re-renders will silently break. Add it to your component/partial checklist the same way you'd add a test id.

Config-per-context. The config is global, but you often want different behaviour per site or per section: full pins + screenshots on staging, mentions-only in the CP. Publish the config and use env vars for the storage path and toggles so staging and production don't diverge in code.

Entry linking as the workflow backbone. The feedback count column in collection listings plus origin-entry linking is what turns this from a comment box into a review queue: editors sort by feedback count, open the entry, resolve items, move on. Lean on the tabbed views (Unread / Mentions / Mine / Resolved) as the triage loop and treat "Resolved" as your done state — teach the team to resolve rather than delete, so history survives.

Multi-site. Feedback is shared via origin entry IDs, so a remark left on the EN entry surfaces against the localised version. That's usually what you want, but be deliberate: reviewers may not realise their note appears on other sites, and entries without a localised counterpart produce links that go nowhere useful.

Notifications. Mentions and toasts route through Statamic's preferences system, which means per-user opt-out is already handled — don't build your own mailer. If a mention produces no toast, check the user's preferences before debugging your code.

Deployment/CI. Flat-file YAML means no migrations. Decide explicitly whether the storage directory is committed (review history in git, reviewable diffs) or ignored + backed up (cleaner history). Either way it must survive deploys.

Gotchas and Tips

• Flat-file storage and ephemeral filesystems are the big one. On Forge Vapor, containerised deploys, or any setup with an ephemeral/read-only filesystem, feedback written to a path outside a persistent volume or shared disk disappears on the next release. Verify persistence with a redeploy before the team invests a week of review comments. Concurrent writes have no transactional guarantees — fine at team scale, worth knowing if you expect dozens of simultaneous annotators.
• Screenshot capture needs a secure context and user consent. The browser screen-capture API requires HTTPS (localhost excepted), prompts the user for permission, and can't capture cross-origin iframes or some embedded content. Expect "screenshots are blank" reports to be environmental, not bugs. Gate it off entirely on low-trust pages.
• Static/full-page caching. If you cache rendered pages, the widget markup — and its config-derived position/toggles — can be baked in and served stale after a config change. Clear caches after publishing config and test the widget on a cached page specifically.
• Config caching. Statamic addon config is read through Laravel's config repository; run php artisan config:clear locally and remember config:cache in production will freeze your env-driven toggles until the next cache rebuild.
• Selectors fail silently. A broken pin doesn't error — the annotation just floats to the page top or orphans. When someone reports a misplaced comment, check the selector against the live DOM first; hashed class names and conditional rendering are the usual culprits, and data-* attributes are the fix.
• Permissions vs. the count column. The injected feedback count column can surface activity to users who lack the "view" permission. If feedback volume is sensitive, verify what a low-privilege role actually sees in listings.
• Multi-site orphans. Origin-entry linking assumes the entry exists elsewhere. Deleting or unpublishing an entry leaves feedback pointing at nothing — audit and clean up periodically, or you'll accumulate dead links in the Resolved tab.
• Translations. 29 locales ship in, but overrides need publishing; if you reword UI strings, publish the lang files rather than editing vendor paths, or the next composer update eats your changes.
• Dark mode and z-index. The widget sits above your app's stacking context. If you have sticky headers, modals, or toasts of your own, check for overlap early — restyling a floating widget after launch is more disruptive than choosing its position up front.
• Extension points and version pinning. At v1.0.0 the YAML schema is effectively a public contract with no migration tooling yet. Pin the version in composer.json, and treat any future release notes mentioning storage or schema changes as requiring a read-and-back-up step before upgrading.