Log Envelope Laravel Package

Getting Started

1. Install the package:

   composer require yaro/log-envelope
   

2. Register the service provider. On Laravel 5.5+ auto-discovery may handle it; otherwise add it to config/app.php:

   Yaro\LogEnvelope\LogEnvelopeServiceProvider::class,
   

3. Publish the package config:

   php artisan vendor:publish --provider="Yaro\LogEnvelope\LogEnvelopeServiceProvider"
   

4. Inspect config/log-envelope.php and set the recipient, sender, subject, enabled flag, and minimum log level. Prefer environment variables so each environment can differ:

   LOG_ENVELOPE_ENABLED=true
   [email protected]
   [email protected]
   

5. First use case: trigger an error and confirm delivery:

   Log::error('LogEnvelope smoke test', ['route' => request()->path()]);
   

   In local development, set MAIL_MAILER=log and inspect storage/logs/laravel.log rather than sending real mail.

Where to look first:

• The README for the exact config key names and supported Laravel versions.
• config/log-envelope.php after publishing.
• The package service provider, to see how it hooks into Laravel logging.
• The handler/listener class, to understand what context and stack trace are included in the email.

Implementation Patterns

Production-only alerting. Enable the package only where you want email alerts, typically production or staging:

// config/log-envelope.php
'enabled' => env('LOG_ENVELOPE_ENABLED', app()->environment('production')),

Keep it disabled in local and testing to avoid noise and accidental mail.

Drive it through Laravel's exception reporting. The clean path is to let uncaught exceptions flow through App\Exceptions\Handler::report(), which logs them. If you override report(), call parent::report($exception) so the package still sees the error:

public function report(Throwable $exception)
{
    parent::report($exception);
}

Use explicit error logs for non-exception failures. Background jobs, failed API calls, and validation of external services may not throw. Log them at error or above:

Log::error('Payment gateway rejected charge', [
    'order_id' => $order->id,
    'gateway' => 'stripe',
    'response' => $response->json(),
]);

Enrich context with request metadata. Add a middleware or exception-handler hook that includes URL, user ID, tenant ID, and request ID. This makes the email actionable without opening the server:

Log::error($message, [
    'url' => request()->fullUrl(),
    'user_id' => optional(auth()->user())->id,
    'request_id' => request()->header('X-Request-Id'),
]);

Throttle and deduplicate. Error storms can send hundreds of emails. Wrap notifications with a cache lock or rate limiter, or configure a higher threshold and rely on a separate monitoring system for volume:

if (Cache::add('log-envelope:'.$fingerprint, true, now()->addMinutes(5))) {
    Log::error($message, $context);
}

Choose the right mail transport. For low-volume alerting, SMTP is fine. For anything that may burst, use a queued transport or a transactional email provider. If the package sends synchronously, an SMTP timeout can slow down the failing request.

Test with the log mailer, not a real inbox. Set MAIL_MAILER=log locally and trigger errors. In automated tests, assert against the log output or bind a fake mailer if the package uses Laravel's Mail facade. Verify the exact behavior rather than assuming Mail::fake() intercepts it.

Keep it as a lightweight fallback. LogEnvelope is useful for small teams and low-traffic apps. For serious production monitoring, pair it with Sentry, Flare, Bugsnag, or Laravel Telescope/Horizon alerting, and avoid duplicate alert paths.

Customize the notification where supported. If the package publishes views or exposes a handler class, override the subject and template to include environment, release version, and a link to your logs. Keep stack traces but redact secrets.

Gotchas and Tips

• Laravel version compatibility is the biggest risk. This package targets Laravel 5 and its logging internals. Laravel 6+ changed the logging stack significantly, and Log::listen-style hooks may no longer fire. Test on your exact Laravel version before depending on it; be prepared to fork the package and adapt the handler to a Monolog processor or custom log channel.
• Monolog API changes can break the package. Laravel 5 used Monolog 1; newer Laravel versions use Monolog 2/3. If the package constructs handlers or records directly, it may fatal on newer versions.
• Mail failures can mask the original error. If the mail transport throws during error handling, you can lose the original exception or create confusing secondary failures. Wrap sending in try/catch and log mail failures separately.
• Synchronous SMTP blocks the request. An error response can hang while connecting to SMTP. Use a fast local relay, a queued mailer, or a transport with a short timeout.
• Avoid recursive alerting. If the mailer or the package's own logging fails and logs an error, you can trigger another email. Disable the package's listener while sending, or ensure mail errors are logged at a level the package ignores.
• Redact sensitive data. Exception traces, request bodies, and context arrays can contain passwords, tokens, and personal data. Configure $dontReport in your exception handler and scrub context before logging.
• Run php artisan config:clear after changing environment variables. Cached config can make it look like the package is ignoring your recipient or enabled flag.
• Check the log level threshold. If the package only listens to error and above, warning or notice entries will not send mail. Confirm whether emergency, alert, and critical are included.
• Recipient and sender formatting matter. A from address on a domain without SPF/DKIM can land in spam. Use a verified sender and test deliverability.
• Duplicate notifications are common. Laravel's exception handler, your own Log::error calls, and the package can all fire for the same event. Pick one reporting path per failure type.
• Do not rely on it for audit trails. Email is lossy and not queryable. Persist errors in a database or external service if you need history.
• The package is small and lightly maintained. With few stars and a 2023 release, expect to read the source. Treat the service provider and handler as the extension points: subclass or rebind them if you need custom formatting, throttling, or transport behavior.