Looking to hire Laravel developers? Try LaraJobs

watchtower-laravel maintained by phattarachai

Description
Laravel client for the Watchtower self-hosted Sentry-compatible exception tracker. Wires up sentry/sentry-laravel and a same-origin browser tunnel that dodges ad blockers.
Author
Phattarachai Chaimongkol
Last update
2026/05/18 18:11 (dev-main)
License
MIT
Links
GitHub - Packagist
Downloads
20
Tags
laravel - sentry - watchtower - error-tracking - observability - exception-tracking

dev-main

Last update
2026/05/18 18:11
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.4.4

Last update
2026/05/18 18:11
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.4.3

Last update
2026/05/18 17:33
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.4.2

Last update
2026/05/18 14:05
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.4.1

Last update
2026/05/18 13:00
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.4.0

Last update
2026/05/18 12:48
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.3.0

Last update
2026/05/18 11:37
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.2.0

Last update
2026/05/18 10:53
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
v0.1.0

Last update
2026/05/17 13:40
License
MIT
Require
  • php ^8.4
  • guzzlehttp/guzzle ^7.0
  • illuminate/console ^12.0 || ^13.0
  • illuminate/contracts ^12.0 || ^13.0
  • illuminate/http ^12.0 || ^13.0
  • illuminate/support ^12.0 || ^13.0
  • sentry/sentry-laravel ^4.0
Comments
comments powered by Disqus

Watchtower Laravel

Laravel client for Watchtower, a self-hosted Sentry-compatible exception tracker. Installs and configures sentry/sentry-laravel, wires Integration::handles($exceptions) into bootstrap/app.php, and exposes a same-origin browser tunnel (/api/watchtower-relay) that proxies envelopes to your Watchtower instance — dodging ad-blockers that strip ?sentry_key= query strings.

Install

composer require phattarachai/watchtower-laravel
php artisan watchtower:install --dsn=http://your-public-key@your-watchtower-host/42

The install command:

  1. Validates and writes WATCHTOWER_DSN and SENTRY_LARAVEL_DSN to .env.
  2. Patches bootstrap/app.php to call Sentry\Laravel\Integration::handles($exceptions) inside withExceptions(...).
  3. Publishes config/watchtower.php.
  4. If vite.config.{js,ts} is present, writes VITE_SENTRY_DSN, VITE_SENTRY_TUNNEL, and VITE_SENTRY_ENVIRONMENT and prints a Vite entry snippet.

Re-running is idempotent. Pass --dry-run to preview changes.

Configuration

Env key Default Purpose
WATCHTOWER_DSN falls back to SENTRY_LARAVEL_DSN Watchtower DSN: http://{key}@{host}/{numeric-project-id}.
WATCHTOWER_RELAY_ENABLED true Register the relay route on boot.
WATCHTOWER_RELAY_PATH /api/watchtower-relay Relay endpoint path (must live under /api/).
WATCHTOWER_RELAY_TIMEOUT 5 Upstream request timeout (seconds).
WATCHTOWER_RELAY_ASYNC false Forward envelopes through a queued job instead of sync.
WATCHTOWER_RELAY_QUEUE (default queue) Queue name when async is enabled.
WATCHTOWER_VERIFY_SSL true Verify upstream TLS certificate.
WATCHTOWER_CONNECT_TIMEOUT 3 Guzzle connect timeout (seconds).

Browser side

The browser SDK posts envelopes to your own app at /api/watchtower-relay. The relay parses your configured DSN, forwards the request body verbatim to {scheme}://{host_with_port}/api/watchtower-relay on the Watchtower instance, and passes back the upstream status and rate-limit headers.

import * as Sentry from '@sentry/browser';

Sentry.init({
    dsn: import.meta.env.VITE_SENTRY_DSN,
    tunnel: import.meta.env.VITE_SENTRY_TUNNEL,
    environment: import.meta.env.VITE_SENTRY_ENVIRONMENT,
});

Because the request hits your own origin under /api/, ad-blockers don't recognize it as Sentry traffic.

Async forwarding

Set WATCHTOWER_RELAY_ASYNC=true to dispatch each forward through a ForwardEnvelope job. The relay returns 202 {"queued": true} immediately and the worker performs the upstream POST. Failures are logged but not retried beyond Guzzle's default behavior — the Sentry SDK retransmits anyway.

Verify

php artisan watchtower:test

Prints the resolved config, runs sentry:test, and POSTs a synthetic envelope through the relay path.

Troubleshooting

See the upstream Watchtower skill: https://watchtower.phattarachai.app/skill/watchtower-error-tracking.

License

MIT.