First init

README.md

@@ -0,0 +1,92 @@
+# herrleinIT Log Handler
+
+This Laravel 12 package captures every log record emitted by your application in real time and forwards it to an external HTTP endpoint while optionally continuing to write to existing log channels (e.g. `single`, `daily`).
+
+## Features
+- Pushes every Monolog record to a configurable HTTP endpoint using Bearer token authentication.
+- Installs as a stackable log channel so you can combine it with your existing file / daily / slack channels.
+- Publishes a configuration file with sensible defaults and `.env` overrides for endpoint, token, timeouts, retries, and trace inclusion.
+- Provides PHPUnit feature coverage to ensure integration behaviour within a Laravel 12 application.
+
+## Installation
+
+Assuming the package is required locally via Composer path repository (as in this project):
+
+```bash
+composer require herrleinit/loghandler:@dev
+```
+
+Laravel will auto-discover the `LogHandlerServiceProvider`.
+
+## Configuration
+
+1. **Publish the config** (optional, but helpful for tweaking in code):
+   ```bash
+   php artisan vendor:publish --tag=loghandler-config
+   ```
+
+2. **Environment variables** – add these to your `.env` (defaults shown):
+   ```env
+   LOGHANDLER_ENDPOINT=http://test.example/api/error/create
+   LOGHANDLER_TOKEN=your-bearer-token
+   LOGHANDLER_SOURCE="${APP_NAME}"
+   LOGHANDLER_ENABLED=true
+   LOGHANDLER_TIMEOUT_MS=3000
+   LOGHANDLER_RETRY_TIMES=0
+   LOGHANDLER_INCLUDE_TRACE=false
+   ```
+
+3. **Logging stack** – ensure the `loghandler` channel participates in your default stack:
+   ```env
+   LOG_CHANNEL=stack
+   LOG_STACK=single,loghandler
+   ```
+   This keeps the usual `storage/logs/laravel.log` file while forwarding every entry to the remote API. You can swap `single` for `daily` or any other channels you need.
+
+4. **Config cache** – whenever you change logging env values, clear cached configuration:
+   ```bash
+   php artisan config:clear
+   ```
+
+## Runtime Behaviour
+- The package registers a custom Monolog handler through `Log::extend('loghandler', ...)` so it can be part of any stack or used standalone via `Log::channel('loghandler')`.
+- When enabled and provided with a token + endpoint, each `LogRecord` is transformed into the required JSON payload:
+  ```json
+  {
+    "source": "Project Name",
+    "error": "Stack error",
+    "type": "E_WARNING",
+    "file": "/var/test/testfile.php",
+    "line": "1337",
+    "trace": "..."
+  }
+  ```
+- Retries are configurable via `retry_times`, and `include_trace` toggles stack traces for non-exception logs.
+
+## Verifying Connectivity
+To confirm logs reach your endpoint from a given environment, run:
+```bash
+php artisan tinker
+>>> Log::error('LogHandler connectivity check', ['file' => __FILE__, 'line' => __LINE__]);
+```
+If your stack includes `loghandler`, that call will POST to the configured endpoint. Inspect the remote API or monitor network traffic to verify delivery.
+
+## Testing
+The package ships with PHPUnit feature tests (`tests/Feature/LogForwardingTest.php`) built on [Orchestra Testbench](https://github.com/orchestral/testbench) to verify:
+- Exception payload forwarding
+- Disabled / missing token branches
+- Delivery via the default `stack` channel
+
+From inside the package directory you can execute:
+```bash
+composer install
+vendor/bin/phpunit -c phpunit.xml
+```
+
+When the package is installed inside a Laravel application (like this repo), you can also keep using the host app's suite:
+```bash
+php artisan test --filter=LogForwardingTest
+```
+
+---
+Need a different logging topology or additional telemetry fields? Extend `LogForwarder` or create another handler and register it alongside this package.