Sonata Bundle Laravel Package

Getting Started

• Install the package via Composer and publish its config: php artisan vendor:publish --tag=health-config (tag may vary).
• Register the health check routes if not auto-discovered; the package exposes HealthCheckController with endpoints under /health or a configured prefix.
• Run the first check: php artisan health:check or hit the JS vulnerability endpoint. The getJsVulnerabilities action now uses npm audit instead of yarn audit to detect JavaScript CVEs.
• First use case: add a scheduled job ($schedule->command('health:check')->daily()) to surface vulnerable npm dependencies alongside Laravel health checks.

Implementation Patterns

• Scheduled vulnerability scans – wrap the JS vulnerability check in a scheduled command and pipe results to Slack/email via Laravel’s notification system.
• CI integration – call the health endpoint in your pipeline (curl -f https://app.test/health/js-vulnerabilities) to fail builds when npm audit reports high/critical CVEs.
• Custom result formatting – extend or decorate HealthCheckController to normalise npm audit JSON into your dashboard’s expected shape (e.g. counts by severity).
• Mixed‑stack projects – when a project uses both PHP and JS, combine this check with PHP dependency checks in a single health dashboard.
• Config‑driven thresholds – publish the config and set minimum severity levels so npm audit only fails the check for high or critical findings.

Gotchas and Tips

• Package manager switch (v2.14.0) – the check now runs npm audit, not yarn audit. Projects still using Yarn must ensure package-lock.json exists and that npm is available in the runtime environment. Yarn‑only lockfiles (yarn.lock) will cause npm audit to fail or report zero results.
• Lockfile requirement – npm audit requires a package-lock.json. If your project uses Yarn, you may need to generate one (npm install --package-lock-only) or override the check.
• Network and registry access – npm audit contacts the npm registry. In air‑gapped or rate‑limited environments, cache results or fall back to a local audit tool. Set npm_config_registry if using a private registry.
• Exit codes – npm audit returns non‑zero when vulnerabilities are found; the health check must interpret this correctly rather than treating it as a command failure. Check the package’s handling of exit codes after upgrading.
• Debugging – run php artisan health:check --verbose and inspect the raw npm audit --json output. If the check silently passes, verify that node and npm are on the PATH used by your web server or queue worker.
• Extension points – override the controller’s getJsVulnerabilities method or bind a custom implementation if you need to support Yarn, pnpm, or a different audit command. The config file usually allows swapping the check class.