Download the PHP package tahsin000/snag without Composer

Snag

Let users point at what's broken.

A portable feedback widget for Laravel Blade applications. Install it, add one line to your layout, and every page gets a slim tab on the edge of the screen. People drag a box around the part that is wrong, describe it, and the report lands in your own database - with the page context and that cropped region attached.

No screen-sharing permission. No build step. No frontend framework.

That is the entire integration.

Features

• Edge tab plus side panel - a slim vertical tab flush against the viewport edge, and a full-height drawer that opens on the same edge. It owns one edge only, so it never lands on top of a chat bubble parked in the corner.
• Point at the problem - an optional crop tool lets the user drag a box around the broken part of the page. The region is attached to the report. No screen-sharing permission is ever requested.
• No build step - plain HTML, CSS and vanilla JavaScript. No Vue, React, Inertia, Livewire, Alpine, Tailwind, Bootstrap, jQuery, Node, npm or Vite. The crop tool's only dependency, html2canvas (MIT), ships inside the package and is fetched lazily the first time someone uses it - never on a normal page load.
• Portable by design - the package never references your User, Participant or Customer model. Identity comes through an ActorResolver you control.
• Configurable feedback types - stored as a VARCHAR, so adding a category needs no migration.
• Safe page context - URL, title, route name, user agent and viewport, collected from a strict allowlist.
• Optional image attachments - stored through Laravel's filesystem under generated paths.
• FeedbackSubmitted event - wire up Slack, email, GitHub or Jira in your application, not in the package.
• Rate limited and CSRF protected out of the box.
• Publishable config, migration and views.
• Works with JavaScript disabled - the form degrades to a normal POST.
• Accessible - semantic controls, focus trap, Escape to close, labelled fields, visible focus states.

Requirements

Installing Snag never forces you to upgrade Laravel, PHP or any other dependency. The package depends only on the individual illuminate/* components it actually uses, pins no Symfony version of its own, and requires no frontend toolchain.

Installation

The service provider is registered automatically through Laravel package discovery.

Publish and run the migration:

Optionally publish the configuration:

Add the widget to your main Blade layout, once:

Every page using that layout now has the widget. That's it.

Configuration

The package works with its defaults; publishing the config is only needed to change them.

Configuration is cached and serialized by config:cache, so this file must contain only scalars, arrays and class-strings - never closures. Re-run php artisan route:cache after changing route.prefix or route.middleware.

The crop tool

Browsers cannot take a true pixel screenshot from JavaScript. The only native route is getDisplayMedia(), which raises the browser's own "share your screen" prompt - a permission most people decline, for a task as small as reporting a typo.

So this package does not use it. Instead the crop tool renders the page's own DOM into a canvas with html2canvas, entirely in the browser:

1. The user opens the panel and presses Select an area of the page.
2. The panel steps aside and the page dims.
3. They drag a box around the part that is wrong. Escape cancels.
4. That region - and only that region - is rendered, attached, and previewed in the panel.
5. They describe the problem and submit.

Nothing leaves the browser until the form is submitted, and the whole step is optional: the manual upload field is always there, and skipping the capture says nothing and shows nothing.

What it can and cannot draw. html2canvas re-renders the DOM; it does not photograph the screen. It handles text, layout, backgrounds, borders and same-origin images well. It cannot see inside cross-origin <iframe>s, and cross-origin images need Access-Control-Allow-Origin to appear. The widget itself is excluded from every capture.

Serving the library. By default it is served from GET {prefix}/html2canvas.js, cached for a year and fetched only when someone first uses the tool. Nothing needs publishing. To serve it yourself instead:

then point the config at it:

Set 'screenshot' => false to remove the tool, its markup and its route usage entirely.

Environment variables

Authentication

Guest feedback

Works out of the box. With the default middleware anyone who can see the page can submit feedback, and the actor columns are left null.

Authenticated feedback

Nothing to configure - if $request->user() returns something, the default resolver records its class, identifier, name and email when those exist.

Authenticated only

Add auth to the endpoint middleware:

The package core never requires authentication.

Custom Actor Resolver

The package deliberately knows nothing about your identity model. To capture your own shape, implement the contract:

Point the config at it:

ActorData::$metadata is stored under metadata.actor in the feedback row.

Actor details are a snapshot taken at submission time, not a foreign key. The package never creates a relationship to your users table, so feedback survives user deletion and the package stays installable in any application.

Attachments

Users may attach one image. Files are validated server side against allowed_mimes and max_size_kb, then stored under a generated path - the uploaded filename never influences where the file lands.

Disable them entirely:

Automatic screenshot capture is deliberately not included: it requires a JavaScript dependency and browser-specific handling. It is reserved for a future optional provider.

Events

Every stored submission dispatches FeedbackSubmitted:

Register it as you normally would (auto-discovery, or in your EventServiceProvider).

Integrations live in your application - the package ships none, so it stays dependency free.

Swapping persistence

FeedbackRepository is a contract. Bind your own implementation to store feedback somewhere else - a remote API, another connection, a queue:

The submission action, validation and widget are unaffected.

Customizing views

Publish them:

The views land in resources/views/vendor/snag/:

Re-theming without publishing

Every colour, radius, spacing and font value is a CSS custom property scoped to .snag-root. Override them from your own stylesheet - no publishing required:

All package styles are namespaced with snag-, use no bare element selectors, and are wrapped in @once so including the widget more than once on a page still emits one stylesheet.

Disabling the package

The widget renders an empty string and the endpoint answers 404 - a disabled package does not advertise its endpoint.

Removing the package

Then remove @include('snag::widget') from your layout. Optionally delete the published config, the published views, the feedback table and any stored attachments. Nothing else in your application is touched.

Testing

The suite runs against a real Laravel application through Orchestra Testbench, with an in-memory SQLite database.

To run a single older lane locally, pin its Testbench and PHPUnit — Testbench selects the Laravel branch, because laravel/framework replaces illuminate/*:

Test methods are named test_* and carry #[Test]. The name is what PHPUnit 9 (the Laravel 9 lane) matches on; the attribute is inert there and authoritative from PHPUnit 10 on. Keep both when adding tests, and do not use the /** @test */ annotation — it was removed in PHPUnit 12.

Version compatibility

Compatibility is claimed only for combinations covered by CI. Every lane installs its own dependency set and runs both --prefer-lowest and --prefer-stable: a green Laravel 13 run proves nothing about Laravel 9, so each version is exercised independently.

One codebase covers the whole range. There are no per-version classes; the only version-conditional line in the package is the migration publishing guard described below.

Notes for Laravel 9 and 10

• Publishing the migration. vendor:publish --tag=snag-migrations copies the migration verbatim on Laravel 9 and 10, keeping its 0001_01_01_000000_create_feedback_table.php filename. On Laravel 11+ the framework rewrites the name with a current timestamp. Both migrate correctly — the stub name sorts first and the table has no foreign keys to order against — so this only affects how the published file is named.
• The default rate limiter. The submission route uses throttle:10,1, which needs a working cache store. Laravel 11+ skeletons default to the database cache driver, so a fresh application that has not run its own migrations has no cache table and the endpoint will fail. Run your app's migrations, or point snag.route.middleware at a different limiter.
• Partial config publishing. mergeConfigFrom is a shallow merge on every Laravel version. If you publish config/snag.php and delete nested keys such as widget.*, they are not back-filled from the package defaults. Keep the published file complete.

Security

• CSRF - the form ships a token and the endpoint sits behind the web middleware group.
• Rate limiting - throttle:10,1 by default; configurable.
• Validation - type is checked against the configured allowlist; attachments are checked against a server-side extension allowlist and a size cap. Nothing unvalidated is persisted.
• File uploads - stored through Laravel's filesystem under a UUID path. The client filename is never used.
• Output escaping - all rendered values go through Blade escaping; the package contains no {!! !!}.
• Privacy - page context is an allowlist. The package never stores request payloads, form values, cookies, session contents, CSRF tokens, passwords or the authenticated model.

Found a vulnerability? See SECURITY.md - please do not open a public issue.

Publishing this package

Tag releases with Git; do not add a version key to composer.json.

Then submit the public repository URL at packagist.org and enable the GitHub webhook so new tags sync automatically.

Local development against a real application

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.