PHP Project Guardrails

✓ Policy Beta Devex Build And Ci

Enforce PHP-specific project standards including Composer lockfile presence, static analysis and code style tool configuration, and PHP version requirements.

Add php to your lunar-config.yml:

uses: github://earthly/lunar-lib/policies/php@v1.0.0

Get Started View on GitHub

Included Guardrails

This policy includes 8 guardrails that enforce standards for your devex build and ci.

Guardrail

`composer-json-exists`

Ensures the project has a composer.json file for dependency management. Reads from .lang.php.composer.json_exists.

composer composer.json project structure

View Guardrail

Guardrail

`composer-lock-exists`

Ensures the project has a composer.lock file for reproducible builds. Reads from .lang.php.composer.lock_exists.

composer.lock dependencies reproducibility

View Guardrail

Guardrail

`phpunit-configured`

Ensures a test framework (PHPUnit) is configured for the project. Testing is essential for maintaining code quality.

phpunit testing test framework

View Guardrail

Guardrail

`static-analysis-configured`

Ensures a static analysis tool (PHPStan or Psalm) is configured. Static analysis catches bugs and type errors before runtime.

phpstan psalm static analysis type safety

View Guardrail

Guardrail

`code-style-configured`

Ensures a code style tool (PHP-CS-Fixer or PHP_CodeSniffer) is configured. Consistent code style reduces cognitive load and merge conflicts.

php-cs-fixer phpcs code style formatting

View Guardrail

Guardrail

`min-version`

Ensures the project requires at least the minimum PHP version. Helps maintain security and compatibility standards.

php version compatibility security

View Guardrail

Guardrail

`min-version-cicd`

Ensures the PHP runtime version observed in CI meets the minimum required version. Reads from .lang.php.cicd.cmds version entries.

php version ci/cd compatibility security

View Guardrail

Guardrail

`min-composer-version`

Ensures CI pipelines use at least the minimum Composer version. Older Composer versions may lack security fixes and modern dependency resolution features.

composer version dependency management security

View Guardrail

How Guardrails Fit into Lunar

Lunar guardrails define your engineering standards as code. They evaluate data collected by integrations and produce pass/fail checks with actionable feedback.

Policies support gradual enforcement—from silent scoring to blocking PRs or deployments—letting you roll out standards at your own pace without disrupting existing workflows.

Learn How Lunar Works →

↓ Integrations Gather Data

Collectors extract metadata from code, CI pipelines, tool outputs, and scans

{ } Centralized as JSON

All data merged into each component's unified metadata document

✓ Guardrails Enforce Standards This Policy

Real-time feedback in PRs and AI workflows

Required Integrations

This policy evaluates data gathered by one or more of the following integration(s). Make sure to enable them in your lunar-config.yml.

Collector LanguagesBuild Required

PHP Collector

Provides PHP project metadata

Configuration

Configure this policy in your lunar-config.yml.

Inputs

Input	Required	Default	Description
`min_version`	Optional	`8.1`	Minimum required PHP version (e.g., "8.1", "8.2")
`min_version_cicd`	Optional	`8.1`	Minimum required PHP CI runtime version (e.g., "8.1", "8.2")
`min_composer_version`	Optional	`2.6`	Minimum required Composer version (e.g., "2.6", "2.7")

Documentation

View on GitHub

PHP Project Guardrails

Enforce PHP-specific project standards including Composer configuration, tool setup, and PHP version requirements.

Overview

This policy validates PHP projects against best practices for dependency management and project structure. It ensures projects have proper composer.json and composer.lock files, use a minimum PHP version, and have testing, static analysis, and code style tools configured.

Policies

This plugin provides the following policies (use include to select a subset):

Policy	Description	Failure Meaning
`composer-json-exists`	Validates composer.json exists	Project lacks Composer dependency management
`composer-lock-exists`	Validates composer.lock exists	Missing lockfile for reproducible builds
`phpunit-configured`	Ensures PHPUnit is configured	No test framework detected
`static-analysis-configured`	Ensures PHPStan or Psalm is configured	No static analysis tool detected
`code-style-configured`	Ensures PHP-CS-Fixer or PHPCS is configured	No code style tool detected
`min-version`	Ensures minimum PHP version in composer.json	PHP version too old
`min-version-cicd`	Ensures minimum PHP runtime version in CI	CI PHP version too old
`min-composer-version`	Ensures minimum Composer version in CI	Composer version too old

Required Data

This policy reads from the following Component JSON paths:

Path	Type	Provided By
`.lang.php`	object	`php` collector
`.lang.php.version`	string	`php` collector
`.lang.php.phpunit_configured`	boolean	`php` collector
`.lang.php.static_analysis_configured`	boolean	`php` collector
`.lang.php.code_style_configured`	boolean	`php` collector
`.lang.php.composer.json_exists`	boolean	`php` collector
`.lang.php.composer.lock_exists`	boolean	`php` collector
`.lang.php.cicd`	object	`php` collector
`.lang.php.composer.cicd`	object	`php` collector

Installation

Add to your lunar-config.yml:

policies:
  - uses: github://earthly/lunar-lib/policies/php@v1.0.0
    on: [php]  # Or use tags like ["domain:backend"]
    enforcement: report-pr
    # include: [composer-json-exists, composer-lock-exists]  # Only run specific checks
    with:
      min_version: "8.1"  # Minimum required PHP version (default: "8.1")
      min_version_cicd: "8.1"  # Minimum required PHP CI runtime version (default: "8.1")
      min_composer_version: "2.6"  # Minimum required Composer version (default: "2.6")

Examples

Passing Example

{
  "lang": {
    "php": {
      "version": "^8.2",
      "phpunit_configured": true,
      "static_analysis_configured": true,
      "code_style_configured": true,
      "composer": {
        "json_exists": true,
        "lock_exists": true
      }
    }
  }
}

Failing Example

{
  "lang": {
    "php": {
      "version": "^7.4",
      "phpunit_configured": false,
      "static_analysis_configured": false,
      "code_style_configured": false,
      "composer": {
        "json_exists": true,
        "lock_exists": false
      }
    }
  }
}

Failure messages:

"composer.lock not found. Run 'composer install' to generate a lockfile for reproducible builds."
"PHPUnit not configured. Add phpunit/phpunit to require-dev and create phpunit.xml."
"No static analysis tool configured. Add PHPStan or Psalm to your project."
"No code style tool configured. Add PHP-CS-Fixer or PHP_CodeSniffer to your project."
"PHP version 7.4 is below minimum 8.1. Update the PHP constraint in composer.json."
"PHP CI runtime version 8.0.30 is below minimum 8.1. Update the PHP version in your CI pipeline."
"Composer version 2.4.1 is below minimum 2.6. Update Composer in your CI pipeline."

Remediation

composer-json-exists

Run composer init to create a composer.json file
Add your project dependencies with composer require

composer-lock-exists

Run composer install to generate composer.lock
Commit the composer.lock file to version control

phpunit-configured

Run composer require --dev phpunit/phpunit
Create a phpunit.xml or phpunit.xml.dist configuration file
Add a test script to composer.json: "scripts": {"test": "phpunit"}

static-analysis-configured

Choose PHPStan or Psalm:
- PHPStan: composer require --dev phpstan/phpstan and create phpstan.neon
- Psalm: composer require --dev vimeo/psalm and run vendor/bin/psalm --init
Add to your CI pipeline for automated checking

code-style-configured

Choose PHP-CS-Fixer or PHP_CodeSniffer:
- PHP-CS-Fixer: composer require --dev friendsofphp/php-cs-fixer and create .php-cs-fixer.php
- PHPCS: composer require --dev squizlabs/php_codesniffer and create phpcs.xml
Add to your CI pipeline for automated checking

min-version

Update the require.php constraint in composer.json: "php": ">=8.1"
Run composer update to verify compatibility
Test your code with the new PHP version

min-version-cicd

Update the PHP version in your CI pipeline (e.g., Docker base image, GitHub Actions php-version)
Verify your application works with the new PHP version
Ensure composer.json's require.php constraint is compatible

min-composer-version

Update Composer in your CI pipeline: composer self-update
Pin a minimum version in your CI config (e.g., composer self-update --2.6)
Consider using the official Composer Docker image with a specific version tag

Open Source

This policy is open source and available on GitHub. Contribute improvements, report issues, or fork it for your own use.

View Repository

Common Use Cases

Explore how individual guardrails work with specific integrations.

Composer Json Exists + PHP Collector Ensures the project has a composer.json file for dependency management. Reads...

→

Composer Lock Exists + PHP Collector Ensures the project has a composer.lock file for reproducible builds. Reads from...

→

Phpunit Configured + PHP Collector Ensures a test framework (PHPUnit) is configured for the project. Testing is...

→

Static Analysis Configured + PHP Collector Ensures a static analysis tool (PHPStan or Psalm) is configured. Static analysis...

→

Code Style Configured + PHP Collector Ensures a code style tool (PHP-CS-Fixer or PHP_CodeSniffer) is...

→

Min Version + PHP Collector Ensures the project requires at least the minimum PHP version. Helps maintain...

→

Min Version Cicd + PHP Collector Ensures the PHP runtime version observed in CI meets the minimum...

→

Min Composer Version + PHP Collector Ensures CI pipelines use at least the minimum Composer version. Older Composer...

→

Ready to Automate Your Standards?

See how Lunar can turn your engineering wiki, compliance docs, or postmortem action items into automated guardrails with our 100+ built-in guardrails.

Works with any process

Infrastructure conventions

Post-mortem action items

Security & compliance policies

Testing & quality requirements

Automate Now

Turn any process doc into guardrails

Book a Demo