Ambit

https://github.com/zoliszabo/php-ambit
Admin
Ambit is a PHP library and CLI that defines shared project file scopes and selects files from those...
Tokens:8,699
Snippets:65
Trust Score:6.1
Update:3 days ago
Show doc for...
Tokens:
Raw
### Example CLI validation output

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Example output from the `ambit validate` command. Exit status is `0` when there are no errors or warnings, `1` when there are errors (including runs that also have warnings), `2` for incorrect CLI arguments, and `3` for warnings only.

```text
Validating "ambit.yaml".
WARNING [filesystem] php.paths "modules/*/src" (resolved to "/project/modules/*/src"): This does not match any real path.
WARNING [filesystem] php.exclude "cache/" (resolved to "/project/cache/"): This does not match any real path.
0 error(s), 2 warning(s).
```

--------------------------------

### Run Ambit validation CLI commands

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Run validation from the command line after installing Ambit. The configuration file defaults to `ambit.yaml` in the current working directory. By default, filesystem checks cover every set; `--set=NAME` limits filesystem checks to that set. Only one of `--schema-only`, `--paths-only`, and `--exclusions-only` may be supplied.

```bash
vendor/bin/ambit validate
vendor/bin/ambit validate path/to/ambit.yaml --set=rector
vendor/bin/ambit validate --schema-only
vendor/bin/ambit validate --paths-only
vendor/bin/ambit validate --exclusions-only
```

--------------------------------

### Basic ambit.yaml configuration with php set

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Create an ambit.yaml in the project root. A single php set is enough; additional sets are optional. Paths and exclusions are additive, and relative paths are anchored to the directory containing the file.

```yaml
php:
    paths:
        - src
        - tests
    exclude:
        - '*/generated/*'
```

--------------------------------

### Select php set by default with Scope::fromProject

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Use Scope::fromProject to select the php set by default. Requires the Ambit\Scope class.

```php
use Ambit\Scope;

$php = Scope::fromProject(__DIR__); // Selects the php set by default.
```

--------------------------------

### FilesystemValidator::validate()

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Checks an existing or programmatically created Config against the filesystem. Returns a result object with issues, errors, and warnings.

```APIDOC
## [PHP] FilesystemValidator::validate()

### Description
Checks an existing or programmatically created Config against the filesystem. Returns a result object with issues, errors, and warnings.

### Method
PHP

### Endpoint
FilesystemValidator::validate()

### Parameters
#### Arguments
- **$config** (Config) - Required - The configuration object to validate.
- **$projectDir** (string) - Required - The project directory to check against.

### Response
#### Return Value
- **result** (object) - Contains issues, errors, and warnings. Use `issues()`, `errors()`, `warnings()`, and `isValid()` methods.

### Request Example
```php
use Ambit\Validation\FilesystemValidator;
use Ambit\YamlConfigLoader;

$config = (new YamlConfigLoader())->load(__DIR__ . '/ambit.yaml');
$result = (new FilesystemValidator())->validate($config, __DIR__);
```
```

--------------------------------

### Select named sets with Scope::fromProject

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Use Scope::fromProject with a set name to select a specific set. Requires the Ambit\Scope class.

```php
use Ambit\Scope;

$rector = Scope::fromProject(__DIR__, 'rector');
$lint = Scope::fromProject(__DIR__, 'lint');
```

--------------------------------

### YAML Language Server Schema Hint for ambit.yaml

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Add this comment as the first line of your project-root ambit.yaml to enable JSON Schema validation and completion in YAML editors. The schema file is provided by ambit.schema.json.

```yaml
# yaml-language-server: $schema=vendor/zoliszabo/php-ambit/ambit.schema.json
```

--------------------------------

### Validate a Config with FilesystemValidator

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Use `FilesystemValidator` to check an existing or programmatically created `Config`, independently of YAML loading. It requires a `Config` object and a project directory.

```php
use Ambit\Validation\FilesystemValidator;
use Ambit\YamlConfigLoader;

$config = (new YamlConfigLoader())->load(__DIR__ . '/ambit.yaml');
$result = (new FilesystemValidator())->validate($config, __DIR__);
```

--------------------------------

### Additional sets with inheritance in ambit.yaml

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Define dedicated sets for different tools. They can inherit paths and exclusions from php using extends. The lint set includes src, tests, bin, and config, and excludes both */generated/* and config/legacy.php.

```yaml
rector:
    extends: php
    exclude:
        - tests/Fixtures

lint:
    extends: php
    paths:
        - bin
        - config
    exclude:
        - config/legacy.php
```

--------------------------------

### SchemaValidator::validate()

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Validates already parsed configuration data against the schema. Returns a result object with issues, errors, and warnings.

```APIDOC
## [PHP] SchemaValidator::validate()

### Description
Validates already parsed configuration data against the schema. Returns a result object with issues, errors, and warnings.

### Method
PHP

### Endpoint
SchemaValidator::validate()

### Parameters
#### Arguments
- **$data** (array) - Required - The parsed configuration data.

### Response
#### Return Value
- **result** (object) - Contains issues, errors, and warnings. Use `issues()`, `errors()`, `warnings()`, and `isValid()` methods.

### Request Example
```php
use Ambit\Validation\SchemaValidator;

$data = ['php' => ['paths' => ['src'], 'exclude' => ['cache/']]];
$result = (new SchemaValidator())->validate($data);
```
```

--------------------------------

### vendor/bin/ambit validate

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Validates the configuration file. By default, it performs both schema and filesystem validation. Options allow limiting checks to schema, paths, or exclusions, and to a specific set.

```APIDOC
## [CLI] vendor/bin/ambit validate

### Description
Validates the configuration file. By default, it performs both schema and filesystem validation. Options allow limiting checks to schema, paths, or exclusions, and to a specific set.

### Method
CLI

### Endpoint
vendor/bin/ambit validate

### Parameters
#### Options
- **--set=NAME** (string) - Optional - Limits filesystem checks to the specified set. Schema checks always cover every set.
- **--schema-only** (flag) - Optional - Only perform schema validation.
- **--paths-only** (flag) - Optional - Only perform filesystem validation for paths.
- **--exclusions-only** (flag) - Optional - Only perform filesystem validation for exclusions.

### Response
#### Exit Status
- **0** - No errors or warnings.
- **1** - Errors (including runs that also have warnings).
- **2** - Incorrect CLI arguments.
- **3** - Warnings only.

### Request Example
```bash
vendor/bin/ambit validate
vendor/bin/ambit validate path/to/ambit.yaml --set=rector
vendor/bin/ambit validate --schema-only
vendor/bin/ambit validate --paths-only
vendor/bin/ambit validate --exclusions-only
```

### Response Example
```text
Validating "ambit.yaml".
WARNING [filesystem] php.paths "modules/*/src" (resolved to "/project/modules/*/src"): This does not match any real path.
WARNING [filesystem] php.exclude "cache/" (resolved to "/project/cache/"): This does not match any real path.
0 error(s), 2 warning(s).
```
```

--------------------------------

### Inspect validation result issues, errors, and warnings

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Both validators return a result with issues, errors, and warnings. `isValid()` returns true when there are no errors; warnings are allowed.

```php
foreach ($result->issues() as $issue) {
    echo $issue->severity() . ': ' . $issue->path() . ' ' . $issue->message() . PHP_EOL;
}

$result->isValid(); // True when there are no errors; warnings are allowed.
$result->errors();
$result->warnings();
```

--------------------------------

### SchemaValidator::assertValid()

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Validates already parsed configuration data against the schema and throws an InvalidArgumentException on a schema violation.

```APIDOC
## [PHP] SchemaValidator::assertValid()

### Description
Validates already parsed configuration data against the schema and throws an InvalidArgumentException on a schema violation.

### Method
PHP

### Endpoint
SchemaValidator::assertValid()

### Parameters
#### Arguments
- **$data** (array) - Required - The parsed configuration data.

### Response
#### Return Value
- **void** - Throws `InvalidArgumentException` on schema violation.

### Request Example
```php
use Ambit\Validation\SchemaValidator;

$data = ['php' => ['paths' => ['src'], 'exclude' => ['cache/']]];
(new SchemaValidator())->assertValid($data);
```
```

--------------------------------

### Using Ambit with Rector in rector.php

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Use the rector set for paths and exclusions alongside rule configuration. Requires Ambit\Scope and Rector\Config\RectorConfig.

```php
use Ambit\Scope;
use Rector\Config\RectorConfig;

$scope = Scope::fromProject(__DIR__, 'rector');

return RectorConfig::configure()
    ->withPaths($scope->paths())
    ->withSkip($scope->exclusions());
```

--------------------------------

### Validate parsed configuration with SchemaValidator

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Use `SchemaValidator` to validate already parsed configuration data. `validate()` returns a result; `assertValid()` throws `InvalidArgumentException` on a schema violation.

```php
use Ambit\Validation\SchemaValidator;

$data = ['php' => ['paths' => ['src'], 'exclude' => ['cache/']]];
$result = (new SchemaValidator())->validate($data);

// Or throw InvalidArgumentException on a schema violation:
(new SchemaValidator())->assertValid($data);
```

--------------------------------

### ValidationResult methods

Source: https://github.com/zoliszabo/php-ambit/blob/main/README.md

Methods on the result object returned by the validators to access issues, errors, warnings, and validity.

```APIDOC
## [PHP] ValidationResult methods

### Description
Methods on the result object returned by the validators to access issues, errors, warnings, and validity.

### Method
PHP

### Endpoint
ValidationResult::issues()
ValidationResult::isValid()
ValidationResult::errors()
ValidationResult::warnings()

### Response
#### Return Value
- **issues()** - Returns an iterable of issue objects, each with `severity()`, `path()`, and `message()` methods.
- **isValid()** - Returns true when there are no errors; warnings are allowed.
- **errors()** - Returns the errors.
- **warnings()** - Returns the warnings.

### Request Example
```php
foreach ($result->issues() as $issue) {
    echo $issue->severity() . ': ' . $issue->path() . ' ' . $issue->message() . PHP_EOL;
}

$result->isValid(); // True when there are no errors; warnings are allowed.
$result->errors();
$result->warnings();
```
```
Tokens:
Raw