# AbstractAuditParser

> Provides strict validation and normalization helpers for audit output parsers.

[API reference](/docs/api/index.md) › [Foxy](/docs/extensions/foxy/reference/index.md) › [Audit](/docs/extensions/foxy/reference/audit/index.md) › [Parser](/docs/extensions/foxy/reference/audit/parser/index.md) › AbstractAuditParser

| abstract class | `Foxy\Audit\Parser\AbstractAuditParser` |
| --- | --- |
| Source | [`src/Audit/Parser/AbstractAuditParser.php`](https://github.com/php-forge/foxy/blob/main/src/Audit/Parser/AbstractAuditParser.php#L31) |

5 subclasses:

- [`AbstractBulkAdvisoryParser`](/docs/extensions/foxy/reference/audit/parser/abstractbulkadvisoryparser/index.md)
- [`DenoAuditParser`](/docs/extensions/foxy/reference/audit/parser/denoauditparser/index.md)
- [`NpmAuditParser`](/docs/extensions/foxy/reference/audit/parser/npmauditparser/index.md)
- [`PnpmAuditParser`](/docs/extensions/foxy/reference/audit/parser/pnpmauditparser/index.md)
- [`YarnAuditParser`](/docs/extensions/foxy/reference/audit/parser/yarnauditparser/index.md)

Provides strict validation and normalization helpers for audit output parsers.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`assertNotErrorDocument()`](#method-assertNotErrorDocument) protected final | Rejects a JSON document that represents a package manager error. | `AbstractAuditParser` |
| [`assertOutputSize()`](#method-assertOutputSize) protected final | Rejects audit output that exceeds the parser's size limit. | `AbstractAuditParser` |
| [`decodeObject()`](#method-decodeObject) protected final | Decodes an audit JSON object after validating its size and shape. | `AbstractAuditParser` |
| [`getAdvisoryId()`](#method-getAdvisoryId) protected final | Selects a GHSA identifier from the candidate or URL, falling back to the source identifier. | `AbstractAuditParser` |
| [`getBoolean()`](#method-getBoolean) protected final | Returns a required boolean field. | `AbstractAuditParser` |
| [`getCves()`](#method-getCves) protected final | Returns validated, normalized CVE identifiers. | `AbstractAuditParser` |
| [`getGhsaId()`](#method-getGhsaId) protected final | Extracts and normalizes a GHSA identifier from a value or URL. | `AbstractAuditParser` |
| [`getManagerName()`](#method-getManagerName) protected abstract | Returns the package manager name used in malformed-output errors. | `AbstractAuditParser` |
| [`getNonNegativeInteger()`](#method-getNonNegativeInteger) protected final | Returns a required non-negative integer field. | `AbstractAuditParser` |
| [`getObject()`](#method-getObject) protected final | Converts a decoded JSON object into its property map. | `AbstractAuditParser` |
| [`getOptionalString()`](#method-getOptionalString) protected final | Returns a sanitized optional string field, or `null` when absent or empty. | `AbstractAuditParser` |
| [`getSeverity()`](#method-getSeverity) protected final | Returns a supported normalized severity value. | `AbstractAuditParser` |
| [`getSeverityCount()`](#method-getSeverityCount) protected final | Returns the sum of severity counts and optionally validates the reported total. | `AbstractAuditParser` |
| [`getSourceId()`](#method-getSourceId) protected final | Returns a non-empty source identifier from a string or integer value. | `AbstractAuditParser` |
| [`getString()`](#method-getString) protected final | Returns a required sanitized string field. | `AbstractAuditParser` |
| [`getStringList()`](#method-getStringList) protected final | Returns a normalized list containing only strings. | `AbstractAuditParser` |
| [`malformed()`](#method-malformed) protected final | Creates a package-manager-specific malformed-output exception. | `AbstractAuditParser` |
| [`sanitizeString()`](#method-sanitizeString) protected final | Replaces control characters and trims surrounding whitespace. | `AbstractAuditParser` |
| [`uniqueStrings()`](#method-uniqueStrings) protected final | Returns unique strings in deterministic order. | `AbstractAuditParser` |

## Method details

### assertNotErrorDocument() <span id="method-assertNotErrorDocument"></span>

```php
final protected function assertNotErrorDocument(mixed[] $data): void
```

Rejects a JSON document that represents a package manager error.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$data` | `mixed[]` |  |

### assertOutputSize() <span id="method-assertOutputSize"></span>

```php
final protected function assertOutputSize(string $output): void
```

Rejects audit output that exceeds the parser's size limit.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$output` | `string` |  |

### decodeObject() <span id="method-decodeObject"></span>

```php
final protected function decodeObject(string $output): mixed[]
```

Decodes an audit JSON object after validating its size and shape.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$output` | `string` |  |

**Returns**

`mixed[]`

### getAdvisoryId() <span id="method-getAdvisoryId"></span>

```php
final protected function getAdvisoryId(string $sourceId, string|null $candidate, string|null $url): string
```

Selects a GHSA identifier from the candidate or URL, falling back to the source identifier.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$sourceId` | `string` |  |
| `$candidate` | `string\|null` |  |
| `$url` | `string\|null` |  |

**Returns**

`string`

### getBoolean() <span id="method-getBoolean"></span>

```php
final protected function getBoolean(array $data, string $key, string $context): bool
```

Returns a required boolean field.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$data` | `array` |  |
| `$key` | `string` |  |
| `$context` | `string` |  |

**Returns**

`bool`

### getCves() <span id="method-getCves"></span>

```php
final protected function getCves(mixed $value, string $context): list<string>
```

Returns validated, normalized CVE identifiers.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `mixed` |  |
| `$context` | `string` |  |

**Returns**

`list<string>`

### getGhsaId() <span id="method-getGhsaId"></span>

```php
final protected function getGhsaId(string|null $value): string|null
```

Extracts and normalizes a GHSA identifier from a value or URL.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `string\|null` |  |

**Returns**

`string|null`

### getManagerName() <span id="method-getManagerName"></span>

```php
abstract protected function getManagerName(): string
```

Returns the package manager name used in malformed-output errors.

**Returns**

`string`

### getNonNegativeInteger() <span id="method-getNonNegativeInteger"></span>

```php
final protected function getNonNegativeInteger(array $data, string $key, string $context): int
```

Returns a required non-negative integer field.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$data` | `array` |  |
| `$key` | `string` |  |
| `$context` | `string` |  |

**Returns**

`int`

### getObject() <span id="method-getObject"></span>

```php
final protected function getObject(mixed $value, string $context): mixed[]
```

Converts a decoded JSON object into its property map.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `mixed` |  |
| `$context` | `string` |  |

**Returns**

`mixed[]`

### getOptionalString() <span id="method-getOptionalString"></span>

```php
final protected function getOptionalString(array $data, string $key, string $context): string|null
```

Returns a sanitized optional string field, or `null` when absent or empty.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$data` | `array` |  |
| `$key` | `string` |  |
| `$context` | `string` |  |

**Returns**

`string|null`

### getSeverity() <span id="method-getSeverity"></span>

```php
final protected function getSeverity(mixed $value, string $context): Foxy\Audit\Severity
```

Returns a supported normalized severity value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `mixed` |  |
| `$context` | `string` |  |

**Returns**

[`Foxy\Audit\Severity`](/docs/extensions/foxy/reference/audit/severity/index.md)

### getSeverityCount() <span id="method-getSeverityCount"></span>

```php
final protected function getSeverityCount(array $metadata, string $context, bool $requireTotal): int
```

Returns the sum of severity counts and optionally validates the reported total.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$metadata` | `array` |  |
| `$context` | `string` |  |
| `$requireTotal` | `bool` |  |

**Returns**

`int`

### getSourceId() <span id="method-getSourceId"></span>

```php
final protected function getSourceId(mixed $value, string $context): string
```

Returns a non-empty source identifier from a string or integer value.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `mixed` |  |
| `$context` | `string` |  |

**Returns**

`string`

### getString() <span id="method-getString"></span>

```php
final protected function getString(array $data, string $key, string $context, bool $allowEmpty = false): string
```

Returns a required sanitized string field.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$data` | `array` |  |
| `$key` | `string` |  |
| `$context` | `string` |  |
| `$allowEmpty` | `bool` |  |

**Returns**

`string`

### getStringList() <span id="method-getStringList"></span>

```php
final protected function getStringList(mixed $value, string $context): list<string>
```

Returns a normalized list containing only strings.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `mixed` |  |
| `$context` | `string` |  |

**Returns**

`list<string>`

### malformed() <span id="method-malformed"></span>

```php
final protected function malformed(string $reason, Throwable|null $previous = null): Foxy\Exception\RuntimeException
```

Creates a package-manager-specific malformed-output exception.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$reason` | `string` |  |
| `$previous` | [`Throwable`](https://www.php.net/manual/en/class.throwable.php)`\|null` |  |

**Returns**

[`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md)

### sanitizeString() <span id="method-sanitizeString"></span>

```php
final protected function sanitizeString(string $value): string
```

Replaces control characters and trims surrounding whitespace.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$value` | `string` |  |

**Returns**

`string`

### uniqueStrings() <span id="method-uniqueStrings"></span>

```php
final protected function uniqueStrings(list<string> $values): list<string>
```

Returns unique strings in deterministic order.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$values` | `list<string>` |  |

**Returns**

`list<string>`