onlime / laravel-http-client-global-logger
A global logger for the Laravel HTTP Client
Package info
github.com/onlime/laravel-http-client-global-logger
pkg:composer/onlime/laravel-http-client-global-logger
Requires
- php: ^8.3
- illuminate/http: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- monolog/monolog: ^3.9
Requires (Dev)
- larastan/larastan: ^3.15
- laravel/framework: ^12.0 || ^13.0
- laravel/pint: ^1.32
- orchestra/testbench: ^10.0 || ^11.0
- pestphp/pest: ^4.7 || ^5.3
- saloonphp/laravel-plugin: ^4.3 || ^5.0
- spatie/invade: ^2.2
Suggests
- saloonphp/laravel-plugin: Enable logging of Saloon HTTP client events
Provides
None
Conflicts
None
Replaces
None
README
A super simple global logger for the Laravel HTTP Client.
Requirements
- PHP 8.3+ (tested up to PHP 8.6)
- Laravel 12 or 13
Installation
You can install the package via Composer:
$ composer require onlime/laravel-http-client-global-logger
Configuration
This is a zero-configuration package. It is auto-discovered by Laravel and global logging is enabled by default. No further configuration needed - you may skip directly to the Usage section below.
Optionally publish the config file with:
$ php artisan vendor:publish --provider="Onlime\LaravelHttpClientGlobalLogger\Providers\ServiceProvider"
You may override its configuration in your .env - the following environment vars are supported:
HTTP_CLIENT_GLOBAL_LOGGER_ENABLED(bool)HTTP_CLIENT_GLOBAL_LOGGER_MIXIN(bool)HTTP_CLIENT_GLOBAL_LOGGER_CHANNEL(string)HTTP_CLIENT_GLOBAL_LOGGER_LOGFILE(string)HTTP_CLIENT_GLOBAL_LOGGER_REQUEST_FORMAT(string)HTTP_CLIENT_GLOBAL_LOGGER_RESPONSE_FORMAT(string)HTTP_CLIENT_GLOBAL_LOGGER_EXCEPT(string, comma-separated URL patterns with wildcard support)HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_ENABLED(bool)HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_REPLACEMENT(string)HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_HEADERS(string, comma-separated header name patterns with wildcard support)HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_BODY_KEYS(string, comma-separated key patterns with wildcard support)HTTP_CLIENT_GLOBAL_LOGGER_TRIM_RESPONSE_BODY_ENABLED(bool)HTTP_CLIENT_GLOBAL_LOGGER_TRIM_RESPONSE_BODY_LIMIT(int)HTTP_CLIENT_GLOBAL_LOGGER_TRIM_RESPONSE_BODY_CONTENT_TYPE_WHITELIST(string)
(look into config/http-client-global-logger.php for defaults, further configuration, and explanation)
Features
Using the logger will log both the request and response of an external HTTP request made with the Laravel HTTP Client.
- Multi-line log records that contain full request/response information (including all headers and body)
- Logging into separate logfile
http-client.log. You're free to override this and use your own logging channel or just log to a different logfile. - Full support of Guzzle MessageFormatter variable substitutions for highly customized log messages.
- Obfuscation of credentials in headers, URL and body (JSON or form), see Sensitive data
- URL exclusion patterns to skip logging for specific URLs (e.g.
HTTP_CLIENT_GLOBAL_LOGGER_EXCEPT=https://api.pirsch.io/*,https://sentry.io/*) - Trimming of response body content to a certain length with support for
Content-Typewhitelisting - Enforce trimming of response body content by setting a
X-Global-Logger-Trim-Alwaysrequest header, which will ignore the whitelisting. - Variant 1: Global logging (default)
- Zero-configuration: Global logging is enabled by default in this package.
- Simple and performant implementation using
RequestSending/ResponseReceivedevent listeners - Also logs Saloon requests if saloonphp/laravel-plugin is installed
- Variant 2: Mixin (
HTTP_CLIENT_GLOBAL_LOGGER_MIXIN=true)- Enabled only on individual HTTP Client instances, using
Http::log()- no global logging. - Log channel name can be set per HTTP Client instance by passing a name to
Http::log($name)
- Enabled only on individual HTTP Client instances, using
- Variant 3: Global HTTP Middleware
- Can be used in combination with other
Http::globalRequestMiddleware()calls in yourAppServiceProvider'sboot()method, after registering your Global Middleware.
- Can be used in combination with other
Usage
NOTE: For all 3 variants below, you need to keep the HTTP Client Global Logger enabled (not setting
HTTP_CLIENT_GLOBAL_LOGGER_ENABLED=falsein your.env). Thehttp-client-global-logger.enabledconfig option is a global on/off switch for all 3 variants, not just the "global" variants. Our project name might be misleading in that context.
Variant 1: Global Logging
Just use Laravel HTTP Client as always - no need to configure anything!
Http::get('https://example.com');
Slightly more complex example:
$client = Http::withOptions([ 'base_uri' => 'https://example.com', 'allow_redirects' => false, ]); $response = $client->get('/user');
Variant 2: Mixin Variant
If you enable mixin variant, global logging will be turned off. Put this into your .env:
HTTP_CLIENT_GLOBAL_LOGGER_MIXIN=true
You could then turn on logging individually on each HTTP Client instance, using the log() method:
Http::log()->get('https://example.com');
Logging with custom channel name (if not specified, defaults to current environment, such as production or local):
Http::log('my-api')->get('https://example.com');
Slightly more complex example:
$client = Http::log('my-api')->withOptions([ 'base_uri' => 'https://example.com', 'allow_redirects' => false, ]); $response = $client->get('/user');
Variant 3: Global HTTP Middleware
If you use Global Middleware (Http::globalRequestMiddleware() and Http::globalResponseMiddleware() methods), you should be aware that Variant 1 uses Laravel's RequestSending event to log HTTP requests. This event is fired before Global Middleware is executed. Therefore, any modifications to the request made by Global Middleware will not be logged. To overcome this, this package provides a middleware that you may add after your Global Middleware.
You may add the middleware using the static addRequestMiddleware() method on the HttpClientLogger class:
use Onlime\LaravelHttpClientGlobalLogger\HttpClientLogger; HttpClientLogger::addRequestMiddleware();
For example, you may add this to your AppServiceProvider's boot() method after registering your Global Middleware:
use Illuminate\Support\Facades\Http; use Onlime\LaravelHttpClientGlobalLogger\HttpClientLogger; Http::globalRequestMiddleware(fn ($request) => $request->withHeader( 'User-Agent', 'My Custom User Agent' )); HttpClientLogger::addRequestMiddleware();
Logging example
By default, logs are written to a separate logfile http-client.log.
Log entry example:
[2021-07-11 11:29:58] local.INFO: REQUEST: GET https://example.com/user
GET /user HTTP/1.1
User-Agent: GuzzleHttp/7
Host: example.com
Authorization: [redacted]
[2021-07-11 11:29:58] local.INFO: RESPONSE: HTTP/1.1 200 OK
HTTP/1.1 200 OK
Date: Fri, 18 Jun 2021 09:29:58 GMT
Server: nginx
Content-Type: application/json
{"username":"foo","email":"foo@example.com"}
FAQ
How does this package differ from bilfeldt/laravel-http-client-logger ?
Honestly, I did not really look into bilfeldt/laravel-http-client-logger, as my primary goal was to build a global logger for Laravel HTTP Client without any added bulk. Global logging currently (as of July 2021) is still an open issue, see bilfeldt/laravel-http-client-logger#2 - Add global logging.
Both packages provide a different feature set and have those advantages:
- onlime/laravel-http-client-global-logger (this package)
- global logging
- auto-configured log channel
http-clientto log to a separatehttp-client.logfile - Full support of Guzzle MessageFormatter variable substitutions for highly customized log messages.
- obfuscation of credentials in HTTP Client requests and responses
- trimming of response body content
- bilfeldt/laravel-http-client-logger
- conditional logging using
logWhen($condition) - filtering of logs by HTTP response codes
- currently still supports PHP 7.4+
- conditional logging using
So, my recommendation: If you need global logging without any extra configuration and without changing a line of code in your project, go for my package. If you don't want to log everything and wish to filter by HTTP response code, go for Bilfeldt's package. But don't install both!
Caveats
-
This package currently uses two different implementations for logging. In the preferred variant 1 or 3 (global logging), it is currently not possible to configure the log channel name which defaults to current environment, such as
productionorlocal. If you with to use Laravel HTTP Client to access multiple different external APIs, it is nice to explicitly distinguish between them by different log channel names.As a workaround, I have implemented another way of logging through
Http::log()method as mixin. But of course, we should combine both variants into a single one for a cleaner codebase.
Sensitive data
The log contains full requests and responses, including all headers and bodies. Credentials are obfuscated by default (HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_ENABLED), in all 3 variants, replaced by [redacted] (HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_REPLACEMENT):
- Headers of requests and responses whose name matches
HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_HEADERS, defaults to*authorization,*cookie,*password*,*token*,*key,*secret*. E.g.Authorization,Proxy-Authorization,Cookie,Set-Cookie,X-Api-Password,PRIVATE-TOKENorX-Api-Key. Body keys in the values of other headers are obfuscated too, e.g.X-Debug: token=[redacted]. - Values of body keys whose name matches
HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_BODY_KEYS, defaults topass,*password*,*token*,*secret*,*key,*signature*,sig. They are replaced in JSON-style ("key":"value") and form/query-style (key=value) text of the formatted message, which covers JSON and form bodies, and the query string of the URL. E.g.{"password":"[redacted]"},refresh_token=[redacted]or?api_key=[redacted]. - The password in the URL, e.g.
https://user:[redacted]@example.com. - Password hashes of known algorithms in the modular crypt format (
$<identifier>$…), anywhere except for their algorithm identifier, also in the values of the body keys above, like in onlime/laravel-sql-reporter. E.g.$2y$[redacted](bcrypt),$argon2id$[redacted], or legacy ones like$6$[redacted](SHA-512-crypt) or$P$[redacted](phpass). Other values like$Summer-2024$…aren't taken for a hash.
Patterns are comma-separated and case-insensitive, and empty ones are ignored. They support wildcards using *, for headers like Str::is(). For body keys, a leading * matches anything, as the match may then start anywhere in a key, e.g. "api key" for *key. A * within or at the end of a body key pattern matches up to 100 characters of a key: letters, digits, _, ., -, %, [ and ], e.g. user[password] or user%5Bpassword%5D for *password*.
Not obfuscated:
- Keys and headers with other names. Add them to the patterns above.
- Other body formats, e.g. XML or
multipart/form-data. Exclude such URLs from logging withHTTP_CLIENT_GLOBAL_LOGGER_EXCEPT. - JSON values other than strings, e.g.
{"pin":1234}or{"tokens":["…"]}, and JSON within a JSON string, e.g.{"payload":"{\"password\":\"…\"}"}. - Nested or array keys in form bodies for patterns without a trailing
*, e.g.credentials[api_key]=…for*key, orsig[]=…forsig. - Secrets in the path of the URL, or a token as its user name without password, e.g.
https://TOKEN@example.com. - URL-encoded password hashes (
%242y%24…) in the values of other keys.
A body is never logged unobfuscated: if it can't be obfuscated, e.g. a JSON value with hundreds of thousands of escaped characters exceeding PCRE's limits without its JIT, it is left out of the log entry ([body not logged: …]).
Protect the log file like any other log of your application: it is created with the same permissions as Laravel's own logs. If logging fails, e.g. because the log file isn't writable, the exception is reported and the HTTP request is sent as usual. This applies to the global logging variants 1 and 3, while the mixin variant (Http::log()) throws the exception.
Upgrading
v1.6.0
The defaults of HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_HEADERS, HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_BODY_KEYS and HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_REPLACEMENT have changed. If you set any of them in your .env, or published the config file, compare them with the new defaults in config/http-client-global-logger.php, as your values replace them. Matching is case-insensitive now, with wildcard support, so your existing names keep working. Empty entries, e.g. from a trailing comma, are ignored now: in v1.5.0, an empty entry of HTTP_CLIENT_GLOBAL_LOGGER_OBFUSCATE_BODY_KEYS obfuscated all form and query values by accident.
Testing
We're using Pest for testing, Larastan for static analysis, and Pint for code style:
$ composer test # run the test suite $ composer test-coverage # run the test suite with coverage report (requires pcov or Xdebug) $ composer analyse # run static analysis $ composer lint # check code style (use `composer format` to fix it)
Changes
All changes are listed in CHANGELOG
Authors
Made with ❤️ by Philip Iezzi (Onlime GmbH).
License
This package is licenced under the MIT license however support is more than welcome.