Search by

adachsoft / project-validator

Arkadiusz Adach

Configurable PHP validators for project repositories

Package info

gitlab.com/a.adach/project-validator

Issues

pkg:composer/adachsoft/project-validator

Statistics

Installs: 11

Dependents: 1

Suggesters: 0

Stars: 0

v0.3.0 2026-11-12 16:20 UTC

This package is auto-updated.

Last update: 2026-11-12 15:23:23 UTC


README

adachsoft/project-validator is a PHP 8.3+ library for running configurable validators against a project repository. Validators are registered as small, independent services and are executed through named validation scopes or by explicitly selected validator codes.

What the library provides

  • A ProjectValidatorInterface extension point for custom validators.
  • Immutable value objects and DTOs for validator codes, scopes, options, violations, and results.
  • Validation scopes that group validators with scope-specific options.
  • Sequential execution with support checks, execution reports, and blocker short-circuiting.
  • Aggregated validation results containing the validity flag, reports, violations, and duration.
  • A command-executor based validator implementation for project CLI commands.

Requirements

  • PHP ^8.3
  • adachsoft/command-executor-lib ^2.3
  • adachsoft/collection ^3.0

Installation

composer require adachsoft/project-validator

Core concepts

Validator

A validator implements AdachSoft\\ProjectValidator\\SPI\\ProjectValidatorInterface and must provide:

  • a unique ValidatorCodeVo returned by getCode();
  • a description returned by getDescription();
  • an isSupported() check;
  • a validate() method returning a ViolationCollection.

Validation context

The validator receives a ValidationContextInterface. It exposes the absolute repository path and the selected validation scope:

$repositoryPath = $validationContext->getRepositoryPath();
$scope = $validationContext->getScope();

Scope

A ValidationScopeDefinitionDto groups ScopeValidatorConfigDto objects under a ValidationScopeVo. Each configuration contains a validator code and a ValidatorOptionsDto instance.

A validation request can select:

  • a registered scope with ProjectValidationRequestDto(new ValidationScopeVo('ci'));
  • explicit validator codes with ProjectValidationRequestDto(null, $validatorCodes);
  • all registered validators with ProjectValidationRequestDto().

Generic CLI validator

GenericCliCommandValidator executes a configured command through adachsoft/command-executor-lib. Its optional constructor arguments are backward-compatible and can be appended after the existing arguments:

  • timeoutSeconds: default process timeout in seconds; null disables the timeout;
  • outputTailLength: maximum number of characters retained separately from STDOUT and STDERR when a command fails (default 4000).

The timeout_seconds option in ValidatorOptionsDto overrides the constructor timeout for a particular validation scope. The output_tail_length option can similarly override the output-tail length. The env option adds environment variables to the process while preserving the current process environment.

For a failed command, the violation message contains the last configured number of characters from each output stream. A timeout is returned as a violation with the <validator>_timeout code instead of propagating the executor exception. Timeout violations remain categorized as code problems.

The fix_hint option accepts a string or null. When a failed command has a non-null hint, its <validator>_failed violation is marked as fixable and exposes the hint as ViolationDto::$fixHint.

The environment_error_patterns option accepts a list of PCRE patterns checked against the complete STDOUT and STDERR streams. The environment_error_hint option accepts a string or null and provides guidance for detected environment errors. A matching pattern, or exit code 126 or 127, produces a <validator>_environment_error violation instead of <validator>_failed. Environment violations are not fixable; their optional hint is supplied by environment_error_hint.

Example

use AdachSoft\\ProjectValidator\\Validator\\GenericCliCommandValidator;

$validator = new GenericCliCommandValidator(
    $code,
    'Run static analysis',
    'vendor/bin/phpstan analyse',
    $commandExecutor,
    timeoutSeconds: 30.0,
    outputTailLength: 4000,
);

Building and configuring an instance

The package does not provide a container-specific bootstrapper. The following example shows the complete object graph for manual composition. In an application using a dependency injection container, register the same objects as services.

use AdachSoft\\ProjectValidator\\Collection\\ProjectValidatorCollection;
use AdachSoft\\ProjectValidator\\Collection\\ScopeValidatorConfigCollection;
use AdachSoft\\ProjectValidator\\Collection\\ValidationScopeDefinitionCollection;
use AdachSoft\\ProjectValidator\\Dto\\ProjectValidationConfigDto;
use AdachSoft\\ProjectValidator\\Dto\\ProjectValidationRequestDto;
use AdachSoft\\ProjectValidator\\Dto\\ScopeValidatorConfigDto;
use AdachSoft\\ProjectValidator\\Dto\\ValidationScopeDefinitionDto;
use AdachSoft\\ProjectValidator\\Dto\\ValidatorOptionsDto;
use AdachSoft\\ProjectValidator\\Facade\\ProjectValidationFacade;
use AdachSoft\\ProjectValidator\\Service\\ProjectValidationEngine;
use AdachSoft\\ProjectValidator\\Service\\ValidationScopeRegistry;
use AdachSoft\\ProjectValidator\\Vo\\ValidationScopeVo;

$validator = new MyCustomValidator();
$validators = new ProjectValidatorCollection([$validator]);

$scope = new ValidationScopeVo('ci');
$scopeDefinitions = new ValidationScopeDefinitionCollection([
    new ValidationScopeDefinitionDto(
        $scope,
        new ScopeValidatorConfigCollection([
            new ScopeValidatorConfigDto(
                $validator->getCode(),
                new ValidatorOptionsDto(['required_file' => 'composer.json']),
            ),
        ]),
        'Continuous integration validation',
    ),
]);

$config = new ProjectValidationConfigDto('/absolute/path/to/repository', $scopeDefinitions);
$registry = new ValidationScopeRegistry($scopeDefinitions);
$engine = new ProjectValidationEngine($validators);
$facade = new ProjectValidationFacade($config, $registry, $engine, $validators);

$result = $facade->validateProject(new ProjectValidationRequestDto($scope));

if (!$result->valid) {
    foreach ($result->violations as $violation) {
        echo $violation->message . PHP_EOL;
    }
}

ProjectValidationConfigDto validates that the repository path is an existing directory. Validator codes and scope names must use the formats accepted by ValidatorCodeVo and ValidationScopeVo.

For a complete custom validator and registration example, see docs/examples/custom-validator.md.

Validation result

Each ViolationDto exposes fixable (default false), fixHint (default null), and category (default ViolationCategoryEnum::CODE) in addition to its code, message, severity, and optional file location. Categories distinguish project-code problems (CODE) from environment or tool-configuration problems (ENVIRONMENT).

ProjectValidationResultDto exposes:

  • valid: true when no violations were returned;
  • scope: the executed scope, or null for ad-hoc validation;
  • reports: one execution report per configured validator;
  • violations: the aggregated violations;
  • totalDurationSeconds: total execution time.

A validator returning a BLOCKER violation stops the execution of subsequent validators in the current run. Unsupported validators are reported as skipped. Validator execution reports use PASSED, FAILED, ERROR, or SKIPPED; ERROR indicates that a validator found an environment or configuration problem. Such violations still make ProjectValidationResultDto::$valid false.

Development

Install development dependencies:

composer install

Run the test suite:

composer test

Run static analysis:

composer phpstan

Check coding standards:

composer cs-fixer

Run Rector in dry-run mode:

composer rector

License

This project is licensed under the MIT License.