README

Check the health of any PHP/Laravel package before you install it.

One artisan command gives you a 0–100 health score built from live Packagist + GitHub data, a Laravel compatibility answer, smart alternative suggestions, JSON output for CI/CD pipelines — and an optional AI verdict.

php artisan package:health spatie/laravel-permission --laravel=10

  📦 spatie/laravel-permission   98/100 Active / Safe
  Permission handling for Laravel 12 and up

  5 Dimensions. 1 Health Score.
  🔧 Maintenance    █████████████████████████  93/100
  👥 Community      █████████████████████████ 100/100
  📥 Usage          █████████████████████████ 100/100
  🧱 Stability      █████████████████████████ 100/100
  🔒 Security       █████████████████████████ 100/100

  ⬇  Total downloads      99,935,637
  ⬇  Monthly downloads    4,027,071
  ⭐ GitHub stars         12,910
  ⚠  Open issues          0
  🏷  Latest version       8.0.0
  🕐 Last updated         7 days ago

  🖥  Will it work on Laravel 10?
  ✘ NO — The latest release (8.0.0) does not support Laravel 10.
  → Install spatie/laravel-permission:6.25.0 instead.

  ✔ Recommendation
  Healthy and actively maintained. Safe to install.

  💡 Alternatives (similar packages, by usage)
  bezhansalleh/filament-shield            3,655,723 downloads
  kodeine/laravel-acl                     359,032 downloads

  🔗 Sources (verify every number yourself)
  Packagist: https://packagist.org/packages/spatie/laravel-permission
  GitHub:    https://github.com/spatie/laravel-permission

Features

🩺 0–100 health score — weighted across 5 dimensions: Maintenance, Community, Usage, Stability, Security
📡 Live data from Packagist + GitHub — downloads, stars, releases, issues, security advisories, abandoned flags
🖥 Laravel version compatibility check — "will it work on Laravel X?" with the exact older version to install when the latest doesn't
💡 Smart alternatives — similar packages ranked by usage
🤖 Optional AI verdict — a short Claude-written recommendation (bring your own Anthropic API key; everything else works without one)
⚙️ JSON output + --min-score gate — drop it straight into CI/CD pipelines
🌐 Web dashboard — visit /laravel-health-monitor in your app to check any package in the browser and audit everything already installed in your project
🛡 Full project audit — one click checks every installed package for known CVEs and abandonment, health-scores your direct requirements, and scans your application code for malware indicators (webshells, obfuscated eval chains, PHP dropped in storage/uploads) plus hygiene problems (debug mode in production, exposed .env/.git)
🚀 Simple installation — one composer require, zero configuration required

Perfect for

Laravel developers deciding between packages
Development teams enforcing package quality standards
DevOps pipelines gating dependencies in CI
Production applications auditing what they already depend on

Requirements

PHP 7.2.5+
Laravel 7, 8, 9, 10, 11, 12 or 13
No API key needed (AI verdict is the only optional key-gated feature)

Installation

composer require elsner/laravel-health-monitor --dev

The service provider is auto-discovered. Optionally publish the config:

php artisan vendor:publish --tag=health-monitor-config

Usage

# Basic health check
php artisan package:health spatie/laravel-permission

# Will it work on my Laravel version?
php artisan package:health spatie/laravel-permission --laravel=10

# Machine-readable output for CI/CD
php artisan package:health spatie/laravel-permission --json

# Fail the build when the score is too low (CI gate)
php artisan package:health spatie/laravel-permission --json --min-score=70

# Include an AI verdict (requires ANTHROPIC_API_KEY)
php artisan package:health spatie/laravel-permission --ai

# Bypass the cache and fetch live data
php artisan package:health spatie/laravel-permission --fresh

Web dashboard

Once the package is installed, open:

https://your-app.test/laravel-health-monitor

You get a browser dashboard that:

Checks any package on Packagist — type any vendor/package (not just Laravel packages), pick a Laravel version, and get the full health report: score badge, 5 dimension bars, live metrics, compatibility answer, security advisories, alternatives and sources.
Lists every package installed in your project — read from your app's composer.lock, with direct/dev requirements flagged and a one-click "Check health" link per package.
Runs a full project audit — packages, code and hygiene in one report (see below).
Serves JSON too — append &format=json to /laravel-health-monitor/check?package=vendor/package for machine-readable output.

Click Check health on any package (installed or not) for the full report:

Configure it in config/health-monitor.php:

'web' => [
    'enabled' => env('HEALTH_MONITOR_WEB_ENABLED', true), // disable the routes entirely
    'path' => env('HEALTH_MONITOR_WEB_PATH', 'laravel-health-monitor'), // URL prefix
    'middleware' => ['web'], // add 'auth' to restrict access
],

Tip: in production, either disable the dashboard (HEALTH_MONITOR_WEB_ENABLED=false) or add auth middleware — the page reveals your dependency list and audit results.

The views are publishable if you want to restyle them:

php artisan vendor:publish --tag=health-monitor-views

Full project audit (packages + code + malware scan)

Click Run project audit on the dashboard (or open /laravel-health-monitor/audit) and the package audits your whole application in four steps:

All installed packages checked for known vulnerabilities — every entry in your composer.lock is checked against the Packagist security-advisory database (batched, one HTTP request per 50 packages) and for abandoned flags.
Direct requirements health-scored — each package you explicitly require gets the full 0–100 health analysis, listed worst-first so you see what needs attention. Capped by health-monitor.audit.max_health_checks (default 25) to respect GitHub's 60 req/hour unauthenticated limit — set HEALTH_MONITOR_GITHUB_TOKEN to raise it.
Code scan for malware indicators — your app/, config/, routes/, public/, storage/app … directories are scanned for:
- obfuscated eval(base64_decode(...)) / gzinflate / str_rot13 payload chains
- eval(), assert(), system(), exec() fed by $_GET/$_POST/$_REQUEST input (backdoors/webshells)
- request input used as a function name, include/require from request input or remote URLs
- unserialize()/extract() of request input, preg_replace /e, create_function()
- known webshell filenames (c99, r57, b374k, wso, …), PHP files with double extensions (avatar.jpg.php), PHP dropped in storage/ or the public web root
- heavy hex obfuscation and suspicious base64 blobs
Project hygiene — APP_DEBUG on outside local, missing APP_KEY, .env or .git exposed in the public web root, missing composer.lock.

Everything is condensed into one 0–100 project score. JSON output for CI: /laravel-health-monitor/audit?format=json; force live data with ?fresh=1.

Tune the scan in config/health-monitor.php:

'audit' => [
    'max_health_checks' => env('HEALTH_MONITOR_AUDIT_HEALTH_CHECKS', 25),
    'scan' => [
        'paths' => ['app', 'bootstrap', 'config', 'database', 'routes', 'resources', 'public', 'storage/app'],
        'exclude' => ['vendor', 'node_modules', 'storage/framework', 'bootstrap/cache'],
        'max_files' => 5000,
        'max_file_size' => 1048576, // skip files over 1 MB
    ],
],

Note: the code scan is a heuristic indicator scanner, not an antivirus. Findings are leads to review — and a clean result is not a guarantee. If you suspect a real compromise, rotate credentials and redeploy from a known-good source.

JSON output (CI/CD)

--json prints a single JSON document; the exit code is 0 on success and 1 when the package is missing or below --min-score:

{
    "package": "spatie/laravel-permission",
    "score": 98,
    "status": "Active / Safe",
    "recommendation": "Healthy and actively maintained. Safe to install.",
    "dimensions": {
        "maintenance": 93,
        "community": 100,
        "usage": 100,
        "stability": 100,
        "security": 100
    },
    "compatibility": {
        "laravel": "10",
        "latest_version": "8.0.0",
        "latest_compatible": false,
        "compatible_version": "6.25.0"
    },
    "security": { "advisories": [], "abandoned": false, "replacement": null },
    "alternatives": [ ... ],
    "sources": { ... },
    "ai_verdict": null
}

GitHub Actions example:

- name: Gate new dependency
  run: php artisan package:health vendor/package --json --min-score=70

Configuration

All settings are environment-driven — publishing the config file is optional.

Env variable	Purpose	Default
`HEALTH_MONITOR_GITHUB_TOKEN` (or `GITHUB_TOKEN`)	Raises GitHub API rate limit from 60 to 5000 req/h	none
`HEALTH_MONITOR_ANTHROPIC_KEY` (or `ANTHROPIC_API_KEY`)	Enables the `--ai` verdict	none
`HEALTH_MONITOR_AI_MODEL`	Claude model for the verdict	`claude-opus-4-8`
`HEALTH_MONITOR_CACHE_TTL`	API response cache in seconds (0 disables)	`3600`
`HEALTH_MONITOR_HTTP_TIMEOUT`	HTTP timeout in seconds	`15`

Step-by-step: using the plugin day to day

Step 1 — Before installing any new package

php artisan package:health vendor/package --laravel=13

Read the three key lines first:

The score badge (98/100 Active / Safe) — your instant go/no-go signal.
The compatibility answer (✔ YES / ✘ NO → Install vendor/package:x.y.z instead) — tells you the exact version to require.
The recommendation line — a plain-language summary of the verdict.

If all three look good, install it. If compatibility says NO, use the suggested version:

composer require vendor/package:^6.25

Step 2 — When comparing two packages for the same job

Run the check on both, then compare dimension by dimension:

php artisan package:health spatie/laravel-permission --laravel=13
php artisan package:health santigarcor/laratrust --laravel=13

Also look at the 💡 Alternatives section of each report — it may surface a third option you didn't know about, ranked by real download numbers.

Step 3 — Auditing what you already depend on

Check the direct dependencies from your composer.json:

php artisan package:health barryvdh/laravel-dompdf --laravel=13
php artisan package:health maatwebsite/excel --laravel=13

Anything scoring below 60, abandoned, or carrying security advisories goes on your migration list.

Step 4 — Enforcing quality in CI

Gate new dependencies in your pipeline so low-quality packages never reach main:

# .github/workflows/ci.yml
- name: Dependency health gate
  run: php artisan package:health vendor/package --json --min-score=70

Exit code 0 = pass, 1 = below the bar (or package not found) — the build fails automatically.

Step 5 — When you want a second opinion

php artisan package:health vendor/package --ai

With an Anthropic API key configured, Claude reads all collected metrics and writes a short verdict naming the strongest signal in favor and the biggest risk.

How to read the scores

The overall score

Score	Status	What to do
80–100	🟢 `Active / Safe`	Install with confidence.
60–79	🟡 `Aging / Caution`	Usable, but check which dimension is dragging it down before committing.
0–59	🔴 `Risky / Avoid`	Prefer an alternative. If you must use it, pin the version and plan an exit.
any	🔴 `Abandoned / Avoid`	Maintainer gave up. Use the replacement shown, or an alternative.

Diagnosing a low score, dimension by dimension

The bars tell you why a score is low. Each dimension points at a different real-world problem:

Low dimension	What it means	What to check yourself
🔧 Maintenance	No recent releases or commits. Bugs and Laravel upgrades won't be handled.	Last release date, open PRs sitting unmerged on GitHub.
👥 Community	Few stars/forks/watchers. Fewer people to answer questions or review code.	Are there Stack Overflow answers? Active discussions/issues?
📥 Usage	Few downloads and dependents. Less battle-tested — edge cases may be yours to find.	Is the package new (fine) or old-but-unused (red flag)?
🧱 Stability	Pre-1.0, few releases, or very young. API may break between versions.	Changelog / upgrade guide quality, semver discipline.
🔒 Security	Known advisories, abandoned or archived repo, or no license.	The `🛡 Security advisories` list in the report — each entry has a CVE link.

Typical patterns:

High usage + low maintenance → a once-popular package going stale (e.g. fzaninotto/faker). Migrate before it blocks a Laravel upgrade.
High maintenance + low usage/community → young but active package. Fine for non-critical features; pin the minor version.
Security below 100 → scroll to 🛡 Security advisories. Advisories on old versions are normal for mature packages — verify the version you would install is not in the affected range.

Reading the compatibility answer

Output	Meaning
`✔ YES — The latest release (X) supports Laravel N.`	Just `composer require` it.
`✘ NO … → Install vendor/package:X instead.`	Latest dropped your Laravel version; require the shown version explicitly.
`✘ NO … no release supports Laravel N.`	The package never supported your Laravel version. Pick an alternative.
`~ No explicit Laravel requirement found`	Framework-agnostic PHP package — it will work with any Laravel version (verify its PHP version requirement instead).

Exit codes (for scripts and CI)

Code	Cause
`0`	Report produced, score at or above `--min-score` (when given).
`1`	Package not found, invalid name, network failure, or score below `--min-score`.

How the score works

Each dimension is scored 0–100 from live data, then combined with these weights:

Dimension	Weight	Signals
🔧 Maintenance	30%	Days since last release, releases in the last year, recent repo pushes, abandoned/archived flags
🔒 Security	20%	Known security advisories, abandoned/archived status, license presence
📥 Usage	20%	Total + monthly downloads, dependent packages
👥 Community	15%	GitHub stars, forks, watchers
🧱 Stability	15%	1.0+ releases, release history depth, package age

80–100 → Active / Safe
60–79 → Aging / Caution
0–59 → Risky / Avoid

Thresholds and weights live in config/health-monitor.php.

Testing

composer install
composer test

License

MIT — see LICENSE.

elsnertechnologies / laravel-health-monitor

Maintainers

Package info

Statistics

Security