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.0
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().

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

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.

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.

adachsoft / project-validator

Package info

Security

Statistics