Spatie Security Advisories Health Check

https://github.com/spatie/security-advisories-health-check
Admin
A Laravel Health check that reports known security issues with installed PHP packages by fetching...
Tokens:17,160
Snippets:128
Trust Score:10
License:MIT
Update:4 days ago
Show doc for...
Tokens:
Raw
### ignoredPackages usage example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Example of using ignoredPackages to exclude multiple packages at once.

```php
SecurityAdvisoriesCheck::new()->ignoredPackages([
    'vendor/package1',
    'vendor/package2',
]);
```

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

### Complete configuration example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/configuration.md

Shows how to configure the SecurityAdvisoriesCheck instance using fluent methods. All mutators return $this and are chainable on the instance returned by SecurityAdvisoriesCheck::new().

```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new()
        ->retryTimes(3)                     // retry budget on failure
        ->cacheResultsForMinutes(120)       // cache results for 2 hours
        ->ignorePackage('acme/legacy')      // skip one package entirely
        ->ignoredPackages(['vendor/a', 'vendor/b']) // skip several more
        ->ignoreAdvisoryId('PKSA-yfw5-9gnj-n2c7')   // suppress one advisory
        ->ignoredAdvisoryIds(['PKSA-one', 'PKSA-two']),
]);
```

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

### ignorePackage usage example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Example of using ignorePackage to exclude a package. Returns $this, chainable.

```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = SecurityAdvisoriesCheck::new();
$check->ignorePackage('acme/legacy-package'); // returned $this, chainable
```

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

### cacheResultsForMinutes usage examples

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Shows how to cache results for one hour and how to revert to uncached behavior. The first example caches for 60 minutes, the second disables caching with 0 minutes.

```php
// Cache results for one hour (advisories change rarely):
SecurityAdvisoriesCheck::new()->retryTimes(5)->cacheResultsForMinutes(60);

// Back to uncached behavior:
SecurityAdvisoriesCheck::new()->cacheResultsForMinutes(0);
```

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

### Usage of retryTimes method

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Shows how to set the retry budget. The default is already 5; this example demonstrates setting it to 5 explicitly and to 10 for a more aggressive retry budget.

```php
SecurityAdvisoriesCheck::new()->retryTimes(5); // default is already 5

// A more aggressive retry budget:
SecurityAdvisoriesCheck::new()->retryTimes(10);
```

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

### affectedRangeOfInstalledVersion method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to find the first version range satisfied by the installed version. Splits on | or ||, uses Composer\Semver\Semver::satisfies(). Returns original string if no match or installed version is null.

```php
protected function affectedRangeOfInstalledVersion(string $affectedVersions, ?string $installedVersion): string
```

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

### getInstalledPackages method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to read installed packages from Composer\InstalledVersions. Keeps packages with a version key, drops ignored packages, and maps packageName => version.

```php
/**
 * @return Collection<string, string>
 */
protected function getInstalledPackages(): Collection
```

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

### ignoredAdvisoryIds usage example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Example of calling ignoredAdvisoryIds with a list of advisory IDs to suppress.

```php
SecurityAdvisoriesCheck::new()->ignoredAdvisoryIds([
    'PKSA-yfw5-9gnj-n2c7',
    'PKSA-xhv3-nr94-h8db',
]);
```

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

### Result->meta shape example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/types.md

Shows the structure of the meta array keyed by package name, with each value a list of slimmed advisory records. Fields are filtered to those in $advisoryFieldsInMeta, with null values rejected.

```php
// Result->meta shape
[
    'guzzlehttp/guzzle' => [
        [
            'title'            => 'Cross-domain cookie leakage', // string
            'link'             => 'https://github.com/advisories/GHSA-w248-ffj2-4v5q', // string
            'affectedVersions' => '>=7.0,<7.5', // string — narrowed to the range matching the installed version
            'reportedAt'       => '2022-05-25 19:21:00', // string
            'severity'         => 'high', // string
        ],
    ],
]
```

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

### Import SecurityAdvisoriesCheck class

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Loads the single public class of the package. Required before using the check in a Laravel Health setup.

```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;
```

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

### ignoreAdvisoryId usage example

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Example of using ignoreAdvisoryId to suppress a known false positive.

```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = SecurityAdvisoriesCheck::new();
$check->ignoreAdvisoryId('PKSA-yfw5-9gnj-n2c7'); // suppress a known false positive
```

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

### advisoriesForMeta method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to build the meta array for failed results. Keeps only actionable fields and matching version range, rejects null values, and replaces affectedVersions with the range matching the installed version.

```php
/**
 * Keep actionable fields and the matching version range to reduce stored metadata.
 *
 * @param  Collection<string, string>  $installedPackages
 */
protected function advisoriesForMeta(Collection $advisories, Collection $installedPackages): array
```

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

### Enable caching with cacheResultsForMinutes

Source: https://github.com/spatie/security-advisories-health-check/blob/main/README.md

Enable caching of Packagist results for a specified number of minutes to reduce API calls. The example caches for 1 hour.

```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new()
        ->retryTimes(5)
        ->cacheResultsForMinutes(60),     // Enables caching for 1 hour
]);
```

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

### ignorePackage(string $packageName): self

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Adds a Composer package name to the ignore list. The package will be excluded from the installed packages check and never sent to Packagist.

```APIDOC
## `ignorePackage(string $packageName): self`

### Description
Adds a package to `$ignoredPackages`; it is filtered out in `getInstalledPackages()` and never sent to Packagist.

### Method
`ignorePackage`

### Parameters
- `$packageName` (string) - Required - Composer package name to exclude, e.g. `'vendor/package'`.

### Returns
`$this` (fluent)

### Example
```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = SecurityAdvisoriesCheck::new();
$check->ignorePackage('acme/legacy-package'); // returned $this, chainable
```
```

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

### Basic usage of SecurityAdvisoriesCheck constructor

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Shows how to instantiate SecurityAdvisoriesCheck with default client or inject a custom PackagistClient with a Guzzle handler, e.g., for testing or proxies. The custom client uses a 10-second timeout.

```php
use Spatie\Packagist\PackagistClient;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = new SecurityAdvisoriesCheck();

// Or inject a client with a custom Guzzle handler (e.g. for testing or proxies):
$client = new GuzzleHttp\Client(['timeout' => 10]);
$check = new SecurityAdvisoriesCheck(new PackagistClient($client, new PackagistUrlGenerator()));
```

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

### Constructor signature for SecurityAdvisoriesCheck

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Defines the constructor accepting an optional PackagistClient. When null, a default client is built with GuzzleHttp\Client and PackagistUrlGenerator. The constructor calls parent::__construct() and assigns the client immediately, allowing early instantiation without resolving Laravel cache bindings.

```php
public function __construct(?PackagistClient $packagistClient = null)
```

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

### Run tests with composer test

Source: https://github.com/spatie/security-advisories-health-check/blob/main/README.md

Command to run the package's test suite.

```bash
composer test
```

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

### run() retry loop with error handling

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/errors.md

Wraps the retry loop in run() (src/SecurityAdvisoriesCheck.php:70). Catches Throwable, returns an OK result if all retries were gateway errors, otherwise throws the last non-gateway exception or the final exception.

```php
try {
    $advisories = $this->retryGetAdvisories($packages)
        ->pipe(fn (Collection $advisories) => $this->removeIgnoredAdvisoryIds($advisories));
} catch (Throwable $exception) {
    if ($this->allRetriesAreGatewayErrors()) {
        return Result::make('Packagist service could not be reached')->ok();
    }

    throw $this->lastNonGatewayException ?? $exception;
}
```

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

### __construct

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Creates a new SecurityAdvisoriesCheck instance. Optionally accepts a PackagistClient to customize the HTTP client used for querying Packagist.

```APIDOC
## `__construct`

### Description
Creates a new SecurityAdvisoriesCheck instance. Optionally accepts a PackagistClient to customize the HTTP client used for querying Packagist.

### Method
`__construct`

### Signature
```php
public function __construct(?PackagistClient $packagistClient = null)
```

### Parameters
- `$packagistClient` (\Spatie\Packagist\PackagistClient|null) - Optional - Client used to query Packagist. When `null`, a default is built: `new PackagistClient(new Client(), new PackagistUrlGenerator())` (`GuzzleHttp\Client`, `Spatie\Packagist\PackagistUrlGenerator`).

### Returns
The constructed check instance.

### Throws
None.

### Notes
The constructor calls `parent::__construct()` and assigns the client immediately, so the check can be instantiated early (e.g. inside `ServiceProvider::register()`) without resolving Laravel cache bindings; cache resolution happens lazily inside `run()`.

### Example
```php
use Spatie\Packagist\PackagistClient;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = new SecurityAdvisoriesCheck();

// Or inject a client with a custom Guzzle handler (e.g. for testing or proxies):
$client = new GuzzleHttp\Client(['timeout' => 10]);
$check = new SecurityAdvisoriesCheck(new PackagistClient($client, new PackagistUrlGenerator()));
```
```

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

### Direct run and outcome inspection

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Shows how to run the check directly and inspect the result, including handling failed status and logging vulnerabilities. Catches non-gateway exceptions after all retries.

```php
use Spatie\Health\Enums\Status;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = new SecurityAdvisoriesCheck();

try {
    $result = $check->run();

    if ($result->status === Status::failed()) {
        foreach ($result->meta as $package => $advisories) {
            foreach ($advisories as $advisory) {
                logger()->warning("Vulnerability {$advisory['title']} affects {$package}");
            }
        }
    }
} catch (\Throwable $e) {
    // Non-gateway failure after all retries; treat as infrastructure error.
    report($e);
}
```

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

### Reproduction of case 2: mixed gateway and non-gateway errors

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/errors.md

From the test suite, reproduces case 2 where a sequence of 502, 400, 504, 403, 504 causes run() to throw a GuzzleHttp\Exception\ClientException with code 403.

```php
// Sequence: 502 (gateway), 400 (non-gateway), 504 (gateway), 403 (non-gateway), 504 (gateway)
// -> throws GuzzleHttp\Exception\ClientException with code 403
$check->run();
```

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

### Configuration options for SecurityAdvisoriesCheck

Source: https://github.com/spatie/security-advisories-health-check/blob/main/README.md

Shows available configuration methods: retryTimes, cacheResultsForMinutes, ignorePackage, and ignoredPackages. Use these to customize retry attempts, cache duration, and package exclusions.

```php
SecurityAdvisoriesCheck::new()
    ->retryTimes(3)                     // Number of retry attempts on failure
    ->cacheResultsForMinutes(120)       // Cache duration in minutes
    ->ignorePackage('vendor/package')   // Ignore specific packages
    ->ignoredPackages([                 // Ignore multiple packages
        'vendor/package1',
        'vendor/package2'
    ]);
```

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

### fetchAdvisoriesFromApi method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to call Packagist API via spatie/packagist-api and wrap result in a Collection.

```php
protected function fetchAdvisoriesFromApi(Collection $packages): Collection
```

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

### ignoredPackages(array $packageNames): self

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Batch equivalent of `ignorePackage()`. Loops over the provided array and calls `ignorePackage()` for each name, appending to the existing ignored packages list.

```APIDOC
## `ignoredPackages(array $packageNames): self`

### Description
Batch equivalent of `ignorePackage()`; loops over the array calling `ignorePackage()` per name. Existing ignored packages are kept (appends, never replaces).

### Method
`ignoredPackages`

### Parameters
- `$packageNames` (array) - Required - List of Composer package names to exclude.

### Returns
`$this` (fluent)

### Example
```php
SecurityAdvisoriesCheck::new()->ignoredPackages([
    'vendor/package1',
    'vendor/package2',
]);
```
```

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

### new SecurityAdvisoriesCheck()

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Instantiates a new SecurityAdvisoriesCheck object. This constructor creates the Packagist client and prepares the check for use.

```APIDOC
## Constructor: `new SecurityAdvisoriesCheck()`

### Description
Creates a new instance of the `SecurityAdvisoriesCheck` class. This constructor initializes the Packagist client used to query security advisories.

### Method
Constructor

### Signature
`new SecurityAdvisoriesCheck()`

### Parameters
None

### Returns
A new `SecurityAdvisoriesCheck` instance.

### Example
```php
$check = new SecurityAdvisoriesCheck();
```
```

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

### getAdvisories method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected caching-aware fetch. Delegates to fetchAdvisoriesFromApi() when cacheResultsForMinutes is 0; otherwise reads from cache store and refetches if not array, storing with TTL.

```php
/**
 * @return Collection<string>
 */
protected function getAdvisories(Collection $packages): Collection
```

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

### ignoredPackages method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Signature of the ignoredPackages method. Batch equivalent of ignorePackage(), loops over the array calling ignorePackage() per name. Existing ignored packages are kept (appends, never replaces). Returns $this.

```php
public function ignoredPackages(array $packageNames): self
```

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

### Catch Throwable around run() to handle non-gateway failures

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/errors.md

Wrap the check's run() in a try/catch for \Throwable to handle non-gateway failures (e.g., HTTP 400/403 from Packagist, connection errors, cache driver errors) after all retries. Gateway-only outages never throw; a thrown exception always indicates a non-gateway failure. Inspect $result->meta when status is failed.

```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;
use Spatie\Health\Enums\Status;

$check = new SecurityAdvisoriesCheck();

try {
    $result = $check->run();

    if ($result->status === Status::failed()) {
        // security advisories found — inspect $result->meta
    }
} catch (\Throwable $e) {
    // Case 2/3: non-gateway failure (e.g. HTTP 400/403 from Packagist,
    // connection errors, cache driver errors) after all retries.
    // Gateway-only outages never reach this block (case 1 resolves to ok()).
    report($e);
}
```

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

### getCacheKey method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to generate cache key as 'security-advisories:' plus md5 of packages sorted by name and joined as name:version pairs with |.

```php
protected function getCacheKey(Collection $packages): string
```

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

### Retry logic in retryGetAdvisories()

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/errors.md

Uses Laravel's retry() helper to fetch advisories with retries. The when callback classifies exceptions between attempts; the final attempt's exception is not classified.

```php
return retry(
    times: $this->retryTimes,
    callback: fn () => $this->getAdvisories($packages),
    sleepMilliseconds: 2 * 1000,
    when: fn ($exception) => $this->shouldRetry($exception)
);
```

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

### retryTimes

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Sets the number of attempts when fetching advisories from Packagist. Returns the instance for fluent chaining.

```APIDOC
## `retryTimes`

### Description
Sets the number of attempts when fetching advisories from Packagist. Returns the instance for fluent chaining.

### Method
`retryTimes`

### Signature
```php
public function retryTimes(int $times): self
```

### Parameters
- `$times` (int) - Required - Number of attempts when fetching advisories from Packagist.

### Returns
`$this` (fluent).

### Notes
Sets `$retryTimes`, the maximum number of attempts made by `retryGetAdvisories()`; there is a 2000 ms sleep between attempts. If all attempts fail with gateway errors (HTTP 502/503/504), the check returns `ok()` instead of throwing (see [errors.md](../errors.md)).

### Example
```php
SecurityAdvisoriesCheck::new()->retryTimes(5); // default is already 5

// A more aggressive retry budget:
SecurityAdvisoriesCheck::new()->retryTimes(10);
```
```

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

### SecurityAdvisoriesCheck::new()

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Static factory method inherited from the parent `Check` class. Provides a convenient way to create a new `SecurityAdvisoriesCheck` instance.

```APIDOC
## Static Factory: `SecurityAdvisoriesCheck::new()`

### Description
Creates a new instance of the `SecurityAdvisoriesCheck` class using the static factory method inherited from the parent `Check` class.

### Method
Static Factory

### Signature
`SecurityAdvisoriesCheck::new()`

### Parameters
None

### Returns
A new `SecurityAdvisoriesCheck` instance.

### Example
```php
$check = SecurityAdvisoriesCheck::new();
```
```

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

### SecurityAdvisoriesCheck::run

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Executes the health check, fetching advisories and reporting results. Overrides the parent Check::run() method.

```APIDOC
## SecurityAdvisoriesCheck::run

### Description
Executes the health check, fetching advisories and reporting results. Overrides the parent Check::run() method.

### Method
run

### Signature
`public function run(): Result`

### Parameters
None documented.

### Return Value
Returns a Result object from spatie/laravel-health.

```

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

### SecurityAdvisoriesCheck::ignoredPackages

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Returns the list of ignored package names.

```APIDOC
## SecurityAdvisoriesCheck::ignoredPackages

### Description
Returns the list of ignored package names.

### Method
ignoredPackages

### Signature
`public function ignoredPackages(): array`

### Parameters
None documented.

### Return Value
Returns an array of ignored package names.

```

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

### SecurityAdvisoriesCheck::__construct

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Constructor for the SecurityAdvisoriesCheck class. Initializes the check instance.

```APIDOC
## SecurityAdvisoriesCheck::__construct

### Description
Constructor for the SecurityAdvisoriesCheck class. Initializes the check instance.

### Method
__construct

### Signature
`public function __construct()`

### Parameters
None documented.

### Return Value
No return value (void).

```

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

### retryTimes method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Defines the retryTimes method that sets the maximum number of attempts when fetching advisories from Packagist. Returns $this for fluent chaining. There is a 2000 ms sleep between attempts; if all attempts fail with gateway errors (HTTP 502/503/504), the check returns ok() instead of throwing.

```php
public function retryTimes(int $times): self
```

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

### allRetriesAreGatewayErrors method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to check if all retries were gateway errors. Compares gatewayExceptionCount to retryTimes - 1, accounting for off-by-one because retry() does not invoke when callback on final attempt.

```php
protected function allRetriesAreGatewayErrors(): bool
```

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

### run(): Result

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

This is the method invoked by the Laravel Health runner. It executes the security advisories check and returns a `Spatie\Health\Checks\Result` object. It throws a `Throwable` if a non-gateway exception occurs after the retry budget is exhausted.

```APIDOC
## run(): Result

### Description
This is the method invoked by the Laravel Health runner. It executes the security advisories check and returns a `Spatie\Health\Checks\Result` object. It throws a `Throwable` if a non-gateway exception occurs after the retry budget is exhausted.

### Method
run

### Parameters
No parameters.

### Returns
`Spatie\Health\Checks\Result` — the Laravel Health check result (the parent `Check::run()` contract).

### Throws
`Throwable` — rethrows the last non-gateway exception (HTTP 4xx/5xx other than 502/503/504, connection errors, etc.) after the retry budget is exhausted. Gateway-only failures do **not** throw.

### Outcomes
| Condition | Result |
|-----------|--------|
| No advisories returned (after removing ignored advisory IDs) | `Result::make('No security vulnerability advisories found')->ok()` |
| All retries failed with gateway errors (502/503/504) | `Result::make('Packagist service could not be reached')->ok()` |
| Advisories found | `Result::make()->meta($this->advisoriesForMeta($advisories, $packages))->failed("Security advisories found for {$packageNames}")` |
| Non-gateway exception after all retries | `throw $this->lastNonGatewayException ?? $exception` |

### Request Example
```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new()->retryTimes(5)->cacheResultsForMinutes(60),
]);
```

### Response Example
```php
use Spatie\Health\Enums\Status;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = new SecurityAdvisoriesCheck();

try {
    $result = $check->run();

    if ($result->status === Status::failed()) {
        foreach ($result->meta as $package => $advisories) {
            foreach ($advisories as $advisory) {
                logger()->warning("Vulnerability {$advisory['title']} affects {$package}");
            }
        }
    }
} catch (\Throwable $e) {
    // Non-gateway failure after all retries; treat as infrastructure error.
    report($e);
}
```
```

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

### shouldRetry method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to classify exceptions. ServerException with code 502/503/504 increments gatewayExceptionCount; others record as lastNonGatewayException. Always returns true.

```php
protected function shouldRetry($exception): bool
```

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

### retryGetAdvisories method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to wrap getAdvisories() in Laravel's retry() helper with times, sleepMilliseconds, and when callback.

```php
/**
 * @throws Throwable
 */
protected function retryGetAdvisories(Collection $packages): Collection
```

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

### SecurityAdvisoriesCheck::ignorePackage

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Adds a package name to the ignore list. Returns the check instance for chaining.

```APIDOC
## SecurityAdvisoriesCheck::ignorePackage

### Description
Adds a package name to the ignore list. Returns the check instance for chaining.

### Method
ignorePackage

### Signature
`public function ignorePackage(string $package): self`

### Parameters
- **package** (string) - Required - Package name to ignore.

### Return Value
Returns the check instance for method chaining.

```

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

### ignorePackage method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Signature of the ignorePackage method. Adds a package to $ignoredPackages, filtered out in getInstalledPackages() and never sent to Packagist. Returns $this for chaining.

```php
public function ignorePackage(string $packageName): self
```

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

### Register with Health facade

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Registers the `SecurityAdvisoriesCheck` with the Laravel Health facade so it runs as part of the health check suite.

```APIDOC
## Registration: `Health::checks()`

### Description
Registers the `SecurityAdvisoriesCheck` with the `Health` facade so it is executed during health checks.

### Method
Registration

### Signature
`Health::checks([...])`

### Parameters
- **checks** (array) - Required - An array of check instances to register.

### Example
```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new(),
]);
```
```

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

### Register SecurityAdvisoriesCheck with Health facade

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Registers the security advisories check with Laravel Health, typically inside a service provider's register() or boot() method. Instantiate directly or via the inherited static factory SecurityAdvisoriesCheck::new().

```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new(),
]);
```

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

### Advisory record shape from Packagist API response

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/types.md

Shape of each advisory as returned by PackagistClient::getAdvisoriesAffectingVersions() from spatie/packagist-api, shown in the package's test fixtures. Fields include advisoryId, packageName, remoteId, title, link, cve, affectedVersions, source, reportedAt, composerRepository, severity, and sources.

```php
[
    'advisoryId'          => 'PKSA-yfw5-9gnj-n2c7', // string
    'packageName'         => 'guzzlehttp/guzzle',    // string
    'remoteId'            => 'GHSA-w248-ffj2-4v5q', // string
    'title'               => 'Cross-domain cookie leakage', // string
    'link'                => 'https://github.com/advisories/GHSA-w248-ffj2-4v5q', // string
    'cve'                 => null,                   // ?string
    'affectedVersions'    => '>=8.0,<8.1|>=7.0,<7.5', // string (Composer constraint, `|` or `||` separated)
    'source'              => 'GitHub',               // string
    'reportedAt'          => '2022-05-25 19:21:00',  // string
    'composerRepository'  => 'https://packagist.org', // string
    'severity'            => 'high',                 // string
    'sources'             => [['name' => 'GitHub', 'remoteId' => 'GHSA-w248-ffj2-4v5q']], // array
]
```

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

### Basic usage with Health facade

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Shows how to register SecurityAdvisoriesCheck with the Laravel Health runner, using retryTimes and cacheResultsForMinutes. This is the typical way to use the check.

```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new()->retryTimes(5)->cacheResultsForMinutes(60),
]);
```

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

### cacheResultsForMinutes method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Method signature for cacheResultsForMinutes, which enables caching of fetched advisories in Laravel's default cache driver. Cached values are stored as plain arrays with a TTL of minutes * 60 seconds under the key security-advisories:<md5>. Non-array cached values are treated as cache misses.

```php
public function cacheResultsForMinutes(int $minutes): self
```

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

### run method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Method signature for run, which is invoked by the Laravel Health runner. It returns a Spatie\Health\Checks\Result and throws Throwable after retry budget exhaustion for non-gateway exceptions.

```php
/**
 * @throws Throwable
 */
public function run(): Result
```

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

### cacheResultsForMinutes(int $minutes): self

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Enables caching of fetched advisories in Laravel's default cache driver. The TTL is set in minutes, with 0 disabling caching. Returns $this for fluent chaining.

```APIDOC
## cacheResultsForMinutes(int $minutes): self

### Description
Enables caching of fetched advisories in Laravel's default cache driver (`App::make('cache.store')`). Cached values are stored as plain arrays with a TTL of `minutes * 60` seconds, under the key `security-advisories:<md5>` (see `getCacheKey`). Any cached value that is not an array — e.g. a `__PHP_Incomplete_Class` stub produced by apps with `cache.serializable_classes => false` — is treated as a cache miss and refetched.

### Method
cacheResultsForMinutes

### Parameters
#### Path Parameters
- **$minutes** (int) - Required - Cache TTL in minutes; `0` (the default) disables caching.

### Returns
`$this` (fluent).

### Request Example
```php
// Cache results for one hour (advisories change rarely):
SecurityAdvisoriesCheck::new()->retryTimes(5)->cacheResultsForMinutes(60);

// Back to uncached behavior:
SecurityAdvisoriesCheck::new()->cacheResultsForMinutes(0);
```
```

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

### Advisory collection type annotation

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/types.md

Docblock annotation showing the shape of the advisory collection returned by the API, keyed by package name. The collection is of type Collection<string, array<int, array>>, meaning each package name maps to an array of advisory records.

```php
/**
 * @param  Collection<string, array<int, array>>  $advisories
 * @return Collection<string, array<int, array>>
 */
```

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

### SecurityAdvisoriesCheck::ignoredAdvisoryIds

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Returns the list of ignored advisory IDs.

```APIDOC
## SecurityAdvisoriesCheck::ignoredAdvisoryIds

### Description
Returns the list of ignored advisory IDs.

### Method
ignoredAdvisoryIds

### Signature
`public function ignoredAdvisoryIds(): array`

### Parameters
None documented.

### Return Value
Returns an array of ignored advisory IDs.

```

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

### Register SecurityAdvisoriesCheck with retryTimes

Source: https://github.com/spatie/security-advisories-health-check/blob/main/README.md

Register the security advisories health check in a service provider. The retryTimes method sets the number of retry attempts on failure.

```php
use Spatie\Health\Facades\Health;
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

Health::checks([
    SecurityAdvisoriesCheck::new()->retryTimes(5),
]);
```

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

### ignoredAdvisoryIds method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Public method to suppress Packagist advisory IDs. Accepts an array of advisory IDs and returns $this for fluent chaining. Batch equivalent of ignoreAdvisoryId().

```php
public function ignoredAdvisoryIds(array $advisoryIds): self
```

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

### removeIgnoredAdvisoryIds method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Protected method to filter out advisories whose advisoryId is in $ignoredAdvisoryIds. Drops packages with no remaining advisories. Applied after fetch/cache lookup.

```php
/**
 * @param  Collection<string, array<int, array>>  $advisories
 * @return Collection<string, array<int, array>>
 */
protected function removeIgnoredAdvisoryIds(Collection $advisories): Collection
```

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

### SecurityAdvisoriesCheck::cacheResultsForMinutes

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Sets the cache duration for advisory results in minutes. Returns the check instance for chaining.

```APIDOC
## SecurityAdvisoriesCheck::cacheResultsForMinutes

### Description
Sets the cache duration for advisory results in minutes. Returns the check instance for chaining.

### Method
cacheResultsForMinutes

### Signature
`public function cacheResultsForMinutes(int $minutes): self`

### Parameters
- **minutes** (int) - Required - Cache duration in minutes.

### Return Value
Returns the check instance for method chaining.

```

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

### Protected property $advisoryFieldsInMeta

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/types.md

Defines the fields included in the meta record for failed results. Override in subclasses to change the meta shape.

```php
protected array $advisoryFieldsInMeta = [
    'title',
    'link',
    'cve',
    'severity',
    'affectedVersions',
    'reportedAt',
];
```

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

### ignoreAdvisoryId method signature

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Signature of the ignoreAdvisoryId method. Adds an advisory ID to $ignoredAdvisoryIds. Advisories matching it are removed after fetching/cache lookup by removeIgnoredAdvisoryIds(). Other advisories for the same package are still reported.

```php
public function ignoreAdvisoryId(string $advisoryId): self
```

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

### SecurityAdvisoriesCheck::retryTimes

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Sets the number of retry attempts for fetching advisories. Returns the check instance for chaining.

```APIDOC
## SecurityAdvisoriesCheck::retryTimes

### Description
Sets the number of retry attempts for fetching advisories. Returns the check instance for chaining.

### Method
retryTimes

### Signature
`public function retryTimes(int $times): self`

### Parameters
- **times** (int) - Required - Number of retry attempts.

### Return Value
Returns the check instance for method chaining.

```

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

### ignoreAdvisoryId(string $advisoryId): self

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/securityadvisoriescheck.md

Adds a Packagist advisory ID to the ignore list. Matching advisories are removed after fetching/cache lookup, without affecting the cache key. Other advisories for the same package are still reported.

```APIDOC
## `ignoreAdvisoryId(string $advisoryId): self`

### Description
Adds an advisory ID to `$ignoredAdvisoryIds`. Advisories matching it are removed **after** fetching/cache lookup (no cache-key impact), by `removeIgnoredAdvisoryIds()`. Other advisories for the same package are still reported.

### Method
`ignoreAdvisoryId`

### Parameters
- `$advisoryId` (string) - Required - Packagist advisory ID, e.g. `'PKSA-yfw5-9gnj-n2c7'`.

### Returns
`$this` (fluent)

### Example
```php
use Spatie\SecurityAdvisoriesHealthCheck\SecurityAdvisoriesCheck;

$check = SecurityAdvisoriesCheck::new();
$check->ignoreAdvisoryId('PKSA-yfw5-9gnj-n2c7'); // suppress a known false positive
```
```

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

### SecurityAdvisoriesCheck::ignoreAdvisoryId

Source: https://github.com/spatie/security-advisories-health-check/blob/main/_autodocs/api-reference/index.md

Adds an advisory ID to the ignore list. Returns the check instance for chaining.

```APIDOC
## SecurityAdvisoriesCheck::ignoreAdvisoryId

### Description
Adds an advisory ID to the ignore list. Returns the check instance for chaining.

### Method
ignoreAdvisoryId

### Signature
`public function ignoreAdvisoryId(string $advisoryId): self`

### Parameters
- **advisoryId** (string) - Required - Advisory ID to ignore.

### Return Value
Returns the check instance for method chaining.

```
Tokens:
Raw