Skip to content

feat: add system.v3, describing the Craft install and not just its disk - #13

Merged
Coysh merged 1 commit into
mainfrom
feat/system-v3
Aug 17, 2026
Merged

Coysh merged 1 commit into
mainfrom
feat/system-v3

Conversation

@Coysh

@Coysh Coysh commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

The runtime report has always described the disk a site sits on — volume sizes, free space, PHP limits — and said nothing about the Craft install doing the sitting. system.v3 adds four sections a site can answer about itself and nothing outside it can observe.

What it adds

Section Fields
craft deprecation_count, session_rows, security_key_set, cp_trigger_default
database size_bytes
paths storage, cpresources, config_project
php missing_extensions, image_driver

The database size is the one worth calling out. Backups are the reason this package exists, and until now the report described every asset volume and the disk underneath them while saying nothing about the size of the thing being backed up — which is the figure that decides whether a backup finishes.

Compatibility

system.v1 and system.v2 are untouched, byte for byte. A connector sending either keeps working against any platform that accepted it before, and a platform that has not been upgraded keeps receiving exactly what it received: the connector picks the newest version both sides know, so neither has to move first.

What was left out, and why

Every addition has a more useful shape that this schema refuses, and the tests are what keep refusing it.

  • A deprecation warning without its message is harder to act on — but the message names a template, a file and a line, and those are the site's own code. The count says whether there is a problem; finding it is done on the site, where the code already is.
  • A database size without a table breakdown is harder to act on — but a per-table row count describes the shape of somebody's content, and a table name often describes their business.
  • cp_trigger_default is a boolean, and there is no field for the trigger itself. A site that moved its control panel moved it somewhere it would rather not have written down; reporting the new address in somebody else's dashboard would undo the change being reported.
  • security_key_set is presence, never the key.
  • missing_extensions is a closed enum of Craft's published requirements, so it cannot become the loaded-extension inventory that php.extensions is reduced to a count to avoid. paths is a fixed set of Craft's own directory names for the same reason a volume sends a handle rather than a path — a free-form label is a filesystem path with extra steps.
  • image_driver is which library, never which version. The version belongs to the host.
  • Response compression is not here at all. It is decided at the edge, so a site behind a CDN would report its origin's answer rather than the one a visitor receives. It is observed from outside instead.

Checks

vendor/bin/pest — 400 passed, 2848 assertions. vendor/bin/phpstan analyse — no errors. The new fixtures cover both directions: a realistic v3 report, and one carrying the identifying half of every fact v3 added, asserted to be refused without the rejected values ever appearing in the error text.

CHANGELOG.md and the version in composer.json and Protocol::VERSION move with the change, in this commit.

The runtime report has always described the disk a site sits on - volume
sizes, free space, PHP limits - and said nothing about the Craft install
doing the sitting. system.v3 adds four sections a site can answer about
itself and nothing outside it can observe: deprecation and session counts,
whether a security key is set and whether the control panel is still at the
default trigger; the database size; whether Craft's writable directories are
writable; and which required PHP extensions are absent, plus which imaging
library is available.

The database size is the one worth calling out. Backups are the reason this
package exists, and until now the report described every asset volume and the
disk underneath them while saying nothing about the size of the thing being
backed up - which is the figure that decides whether a backup finishes.

v1 and v2 are untouched, so every existing combination of connector and
platform keeps working and neither side has to be upgraded first.

Each addition has a more useful shape that is deliberately refused, and the
tests are what keep refusing it. A deprecation warning is easier to act on
with its message, but the message names the site's own templates; a database
size is easier to act on with a table breakdown, but table names describe
somebody's business; a moved control panel is easier to find if you know
where it moved to, which is exactly what moving it was meant to prevent. So
this sends the count, the total and the boolean. missing_extensions is a
closed enum of Craft's published requirements rather than free strings, so it
cannot become the loaded-extension inventory that php.extensions is reduced
to a count to avoid, and paths is a fixed set of Craft's own directory names
because a free-form label is a filesystem path with extra steps.

Response compression is not here. It is decided at the edge, so a site behind
a CDN would report its origin's answer rather than the one a visitor gets.
@Coysh
Coysh merged commit 6322d18 into main Aug 17, 2026
3 checks passed
@Coysh
Coysh deleted the feat/system-v3 branch August 17, 2026 17:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant