Larabeacon Laravel Package

Technical Evaluation

Architecture fit

LaraBeacon is a development-time Composer dependency (require --dev) with no runtime footprint in the shipped application — no service provider boot cost in production, no migrations, no queue workers. Architecturally it belongs in the same layer as Pint, PHPStan/Larastan and Rector: a quality gate that runs locally and in CI, not a feature of the product.

The v3.2.0 additions extend that layer in three useful directions:

The notable architectural characteristic is that the package is opinionated about vendor lifecycle, not just code correctness. That makes it a good complement to Rector (which performs the actual upgrade) — LaraBeacon signals when, Rector does what. It does not replace either dependency auditing (composer audit) or static analysis; treat findings as a partially overlapping third source.

Integration feasibility

Integration cost is low and well-bounded:

• Install is a single dev requirement; no application code changes.
• The GitHub Action exposes working-directory, profile, fail-on, baseline, sarif-file, upload-sarif and args, which covers monorepos (working-directory), incremental adoption (baseline) and phased enforcement (fail-on) without custom wrapper scripting.
• baseline is the key input for feasibility: it lets us adopt on a large existing codebase without a 400-finding wall on day one.

The two non-trivial dependencies are GitHub code scanning permissions (security-events: write plus code scanning enabled for the repo — GitHub Advanced Security for private repos) and Laravel Boost being present for the guidelines/skill to land. Neither is heavy, but both need to be verified in a pilot rather than assumed.

Technical risk

1. Default-on failing checks in a minor release. The support-window checks run in the default and --profile=production scans and fail when a supported-but-near-EOL release is detected (Laravel 12, PHP 8.2 with the 180-day default). A team that installed LaraBeacon at 3.1 and auto-bumped to 3.2 can see a previously green command start failing with no code change. This is behaviourally a breaking change shipped under a patch/minor version. Mitigation is cheap — set support_warning_days, or use --profile=ci — but it must be documented, because the failure message will be misread as "our stack is insecure."

2. Semantic-version trust. Given the above, "expose to ^3.2" is not a safe consumption policy. Pin to an exact version and let Renovate/Dependabot open a PR, so the CI profile change is reviewed rather than absorbed silently.

3. Floating action tag. uses: A-Baer/LaraBeacon@v3 is a movable major tag on a third-party action that runs with repository token permissions. Pin to a commit SHA, per standard supply-chain hygiene, and review the action's code once before org-wide rollout.

4. Fork/PR token restrictions. SARIF upload requires security-events: write; on pull_request events from forks the token is read-only, so upload-sarif may fail or be skipped while the scan itself succeeds. Decide explicitly whether that is a hard failure or tolerated.

5. Commercial boundary and telemetry. Interactive runs now mention LaraBeacon Pro and link to self-service Cloud registration. The hints are correctly suppressed in CI, quiet, non-interactive and exported runs, so there is no pipeline noise — but we need a written answer on whether Cloud registration or Pro usage transmits source code, findings, or repo metadata off-network. Air-gapped or regulated repos may need the interactive hints and any network calls disabled outright.

6. Exit-status semantics. The action "keeps the scan's exit status," which is right. The open question is whether support-window failures are subject to fail-on severity gating — if not, fail-on: error may still fail the build on an EOL warning, which changes how we tune the gate.

7. Single-maintainer dependency. A-Baer/LaraBeacon is a small-vendor package. A dev-only tool is a low-blast-radius bet, but the CI gate becomes load-bearing once we enforce it — so we need a fallback path (run the artisan command directly, drop the SARIF upload) if maintenance stalls.

Key questions

• What is the exact supported matrix (Laravel and PHP versions) in composer.json for 3.2.x, and what is the vendor's stated support policy for LaraBeacon itself?
• Does the GitHub Action install dependencies itself, or does it require a prior composer install? Does it need a Composer auth token for private packages in a monorepo?
• Are support-window failures classified as errors or warnings for fail-on purposes?
• Does the Cloud registration or any Pro prompt make an outbound network call? What is sent?
• Is there a config file published by the package (so support_warning_days is committed and reviewable) or is it config/env only?
• What is the release cadence and how many maintainers are behind the action repo?
• Does the SARIF output validate against the GitHub code-scanning schema version currently in use, and how are schema changes signalled?

Integration Approach

Stack fit

Fit is good for a standard Laravel estate on GitHub Actions with Composer-based CI. Prerequisites to confirm in the pilot:

• Laravel/PHP versions in use are within the package's supported matrix (the release notes reference Laravel 12 and PHP 8.2 support windows, implying both are supported targets).
• Repos are on GitHub, or we accept console-only output on other CI providers (the artisan command still works; only the Action and SARIF upload are GitHub-specific).
• Code scanning is available — free for public repos, GHAS-licensed for private ones. This is the gating commercial item for a private-repo rollout.

Migration path

There is no prior install, so this is greenfield adoption rather than a migration. Treat it as a four-phase rollout rather than a switch-on:

Do not skip Phase 2. Enforcing without a baseline converts an existing backlog into a blocked release train on day one, and the predictable outcome is that someone disables the check.

Compatibility

• Version pinning: pin LaraBeacon to an exact 3.2.x in composer.json; pin the Action to a SHA, not @v3.
• CI mode is the compatibility bridge. The release explicitly excludes the new support checks from CI mode so existing pipelines don't break. This means teams that want the early-upgrade signal must opt into the default or production profile — a deliberate, documented split we should mirror in our own conventions: CI mode for gating, default/production profile for periodic upgrade-readiness sweeps (e.g. a weekly scheduled job).
• Laravel Boost: if the org uses Boost, php artisan boost:update must run after every LaraBeacon upgrade or the guidelines/skill go stale. That is a manual step today — put it in the developer bootstrap script and note it in the upgrade ticket template.
• Code scanning permissions: add permissions: security-events: write and contents: read explicitly to the workflow; don't rely on default token scopes.

Sequencing

1. Confirm licensing and permissions posture (GHAS availability, SARIF upload policy, network egress questions) — this gates everything downstream.
2. Pilot on one repo in Phase 0/1; produce a one-page findings summary for engineering leadership.
3. Publish org conventions: support_warning_days value, profile usage (CI vs. scheduled production scan), fail-on threshold, SHA pinning, fork-PR policy.
4. Schedule the production-profile sweep as a separate weekly job — this is where the upgrade-readiness value actually lands, and it keeps the failing support checks out of the per-PR path.
5. Baseline and enforce repo-by-repo.
6. Only after the gate is stable, evaluate Boost integration and Pro/Cloud.

Operational Impact

Maintenance

Low, but not zero:

• Dev dependency bumps land as PRs (pinned version → reviewable). Budget ~1 hour per upgrade for the first few.
• php artisan boost:update must follow each upgrade where Boost is used — automate it or it will be forgotten, and stale guidelines are worse than none because AI agents will follow them confidently.
• SARIF schema and GitHub code-scanning behaviour drift occasionally; the sarif-file input lets us decouple generation from upload if needed.
• Watch for a v4 major. Given the 3.2 precedent (behaviour change in a minor), assume future minors may also change default behaviour and review changelogs rather than trusting the range.

Support

• Primary support burden is interpretive, not technical. The most common ticket will be "the scan failed and says our Laravel version is near end of life — are we breached?" The answer is no. Pre-write that runbook: the check is an upgrade-planning signal, support_warning_days is a tunable policy knob, and the resolution is either a scheduled upgrade or a documented, approved window extension.
• Ownership must be explicit. Assign the config/support_warning_days policy and the baseline files to a named owner (platform team), otherwise each repo forks its own policy.
• Vendor support is thin. Small vendor, commercial upsell into Pro/Cloud. Assume community/issue-tracker support for the OSS tier and do not make it a production dependency — it isn't one.
• Procurement: if Pro or Cloud becomes desirable, that's a new commercial conversation; do not let the in-terminal hints drive an unplanned purchase. Note the hints are suppressed in CI, so they won't appear in build logs.

Scaling

• Scan time grows with codebase size and is per-repo per-run. Put it in its own job, run it in parallel with tests, and cache Composer installs. Do not serialize it in front of the test suite.
• Alert fatigue is the real scaling limit, not compute. At 50+ repos, unreviewed SARIF becomes background noise. Two controls: a committed baseline per repo, and a periodic sweep job that reports a portfolio-level view ("N repos on Laravel versions leaving security support within 180 days") — which is the artefact that actually drives upgrade planning.
• The scheduled production-profile sweep scales better than per-PR enforcement for the support checks: one weekly run per repo, one aggregated dashboard, zero PR-path friction.

Failure modes

Ramp-up

• Engineering time: roughly 1–2 days for the pilot and conventions doc, then ~30 minutes per repo for baseline and enforce. The scheduled sweep is a half-day setup.
• Learning curve: shallow for developers (one command, one failure message to interpret); moderate for the platform owner (profile semantics, fail-on gating, SARIF/permissions behaviour).
• Enablement needed: a short README section per repo, the "support window failure" runbook, and one internal note explaining that CI mode intentionally excludes the support checks so the team doesn't think enforcement is broken.
• Adoption signals to track: number of repos with a committed baseline, number of enforced required checks, weekly count of repos within the 180-day window, and — the honest one — number of repos where the check was disabled after enforcement.

Recommendation: adopt, but as a pinned dev dependency with a scheduled production-profile sweep and a SHA-pinned Action, not as an unpinned PR-blocking gate. The value in 3.2.0 is the upgrade-readiness signal and the SARIF/code-scanning bridge; the risk is a behaviour-changing minor and a floating Action tag, both of which are cheap to neutralise with pinning and a baseline before enforcement.