Agent Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for PHP-upgrade planning. The package now supplies the inventory layer of a PHP upgrade forecast — first-party app/ code and private (non-packagist) Composer packages — rather than making you build custom scanners or commission a consultancy audit. The decision it informs is whether to adopt an off-the-shelf agent + dashboard instead of internal tooling.
• Roadmap sequencing for a PHP version migration. File counts, byte sizes, and per-package fingerprints give a defensible effort proxy: how much first-party code and how many private dependencies must be validated before a PHP 8.x → 8.4/9 upgrade. Use it to decide whether the upgrade is a single sprint or a multi-quarter program, and to order packages by migration risk.
• Scope and staffing estimates. Per-package file counts and sizes turn "we have some private packages" into a rough audit surface, which is the input to staffing an upgrade workstream and to negotiating vendor timelines for private dependencies.
• Distro-patched PHP builds are now reported as their own signal. As of v1.21.0 the agent reports what a distribution's build adds to the PHP version (e.g. Ubuntu's -1ubuntu2.20) separately from the base version. This matters because distro maintainers routinely backport security fixes without bumping the version number. The decision it informs: whether a given host is genuinely running an unpatched PHP or a distro-patched one, which changes the priority of "patch now" versus "plan the upgrade" in your roadmap.
• Vulnerability triage severity is now explicit, not implied. For distro-built PHP the dashboard emits a hint rather than a warning on PHP vulnerabilities. The PM decision is how to route these: hints belong in the upgrade backlog, warnings belong in the incident/security queue. Do not let a hint get escalated as a breach, and do not let a warning get filed as "we'll get to it in the migration."
• Security and compliance posture as a gating decision. Default behaviour is metadata-only (paths, sizes, mtime-based fingerprints); no file content leaves the server unless STACKMONITOR_AGENT_FILE_CONTENTS=true. That distinction is what lets a security review approve adoption in regulated environments, and it is a decision the PM should own rather than delegate.
• Opt-in content retrieval as a product trade-off, not a default. ZIP retrieval is capped (PHP files only, within the package folder, ≤5,000 files, ≤8 MB) and requires the PHP zip extension. The decision is whether the marginal accuracy of remote content analysis is worth a new egress path and a new extension dependency — for most teams, defaults stay off until a specific forecast gap appears.
• Incremental re-report economics. Fingerprints over path, size and date enable the dashboard to detect change without re-transferring code. This supports a "cheap, recurring telemetry" model rather than "one-off audit" — relevant if you want upgrade readiness tracked continuously through the migration, not sampled once.
• Release ordering as a deployment-plan input. The dashboard must be deployed before the agent for php_code.contents to be understood. This is a coordination cost to bake into the rollout plan, not a blocker. The same discipline applies to the v1.21.0 distro-build field: it is additive metadata, so roll the dashboard first if you want the richer version string and the hint/warning split reflected immediately.
• Upgrade path is low-risk. v1.18.0 → v1.21.0 is additive: a new reported field plus a severity refinement. No breaking changes, no configuration migration, no new extension dependency. This should not be a roadmap line item — schedule it as routine maintenance.

Adoption considerations surfaced by this release: reports read within 2 seconds per run, cached 10 minutes in the app's cache; a package that misses the window is deferred to a later report with a 20-second budget of its own. Combined with the 5,000-file cap per package and no following of symlinked folders inside packages, this produces eventually-complete, bounded inventories — the PM should treat early reports as partial for large monorepos and avoid publishing forecasts from the first run.

When to Consider This Package

Consider it when:

• You run a Laravel application on PHP 8.x with a non-trivial app/ directory and private or forked Composer packages that packagist-based scanners cannot see — precisely the blind spot this release closes.
• A PHP upgrade is on the roadmap within the next two to four quarters and you need an evidence-based sizing of the migration surface rather than an estimate from memory.
• Your PHP comes from a distribution package (Ubuntu, Debian, RHEL or similar) rather than being compiled or sourced from an upstream tarball — the v1.21.0 build-suffix reporting is specifically there to stop distro backports from being read as unpatched versions.
• Security policy permits outbound metadata about your codebase (paths, sizes, modification dates) but forbids source exfiltration — the default mode is designed for exactly this; content transfer is a separate, explicit opt-in.
• You already operate (or are willing to operate) the companion dashboard, and can sequence a dashboard-first deployment.
• You want recurring, low-cost change detection through a migration rather than a single point-in-time audit.

Look elsewhere or defer when:

• You need semantic or AST-level static analysis — actual incompatible-API detection, deprecation call-site enumeration, or dependency-graph resolution. This release is an inventory and fingerprinting capability; it tells you how much code there is, not what in it will break.
• You want a real vulnerability scanner. Even with the improved distro-build awareness, this is a version-string signal that distinguishes hints from warnings — not a CVE feed, not a patch-status oracle, and not a substitute for your existing dependency/OS scanning.
• Your codebase exceeds the bounds: more than 5,000 PHP files in a single package, packages over 8 MB of PHP source if you enable content retrieval, or trees where the 2s/20s read budgets will leave packages perpetually deferred. Very large monorepos will get partial coverage per report cycle.
• Symlinked or vendored-outside-the-package directories are load-bearing in your layout — linked folders inside packages are explicitly not followed, so that code is invisible.
• Policy forbids any agent-side codebase scanning, even metadata-only and cache-local.
• You cannot yet deploy the matching dashboard version; the php_code.contents field is ignored until the dashboard knows it, so the feature is inert until then.
• You need cryptographic integrity guarantees. The fingerprint hashes path, size and date — it is a change-detection heuristic, not a content hash; treat it as "did this likely change," not "is this provably identical."

How to Pitch It (Stakeholders)

For executives: This release closes the last blind spot in our PHP upgrade forecast. Until now the tooling could only reason about public open-source dependencies; the code we actually own and the private packages we maintain were invisible — which is where most upgrade risk and most engineering effort actually live. We now get a sized inventory of first-party and private-package PHP code, refreshed on a short cycle, without any source code leaving our servers. The latest version additionally tells us the exact build of PHP each host runs, including distribution patches, so we stop conflating "old version number" with "unpatched" — distro maintainers backport security fixes without renaming the version. Practically: it converts "the PHP upgrade will take a while" into a scoped, defensible estimate we can put in front of a steering committee, and it does so continuously so the estimate stays honest as the work proceeds. The upgrade from our current version is additive and needs no engineering project of its own.

For engineering: Integration is configuration, not code. The agent generates the per-package PHP inventory locally, caches it for 10 minutes, and fingerprints each file by path, size and date so unchanged code isn't re-processed. Reads are bounded at 2 seconds per report with a 20-second catch-up budget for packages that miss their slot, and each package is capped at 5,000 files, so the agent cannot become a latency source in your app. Optional source retrieval is off by default, requires the PHP zip extension, and is constrained to *.php files inside the package folder. v1.21.0 parses the distribution build suffix (-1ubuntu2.20) alongside the base version and ships it as a separate field — no configuration, no new dependency, and no change to the existing report contract beyond an added key. One coordination note: the dashboard must ship before the agent, or you'll be sending a field nothing consumes yet.

For security and compliance: The default is metadata-only — file paths, byte sizes, and a fingerprint derived from path, size and modification date. No file content leaves the host in this mode. Content transfer is a distinct, explicitly-flagged capability (STACKMONITOR_AGENT_FILE_CONTENTS), scoped to one package at a time, filtered to PHP files, contained within the package's own directory, and hard-capped at 5,000 files and 8 MB per archive. Both the metadata and content paths are auditable and reversible via configuration, which is why the recommendation is to adopt with content retrieval disabled and revisit only if a specific forecast gap requires it. On the new build-suffix reporting: this is version metadata the agent already reads from the local runtime, it adds no new egress, and it materially reduces false positives — distro-patched PHP is reported as a hint rather than a warning, so security triage is not paged for builds that already carry backported fixes.