Larabeacon Laravel Package

Getting Started

Install it as a dev dependency and treat it as a pre-upgrade and CI gate rather than a linter you run on every save:

composer require --dev baer-software/larabeacon:^3.2

Then:

1. Find the scan command first. Run php artisan list and look for the LaraBeacon namespace (the release notes reference profiles and flags but not the command signature). Confirm the flags you care about with php artisan <command> --help before scripting anything.
2. Run a default scan once, interactively. This is the mode that shows terminal hints and, in 3.2, includes the new Laravel/PHP security-support checks.
3. Run the production profile: php artisan <command> --profile=production. This is the scan you should wire into a release gate — same checks plus production-oriented rules.
4. First real use case: open the project you're planning to upgrade, run the default scan, and read the support-check output as an early warning, not a bug list. On 3.2 you will likely see Laravel 12 (supported until 2027-02-24) and PHP 8.2 (until 2026-12-31) flagged, because both fall inside the default support_warning_days of 180. Decide immediately whether you want that signal (keep 180) or a quieter default (drop to ~90).

Commit a baseline on day one — see below — so the tool is useful from the first CI run instead of drowning you in pre-existing findings.

Implementation Patterns

Baseline-first adoption. On an existing codebase, don't turn the scan into a hard gate on the first run. Generate a baseline, commit it to the repo, and pass it via the baseline input (or the equivalent CLI flag). Now the gate only fails on new findings — which is what you actually want from a day-to-day tool. Regenerate the baseline deliberately after you've accepted a batch of findings.

GitHub Actions as the default CI shape. The 3.2 action keeps this simple:

- uses: A-Baer/LaraBeacon@v3
  with:
    working-directory: .
    profile: production
    fail-on: error
    baseline: larabeacon-baseline.json
    upload-sarif: true

Useful behaviours baked in: it runs the CI profile, uploads SARIF to GitHub code scanning, and preserves the scan's exit status — so the job fails when the scan fails. Use sarif-file when you want to inspect the artifact before upload, upload-sarif: false on forks where code scanning isn't configured, and args to pass through anything the action doesn't surface as a first-class input.

Non-GitHub CI. Set sarif-file (or the CLI's SARIF export) and feed it to whatever your platform uses — GitLab, Azure DevOps and most scanners accept SARIF. The scan stays non-interactive there, so no Pro/Cloud hints pollute the logs.

Use the profile split intentionally. CI mode deliberately excludes the Laravel/PHP support checks so existing pipelines didn't break on upgrade. That means:

• CI profile → fast, deterministic, diff-focused gate. Good for every push.
• Default / --profile=production → the upgrade-readiness view. Run these on a schedule (nightly/weekly cron), on a pre-upgrade branch, or as a manual workflow_dispatch, and read the support-check output as a planning input.

A cron job running the production profile is the highest-value pattern here: you get a heads-up months before a Laravel or PHP EOL, without coupling your PR pipeline to calendar dates.

Laravel Boost for AI agents. 3.2 ships guidelines plus a larabeacon-release-check skill. Run php artisan boost:update after every LaraBeacon bump, then prompt your agent to run the release check as part of a dependency-upgrade workflow. This is the natural home for the "we bumped Laravel, are we ready?" loop — the agent reads findings and proposes fixes rather than you triaging SARIF by hand.

Release checklist integration. Add a step to your upgrade runbook: bump composer.json, run production-profile scan, triage support warnings, regenerate baseline if the accepted set changed.

Gotchas and Tips

The support checks are date bombs. They fail based on wall-clock time, not code changes. A scan that was green yesterday can go red today with zero diff. This is fine in a scheduled job, but do not put the default or production profile in every-PR CI — that's precisely why CI mode excludes these checks. If you do want them in PRs, lower support_warning_days to something like 30–60 so you're only failing when it's genuinely urgent.

"CI mode doesn't include support checks" is the whole compatibility story. If your pipeline previously ran --profile=production manually and you now see new failures, it's not a regression — it's the feature. Tune support_warning_days rather than disabling the checks.

Hints only appear on a TTY. Pro prompts and Cloud registration hints are suppressed in CI, --quiet, non-interactive and exported runs. Don't document the Pro upsell as part of the workflow for teammates who only ever see it in exported logs — they won't. Conversely, don't be surprised when a --quiet run "looks different" from a local one.

Project-wide findings land on composer.json in SARIF. Findings with no file of their own are attached to composer.json so code scanning accepts them. Expect composer.json to accumulate alerts that have nothing to do with Composer. Filter by rule ID in the GitHub code-scanning UI, or set fail-on conservatively, rather than assuming composer.json is the culprit.

Exit status flows through the action — don't paper over it. Resist adding continue-on-error: true to the action step. If you need a non-blocking first run, use a baseline and a lenient fail-on, not a swallowed failure.

boost:update is a post-upgrade step, not a one-off. Stale Boost guidelines after a LaraBeacon version bump will give your AI agent the wrong flags and file layout. Pin it into the same command chain as composer update.

Dev dependency, production installs. LaraBeacon is require-dev. Any deploy step that runs composer install --no-dev won't have it — if you gate deploys on a production-profile scan, run the scan as a separate CI job on a full install rather than inside the deploy container.

Baseline drift is silent. A committed baseline suppresses real regressions if it was generated against a very different branch. Regenerate on your main branch after merges, and review baseline diffs in PRs like any other generated artifact.

Extension point to watch: fail-on and baseline together are the entire tuning surface most teams need. If you find yourself filtering SARIF downstream, first check whether fail-on should simply be tighter.