Guardrails / Collectors

PHP project

The Composer project in the project directory: the package it declares, the PHP version and extensions it asks for, the packages it requires and which of them are pinned, and whether the lock file is committed.

Facts key	php
Version	v1
Script	php.py
Timeout	30 seconds

Inputs

Input	Description	Default	Environment
projectDir	Directory holding the project, relative to the directory the CLI runs in.	.	GUARDRAIL_INPUT_PROJECTDIR

A guardrail that declares an input of the same name passes it through, so the guardrail's configuration in buildnote.json is what decides these values.

A guardrail asks for these facts by name, and reads them back the same way:

{
  "collect": ["php"]
}

php = guardrail.facts("php")

Facts

The document php collects. A path carrying [] is an entry of the list before it, and one carrying [path] is a key of the object before it.

Fact	Meaning
directory	The projectDir input, as the guardrail configured it.
exists	Whether that directory is there. Nothing else is collected when it is not.
manifest	Path of the primary manifest, relative to projectDir, always composer.json.
sources	Every manifest that was read and understood. A manifest the reader could not handle is in unparsed instead.
declared	The PHP version the project asks for, or null when it asks for none. config.platform.php wins over require.php, because it is the version Composer resolves against.
declared.version	Constraint exactly as written, such as ^8.2 or 8.2.18.
declared.source	File declaring it, relative to projectDir.
declared.pinned	Whether the constraint names one exact version rather than a range. A ^, a ~, a >=, a * or a | is not pinned.
type	The type the manifest declares, such as library or project, or null when it declares none and library is implied.
projects	The one package the manifest declares. Composer has no workspaces, so this is always a single entry.
projects[].path	Directory of the package, relative to projectDir, always ..
projects[].manifest	That package's composer.json, relative to projectDir.
projects[].name	Name the manifest declares, such as acme/widget, or null when it declares none.
dependencies	What the manifest requires, split by whether the project asks for it itself.
dependencies.direct	Every package require and require-dev name, the php constraint and the ext- and lib- platform requirements left out because they are not packages.
dependencies.direct[].name	Package name, such as symfony/console.
dependencies.direct[].version	Constraint exactly as written, such as ^7.0.
dependencies.direct[].scopes	Which of require and require-dev declare it.
dependencies.direct[].source	Manifest declaring it, relative to projectDir.
dependencies.direct[].pinned	Whether the constraint names one exact version. A ^, a ~, a range, a *, a dev- branch or a @ stability flag is not pinned.
dependencies.transitive	Always empty. What composer.lock resolves is not read: lockfiles says whether one is committed.
platform	Every ext- and lib- requirement the manifest names, which is what the runtime has to carry rather than what Composer installs.
platform[].name	Requirement name, such as ext-json.
platform[].version	Constraint exactly as written, such as *.
scripts	Names of the scripts the manifest declares. Names only, because a script body can carry a token.
lockfiles	composer.lock when it is committed, relative to projectDir. An application without one resolves differently on every install.
unparsed	Every manifest the reader could not handle, so a guardrail can tell a project that declares nothing from one nobody could read.
unparsed[].path	Path of that manifest, relative to projectDir.
unparsed[].reason	What stopped the reader.

A collector that cannot finish prints what it had along with an incomplete key saying why, so the facts below the point it stopped are absent. A check that cares reads incomplete before the rest.

Example facts

The example facts collected by php collector:

{
  "directory": ".",
  "exists": true,
  "manifest": "composer.json",
  "sources": [
    "composer.json"
  ],
  "declared": {
    "version": "^8.2",
    "source": "composer.json",
    "pinned": false
  },
  "type": "project",
  "projects": [
    {
      "path": ".",
      "manifest": "composer.json",
      "name": "acme/widget"
    }
  ],
  "dependencies": {
    "direct": [
      {
        "name": "symfony/console",
        "version": "^7.0",
        "scopes": [
          "require"
        ],
        "source": "composer.json",
        "pinned": false
      },
      {
        "name": "monolog/monolog",
        "version": "3.6.0",
        "scopes": [
          "require"
        ],
        "source": "composer.json",
        "pinned": true
      },
      {
        "name": "phpunit/phpunit",
        "version": "^11.1",
        "scopes": [
          "require-dev"
        ],
        "source": "composer.json",
        "pinned": false
      }
    ],
    "transitive": []
  },
  "platform": [
    {
      "name": "ext-json",
      "version": "*"
    }
  ],
  "scripts": [
    "lint",
    "test"
  ],
  "lockfiles": [
    "composer.lock"
  ],
  "unparsed": []
}

Collected for

Guardrail	Category	Inputs
php/dependencies-constrained	php	projectDir
php/lockfile-committed	php	projectDir
php/version-declared	php	projectDir

All collectors