pkdev / reporter
Reports site telemetry (heartbeats, queues, crons, exceptions, deployments) to the PKDev control plane.
Requires
- php: ^8.3
- guzzlehttp/guzzle: ^7.0|^8.0
- illuminate/console: ^12.0|^13.0
- illuminate/contracts: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
Requires (Dev)
- mockery/mockery: ^1.6
- orchestra/testbench: ^10.0|^11.0
- phpunit/phpunit: ^11.0|^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-13 17:15:01 UTC
README
Telemetry reporter for PKDev — sends heartbeats, queue snapshots, cron status, exceptions, and deployment events from your Laravel site to the PKDev control plane.
Requirements
- PHP 8.3+
- Laravel 12 or 13
Installation
composer require pkdev/reporter
Then deploy. Nothing goes in .env.
Within a minute of the deploy, the scheduler runs pkdev:report. With no key configured, it generates one, saves it to storage/app/pkdev-site.key (with the same group and mode as the site's .env), and asks PKDev to enroll the site. The request shows up in the PKDev Ops panel under Sites → waiting for approval. Approve it and the next heartbeat lands.
Enrollment is accepted only from a server registered in PKDev, and nothing reports until it is approved. The site needs a running Laravel scheduler (schedule:run in cron) and a correct APP_URL, which is how PKDev matches it to a site it already probes.
To use a key minted in the Ops panel instead, set PKDEV_SITE_KEY; the site then never enrolls. php artisan pkdev:install writes it to .env for you.
What it does automatically
Once installed, the package hooks into your application with zero additional code:
| Feature | How |
|---|---|
| Heartbeat + queue snapshot | pkdev:report command scheduled every minute via the Laravel scheduler |
| Cron monitoring | Listens to the scheduler's finished, failed and background-finished events — every scheduled command reports one row per run, success or failed, including background tasks |
| Exception reporting | Hooks into Laravel's exception handler via reportable() — unhandled exceptions are reported with class, message, file, line, and trace |
| Deployment notifications | Via the included Deployer recipe (optional) |
Environment variables
All optional.
| Variable | Default | Description |
|---|---|---|
PKDEV_ENABLED |
on when APP_ENV=production, off otherwise |
Set true or false to override |
PKDEV_API_URL |
https://app.pkdev.dev |
PKDev hub URL; http://host.docker.internal:8090 for a hub in Sail |
PKDEV_SITE_KEY |
unset | A key minted in the Ops panel. Unset, the site generates and enrolls its own |
PKDEV_QUEUES |
default |
Comma-separated queue names to monitor |
Feature toggles (all default true):
| Variable | Description |
|---|---|
PKDEV_FEATURE_HEARTBEAT |
Enable/disable heartbeat + queue reporting |
PKDEV_FEATURE_CRON |
Enable/disable cron monitoring |
PKDEV_FEATURE_EXCEPTIONS |
Enable/disable exception reporting |
Deployer integration
If you deploy with Deployer, require the included recipe in your deploy.php to send deployment notifications:
require 'vendor/pkdev/reporter/deployer/pkdev.php';
The recipe runs php artisan pkdev:notify-deployment on the server, so it uses the site's own key and hub URL. It hooks into deploy:success and deploy:failed and sends the branch, commit, deployer username, duration, and status to PKDev. It swallows its own failures, so it can never fail a deploy.
Artisan commands
| Command | Description |
|---|---|
php artisan pkdev:install |
Sets up a key minted in the Ops panel — writes .env, tests connectivity |
php artisan pkdev:report |
Send a heartbeat + queue snapshot; generates a key and enrolls if there is none |
php artisan pkdev:test |
Send a test payload through every pipeline |
php artisan pkdev:ping |
Send a single connectivity test without writing anything |
Local dev (Sail)
The reporter is off outside production. To report from a site in Sail to a PKDev hub in Sail, set:
PKDEV_ENABLED=true
PKDEV_API_URL=http://host.docker.internal:8090
host.docker.internal resolves to your host machine from inside the Sail container, allowing the spoke to reach the hub's exposed port.
Security
Every request carries the site key as a bearer token and an HMAC body signature (X-PKDev-Signature: sha256=...). The key file is never more readable than the site's .env; if the scheduler's user can't give it the .env file's group, it falls back to 0644 and logs one warning. Exception and cron messages pass through a redactor that blanks password=, *_KEY=, bearer tokens and DSN passwords before they leave the site.