Statamic A11Y Report Laravel Package

Technical Evaluation

Architecture fit. This is a Statamic addon (Laravel/PHP) that adds an accessibility scanning and reporting layer: an a11y:report command, a control-panel button, a dashboard widget, and a worksheet/report document. It fits naturally into a Statamic site's existing content and addon model — config publishing via vendor:publish, console commands via please, and site-scoped data aligned with Statamic's multisite concept. The release is a patch that hardens a core data-model assumption: scans have a scope (['*'] or a named site), and reporting surfaces must resolve that scope identically. That is the right architectural direction for a multisite-capable addon, but it also reveals that scan identity was previously implicit and inconsistently resolved across three consumers (CLI, CP button, widget). Any TPM evaluating this package should treat "scan-to-site attribution" as a first-class data contract, not an implementation detail.

Integration feasibility. Low-to-moderate. The package installs as a normal Composer dependency and requires a post-install step (php please a11y:report:install) that this release makes more important than before, because it backfills site names onto existing scan/report records on single-site installs. For a fresh install, the README now correctly documents the config publish tag, which removes a common first-run failure. For an existing install, the upgrade is composer update followed by the install command — two steps, both standard. The main feasibility question is not "can we install it" but "do we have a controlled path to run a data-mutating command against production content storage," since Statamic stores this data on disk (flat files/YAML), and the migration rewrites rows based on inferred evidence (the pages the scan read). That inference is conservative — scans that read a page of a site the install no longer has are left alone — which is the right behavior, but it means the backfill is not guaranteed to be total, and some legacy rows may remain unnamed.

Technical risk. Overall: low, with two specific watch items.

• Data migration risk (moderate). The install command mutates existing scan/report records. It is described as evidence-based and non-destructive for orphaned sites, but it is still an in-place rewrite of reporting history. This is the highest-risk element of the release and should be staged with a backup of the relevant storage directory.
• Reporting semantics change (low-to-moderate). The unified lookup is now: "a scan named for the site, or a scan of every site, whichever is newer — never another site's alone." That is a correctness fix, but it changes which scan a widget or report may resolve to on multisite installs where both a site-scoped and an all-sites scan exist. Expect at least one stakeholder to notice a "different" last-scan reference after upgrade, even though it is more correct. The release explicitly claims continuity for single-site installs ("the 'against the last scan' line and the site-scoped widget stay continuous"), which is reassuring but should be verified in staging.
• No breaking changes, no deprecations, no new dependencies. The remainder of the release is documentation hygiene: config publish instructions, a corrected composer show support command, and consistent reading-level band spelling ("Grade 9–10"). These are low-risk but worth noting because they reduce support-ticket volume rather than change behavior.

Key questions.

1. Which Statamic major versions and PHP versions does this release support, and does the install command behave identically across them?
2. Is a11y:report:install idempotent — safe to run twice, and safe to run on an install that has already been migrated?
3. On multisite installs, what exactly is the resolution order when a site-scoped scan and an all-sites scan share a timestamp or are within the same refresh window?
4. Does the backfill require write access to the Statamic content/storage path at deploy time, and does it run cleanly in a read-only or containerized filesystem?
5. What is the expected behavior for a scan whose scope names a site that has since been removed — is it simply excluded from all lookups, or shown anywhere as historical?
6. Are there tests covering the three consumers (command, CP button, widget) resolving to the same scan? This release is precisely a divergence bug, so shared-lookup coverage is the thing to confirm.

Integration Approach

Stack fit. The package assumes a Laravel + Statamic application with the control panel enabled and, for scheduled scanning, a working scheduler/queue. It does not introduce a new runtime or datastore; it reads and writes Statamic-managed content. That makes it a low-friction fit for teams already standardized on Statamic, and a poor fit for anyone trying to run it outside that stack.

Migration path. Treat this as a two-phase deploy rather than a single composer update.

1. Pre-flight: confirm the current package version, snapshot the storage path that holds scan/report records, and identify whether the install is single-site or multisite. The migration's behavior differs between the two, so this determines the expected outcome.
2. Staging upgrade: composer update to v1.2.2, run php please a11y:report:install, then verify: (a) existing single-site scans are now named for the site, (b) the CLI --site=default report no longer reports "no complete scan," (c) the dashboard widget shows a completed scan consistent with the open-issue count, and (d) on multisite, the CP button resolves to the correct site's scan and never another site's.
3. Production upgrade: same sequence in a maintenance window, with the storage snapshot retained until the post-upgrade verification passes.
4. Config: if the config file was never published, publish it now with php artisan vendor:publish --tag=statamic-a11y-report-config and commit it, so environment-specific settings are not silently defaulted.

Compatibility. The release is explicitly non-breaking, and the changed items are documentation-level. The compatibility surface to check is therefore environmental, not API-level: Statamic version, PHP version, and whether the deployment pipeline can execute a Statamic console command against production storage. The release notes also correct the composer show support command, which previously named two packages in one invocation — a small but real signal that the package's own support instructions were not being exercised; worth noting when judging documentation quality.

Sequencing. Upgrade the package first, then run the install command, then republish/verify config, then validate the three reporting surfaces in this order: CLI → dashboard widget → worksheet/report document. Validating CLI first isolates data-layer problems from control-panel caching or rendering problems. Do not schedule a new scan between the Composer update and the install command; run the backfill first so new scans are written under the corrected attribution model.

Operational Impact

Maintenance. Low ongoing burden. This is a patch release with no new dependencies, no schema changes in the traditional sense, and no deprecations. The maintenance cost is concentrated in the one-time backfill and in keeping the published config file under version control. The documentation fixes reduce the steady-state support load: fresh installs no longer fail on a missing config file, and the corrected composer show line means support requests can actually be diagnosed with the command the README recommends.

Support. The support surface is narrow — install, config publishing, scan scheduling, and interpreting reports. The riskiest support scenario is a user on a multisite install who notices a report now references a different "last scan" than before. That is a correctness improvement, not a regression, but it needs a prepared explanation: the old behavior could resolve to another site's scan, and the new shared lookup cannot. For single-site installs, the story is simpler and the release explicitly preserves continuity, so support should frame the upgrade as "your existing scans are being labeled correctly," not "your data is changing."

Scaling. The package scales with the number of sites and pages scanned, not with request volume. The multisite fix is the scaling-relevant change: a shared lookup across command, button, and widget removes a class of cross-site ambiguity that would otherwise get worse as site count grows. Two scaling considerations remain: scan storage grows as flat files under Statamic's content model, and the "whichever is newer" resolution rule means report freshness depends on scan cadence per site — teams with uneven scheduling across sites should expect the all-sites scan to dominate the "last scan" reference for less-frequently scanned sites.

Failure modes.

• Partial backfill. Scans that reference a page from a removed site are intentionally left unnamed. They will not appear in site-scoped lookups, which is correct but can look like missing history. Document this before upgrade.
• Re-running the install command. If it is not idempotent, a repeated deploy step could re-process already-migrated rows. Confirm idempotency in staging.
• Read-only deploy filesystems. The backfill writes to content storage. Immutable-container or read-only deployments will fail or silently skip; the command needs to run in an environment with write access.
• Timestamp ties on multisite. If a site-scoped scan and an all-sites scan are effectively simultaneous, the "whichever is newer" rule needs a deterministic tiebreak; otherwise the same symptom (widget and CLI disagreeing) can reappear intermittently.
• Stale config. A never-published config file means defaults are in force and are invisible to operators. Publishing it is now documented, but existing installs may still be running unpublished.

Ramp-up. Minimal for a team already on Statamic. A developer can install, publish config, run the backfill, and validate the three surfaces in well under a day. The learning curve is not in the package but in the domain: understanding what a "scan scope" means, why a scan of every site is not the same as a site's scan, and why a report must never claim less than it covered. That conceptual point is the actual subject of this release, and it is worth a short internal write-up so the next person reading a report does not have to rediscover it.