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:

1. 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.
2. 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.
3. 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
4. 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:

1. The score badge (98/100 Active / Safe) — your instant go/no-go signal.
2. The compatibility answer (✔ YES / ✘ NO → Install vendor/package:x.y.z instead) — tells you the exact version to require.
3. 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.