README

Laravel plugin of the mindtwo monitoring suite. On top of mindtwo/base-monitoring — which collects OS, web server, database, Node.js, system stats, Composer/npm packages, security audits, licenses and git status — this package adds:

• Laravel collectors — framework version, operational environment (debug flag, maintenance mode, drivers, optimization caches) and the live database server version from your actual connection.
• Push — a scheduled monitoring:push run delivering signed snapshots to the central endpoint.
• Pull — a throttled, HMAC-authenticated GET /api/m2-monitoring endpoint with optional IP allow-listing and short-lived snapshot caching.
• DX tooling — monitoring:show, monitoring:push --dry-run, monitoring:collectors, php artisan about integration and a facade for custom data.

Installation

composer require mindtwo/laravel-monitoring

Set your credentials (issued by the monitoring dashboard) in .env:

MONITORING_PROJECT_KEY=prj_live_8f3a…
MONITORING_SECRET=base64-encoded-shared-secret

That's it. The service provider auto-registers, the pull endpoint goes live at /api/m2-monitoring, and a push is scheduled daily at 03:00 — provided your scheduler is running.

Publish the config when you need to customize more:

php artisan vendor:publish --tag=monitoring-config

Configuration

Everything is configurable via .env without publishing:

Artisan commands

php artisan monitoring:show              # human-readable snapshot table
php artisan monitoring:show --json       # the full payload
php artisan monitoring:push --dry-run    # print what would be sent
php artisan monitoring:push              # build + deliver a snapshot now
php artisan monitoring:collectors        # registered collectors + support status

monitoring:show example:

+---------------------+--------+----------------------------+
| Metric              | Status | Details                    |
+---------------------+--------+----------------------------+
| os                  | ok     | macos 14.4.1               |
| php                 | ok     | php 8.3.2                  |
| database            | ok     | mysql 8.0.36               |
| laravel             | ok     | laravel 11.9.0             |
| composer_packages   | ok     | 73 packages                |
| composer_audit      | ok     |                            |
| nginx               | unsup… |                            |
+---------------------+--------+----------------------------+

The pull endpoint

GET /api/m2-monitoring returns the current snapshot as JSON. Every request must be signed:

X-Monitoring-Key:       <project key>
X-Monitoring-Timestamp: <unix timestamp>
X-Monitoring-Signature: hex( hmac_sha256( "<timestamp>.<raw request body>", secret ) )

The body of a pull GET is empty, so the signed string is simply "<timestamp>.". Example:

TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s.' "$TIMESTAMP" | openssl dgst -sha256 -hmac "$MONITORING_SECRET" -hex | sed 's/^.* //')

curl https://example.com/api/m2-monitoring \
  -H "X-Monitoring-Key: $MONITORING_PROJECT_KEY" \
  -H "X-Monitoring-Timestamp: $TIMESTAMP" \
  -H "X-Monitoring-Signature: $SIGNATURE"

Defense layers, in request order:

1. Rate limiting — 10 requests/minute per IP by default (throttle:monitoring).
2. IP allow-list (optional) — plain IPs and CIDR ranges, IPv4 + IPv6. Behind a load balancer, configure trusted proxies so the client IP resolves correctly.
3. Signature verification — constant-time HMAC comparison plus a timestamp tolerance window against replays. Unconfigured credentials answer 503 and never expose data.
4. Snapshot caching — responses are cached for 5 minutes by default, keeping repeated polls from re-running expensive audit collectors.

Customizing

Choose or add collectors

The collectors config array is the single source of truth — reorder, remove, or add entries. Every class is resolved through the container:

// config/monitoring.php
'collectors' => [
    // ...defaults...
    \App\Monitoring\HorizonCollector::class,
],

namespace App\Monitoring;

use Mindtwo\Monitoring\Collectors\AbstractCollector;
use Mindtwo\Monitoring\Data\CollectionResult;

final class HorizonCollector extends AbstractCollector
{
    public function key(): string
    {
        return 'horizon';
    }

    public function collect(): CollectionResult
    {
        return CollectionResult::ok($this->key(), [
            'status' => 'running',
        ]);
    }
}

Attach custom data

use Mindtwo\Monitoring\Laravel\Facades\Monitoring;

Monitoring::addCustomData('deployment', fn () => [
    'region' => config('app.region'),
    'release' => exec_free_release_id(),
]);

Closures are evaluated lazily and fault-isolated — a throwing provider records an error under its key instead of breaking the snapshot.

Replace the transport

Bind your own Mindtwo\Monitoring\Contracts\Transport implementation to ship snapshots anywhere else (S3, a queue, a different protocol):

$this->app->singleton(\Mindtwo\Monitoring\Contracts\Transport::class, MyTransport::class);

How pushing works

monitoring:push is registered on the scheduler (daily at 03:00 by default) with withoutOverlapping(), onOneServer() and runInBackground(). The command builds a snapshot — every collector individually fault-isolated — signs the JSON payload and POSTs it through Laravel's HTTP client, so Http::fake() sees it in your tests.

Delivery failures exit non-zero with a clear message; they never throw.

Testing your integration

use Illuminate\Support\Facades\Http;

Http::fake(['monitoring.mindtwo.com/*' => Http::response('', 200)]);

$this->artisan('monitoring:push')->assertExitCode(0);

Http::assertSent(fn ($request) => $request->hasHeader('X-Monitoring-Signature'));

Development

composer install
composer check    # pint --test + larastan (level 8) + pest

Security

If you discover a security issue, please email info@mindtwo.de instead of opening a public issue.

License

The MIT License (MIT). See LICENSE.md.