Laravel Star Log Laravel Package

Getting Started

• composer require caixingyue/laravel-star-log — v2.0.1 is a drop-in patch over 2.0.0, so any pinned ^2.0 constraint picks it up with a plain composer update. No migration, no config republish required.
• Publish the config (php artisan vendor:publish and select the Star Log provider/tag from the package README) and open config/star-log.php first. This single file is where every feature is switched on: HTTP client logging, query logging, connection-failure logging, exception logging, user-agent/device detection, and the per-feature channel/level settings. Nothing is logged until you enable a block and point it at a channel.
• Second place to look: config/logging.php. The package expects a dedicated channel (e.g. star-log) rather than the default stack, so add one early — you want these entries isolated from application logs from day one.
• First use case worth wiring: HTTP client logging on an unreliable third-party API. Enable the HTTP client block, add the package middleware to that client, hit the endpoint once, and confirm you get a paired request/response entry with status, duration, and payload. That single loop validates config, channel, and middleware registration in one shot.
• Version-specific starting point for this release: if you are on Laravel 13 you may now run Guzzle 8 / PSR-7 3.x. If you are on Laravel 12, stay on Guzzle 7 — that combination is the only one covered by the test matrix.

Implementation Patterns

Channel-per-concern, not one giant log. Give each feature its own channel (star-log-http, star-log-query, star-log-exceptions) using the daily driver. Query logs in particular explode in volume; separating them keeps your log shipper's parsing rules sane and lets you set different retention per stream.

HTTP client middleware, per named client. Register the logging middleware on the specific clients you care about rather than globally. Laravel's Http:: facade makes it easy to build a base client in a service provider and attach the middleware there, so every consumer of that client inherits consistent logging without remembering to opt in. Do this for outbound integrations; skip it for internal service calls that would flood the log.

Mask before you log, not after. Configure header and body redaction (Authorization, cookies, API keys, password fields) in the package config. Treat this as mandatory: these logs land on disk and in your aggregator, and HTTP request bodies routinely carry credentials.

Use the connection-failure log as your alerting signal. This is the entry type that survives when a request never got a response at all — DNS failure, timeout, refused connection. Route it to the channel your alerting watches, and keep it enabled in production even if you turn general HTTP logging down. v2.0.1 specifically hardens this path on Guzzle 8 and stops the failure-log middleware callbacks from running at all when both HTTP and connection-failure logging are disabled, so a "logging off" environment is now truly zero-cost.

Never clobber the statistics callback. If you supply your own Guzzle statistics callback for metrics, the package now merges transport statistics into it instead of overwriting it. Keep your callback pure and idempotent — read stats off the transfer, don't mutate shared state — and both your metrics and the package's failure reasons will coexist.

Slow-query thresholding for anything query-related. Set a millisecond threshold comfortably above your p95 and log only beyond it. Full query logging belongs in local/staging; production should be threshold-only plus sampling.

Enrich with request context. Push a request/trace ID, authenticated user ID, and route into the log context so an HTTP-client entry can be correlated with the inbound request that triggered it. Without this, outbound logs are orphans.

Device/user-agent detection is opt-in and dependency-backed. If Mobile Detect is installed, the package can annotate entries with device class. Useful for debugging mobile-specific issues on public endpoints; noise everywhere else — enable it per channel.

Gotchas and Tips

• Guzzle 8 is Laravel 13 only. The test matrix keeps Guzzle 7 on Laravel 12 and 13, and adds Guzzle 8 solely on Laravel 13. If you're on Laravel 12 and try to force guzzlehttp/guzzle:^8.0, do not expect this package to be validated against it. Don't "helpfully" bump it in a Laravel 12 app.
• PSR-7 versions move with Guzzle. Guzzle 8 pairs with guzzlehttp/psr7 3.x, Guzzle 7 with 2.x. A stray direct constraint on guzzlehttp/psr7 in your composer.json is the most likely cause of a resolver conflict after upgrading; check that before filing anything.
• Upgrade order matters on Laravel 13. Bump Laravel, then Guzzle, then this package, then run the suite. composer update --prefer-lowest in CI is worth adding here — the release explicitly covers lowest-supported dependency versions, and that's where PSR-7 signature mismatches surface.
• Desktop detection changed under Mobile Detect 4.8. That version does not expose the newer CloudFront user-agent property, and detection is now guarded for it. If you were previously seeing desktop traffic misclassified (or seeing notices/warnings on that property), re-check your dashboards after upgrading — historical device splits may shift.
• Failure reasons may read differently. Connection-failure logs now derive their reason from transport statistics and follow Guzzle 8's exception hierarchy. If you have regexes or alert rules parsing the failure-reason string, re-validate them against both Guzzle 7 and 8 output before you trust the pager.
• Callbacks are skipped when logging is off. If you hung side effects (metrics increments, audit writes, notifications) inside a failure-log middleware callback and relied on it firing regardless of the logging toggle, that no longer holds. Move side effects out of logging callbacks entirely.
• Silent no-logs checklist, in order: is the feature block enabled in config/star-log.php; is the configured channel present in config/logging.php and writable; is the entry's level at or above the channel's threshold; is the middleware actually attached to the client you're using (named clients don't inherit unless you attach it). Ninety percent of "the package doesn't work" is the fourth item.
• Extension points: the package's middleware and log handlers are the seams to use — wrap or decorate rather than editing vendor code. Custom channel drivers in logging.php let you ship these entries to a different sink (e.g. a separate index) without touching the package config beyond the channel name.
• Patch-level discipline: v2.0.1 changes runtime behaviour in two places (callback skipping, failure-reason derivation) without changing the public API. Pin ^2.0.1 rather than ^2.0.0 so environments that resolved early don't sit on the old callback semantics.