vanilla / laravel
Utilities and Commands for working with Laravel.
Installs: 60 204
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 3
Forks: 0
Open Issues: 0
Requires
- php: >=8.0
- laravel/framework: ^10.0
- vanilla/garden-utils: ^1.1
Requires (Dev)
- phpunit/phpunit: ^10.2
- vimeo/psalm: ^5.13
README
A set of common laravel utilities and configurations used in Vanilla laravel services.
Installation
Require this package with composer using the following command:
composer require vanilla/laravel
This package makes use of Laravels package auto-discovery mechanism so it should automatically be applied.
Additional Logging Context
This is automatically configured if the package is installed through composer.
Every made during a web request will have the following additional data applied.
{ // ... Basic log data here. "tags": ["webRequest"], "request": { "hostname": "www.your-service.com", "method": "GET", "path": "/some/path/here?queryParams", "protocol": "https", "url": "https://www.your-service.com/some/path/here?queryParams", "clientIP": "0.0.0.0" } }
Improved JSON Log Formatter
To apply this, update your desired log channel in config/logging.php
file to use the new log formatter.
config/logging.php
return [ // ...Other configs here "channels" => [ // ...Other configs here "single" => [ "driver" => "single", "formatter" => VanillaLogFormatter::class, "path" => storage_path("logs/laravel.log"), "level" => env("LOG_LEVEL", "debug"), ], "syslog" => [ "driver" => "syslog", "formatter" => VanillaLogFormatter::class, "level" => env("LOG_LEVEL", "debug"), ], // ...Other configs here ], // ...Other configs here ];
The improved log formatter provides the following behaviours:
- Outputs logs as serialized JSON prepended with
$json:
in the standard vanillav2
logging schema. Vanilla\Laravel\Exception\ContextException
instances will now have their context serialized.- Exception stack traces have improved serialization.
- Frames do not include the base path of the repo.
- Certain common frames are always excludes (like ones in the log formatter and exception handler).
- Vendor stack frames are collapsed.
- Only files and line numbers are included.
- All logs get a minimal stacktrace.
Improved Exception Handling
To apply this have your exception handler in Exceptions\Handler.php
extend from Vanilla\Laravel\Exceptions\ExceptionHandler
instead of Illuminate\Foundation\Exceptions\Handler
.
It has the following improved behaviours
- API responses will always be serialized as JSON.
- Thrown
ContextExceptions
will serialize their context. - If the
app.debug
config is enabled then stack traces will be returned in the JSON output.
Context Exceptions
Oftentimes when you throw an exception you might have some useful structured data that you want captured for logging or an HTTP response.
For these case throw or extend Vanilla\Laravel\Exceptions\ContextException
. It adds an optional array of context
.
Want to add additional context to a caught ContextException
? Use ContextException::withContext($newContext)
.
Configuration Validation
This package registers a new command artisan config:validate
that will automatically run before config:cache
. It will look through your configuration files for validation specification under a ValidateConfigCommand::KEY
key and validate the rest of that configuration file according to those rules.
Example
orch.php
return [ /// /// Config validate here!!! /// ValidateConfigCommand::KEY => [ "type" => ["in:orchestration,local"], "base_url" => ["required", "url"], "search_service_base_url" => ["required", "url"], "hostname" => ["string"], "token" => ["string", "required"], "network" => ["string", "required"], "zone" => ["string", "required"], ], /* |-------------------------------------------------------------------------- | Orchestration |-------------------------------------------------------------------------- | | These fields are used for accessing orchestration and fetching site info. */ "type" => env("ORCH_TYPE", $isOrchestration ? "orchestration" : "local"), // Base URL for orchestration. "base_url" => env("ORCH_BASE_URL"), // Optional. Primarily used in localhost to force `Host` header with a base_url of an internalIP for the VPN. "hostname" => env("ORCH_HOSTNAME"), // Access token used to call orchestration. "token" => env("ORCH_TOKEN"), // Which orchestration network to use. "network" => env("ORCH_NETWORK"), // Which orchestration zone to use. "zone" => env("ORCH_ZONE"), // Base url to use when calling elasticsearch. "search_service_base_url" => env("ORCH_SEARCH_SERVICE_BASE_URL"), ];