README

Official PHP SDK for the Argus dependency monitoring API. Push Composer and npm dependency snapshots to Argus so it can track vulnerabilities, outdated packages, and dependency drift across your projects.

Requirements

PHP 8.2+
Composer

Installation

composer require argus-dep/sdk

Quick Start — Standalone PHP

use ArgusSDK\ArgusClient;
use ArgusSDK\Reporters\ComposerReporter;

$client   = new ArgusClient(token: getenv('ARGUS_TOKEN'));
$reporter = new ComposerReporter(client: $client, projectName: 'My App');
$response = $reporter->send();

echo "Queued snapshot {$response->snapshotId} — {$response->packagesReceived} packages received.\n";

For npm projects, swap ComposerReporter for NpmReporter and point it at your package-lock.json / package.json files.

Quick Start — Laravel

1. Add environment variables

ARGUS_TOKEN=your-secret-project-token
ARGUS_PROJECT_NAME="My Laravel App"

2. Publish the config (optional)

php artisan vendor:publish --tag=argus-config

3. Report dependencies on demand

php artisan argus:report
# Report npm as well:
php artisan argus:report --ecosystem=all
# Override the environment label:
php artisan argus:report --env=staging

Auto-scheduling

The service provider registers the argus:report command with Laravel's scheduler automatically based on the schedule config values. Once ARGUS_TOKEN is set and the Laravel scheduler is running, no further setup is required.

# Make sure the scheduler is running (production)
* * * * * php /var/www/html/artisan schedule:run >> /dev/null 2>&1

Configuration Reference

Publish config/argus.php with php artisan vendor:publish --tag=argus-config to customise any value.

Key	Env variable	Default	Description
`token`	`ARGUS_TOKEN`	`null`	Required. Your project API token.
`url`	`ARGUS_URL`	`https://app.argus-dep.app`	Base URL for the Argus API.
`project_name`	`ARGUS_PROJECT_NAME`	`APP_NAME` / `"My App"`	Name shown in the Argus dashboard.
`environment`	`ARGUS_ENV`	`APP_ENV` / `"production"`	Environment label (e.g. production, staging).
`timeout`	`ARGUS_TIMEOUT`	`10`	HTTP request timeout in seconds.
`composer.enabled`	`ARGUS_COMPOSER_ENABLED`	`true`	Enable Composer reporting.
`composer.lock_file`	`ARGUS_COMPOSER_LOCK`	`base_path('composer.lock')`	Path to `composer.lock`.
`composer.manifest_file`	`ARGUS_COMPOSER_MANIFEST`	`base_path('composer.json')`	Path to `composer.json`.
`composer.schedule`	`ARGUS_COMPOSER_SCHEDULE`	`"daily"`	Auto-schedule frequency: `daily`, `hourly`, `weekly`, or `false` to disable.
`npm.enabled`	`ARGUS_NPM_ENABLED`	`false`	Enable npm reporting.
`npm.lock_file`	`ARGUS_NPM_LOCK`	`base_path('package-lock.json')`	Path to `package-lock.json`.
`npm.manifest_file`	`ARGUS_NPM_MANIFEST`	`base_path('package.json')`	Path to `package.json`.
`npm.schedule`	`ARGUS_NPM_SCHEDULE`	`"daily"`	Auto-schedule frequency for npm.

CI/CD Integration (GitHub Actions)

Add a step to your deployment workflow to push a fresh snapshot after every deploy:

- name: Report dependencies to Argus
  env:
    ARGUS_TOKEN: ${{ secrets.ARGUS_TOKEN }}
  run: php artisan argus:report --ecosystem=all

For non-Laravel projects:

- name: Report dependencies to Argus
  env:
    ARGUS_TOKEN: ${{ secrets.ARGUS_TOKEN }}
  run: |
    php -r "
      require 'vendor/autoload.php';
      \$client   = new \ArgusSDK\ArgusClient(getenv('ARGUS_TOKEN'));
      \$reporter = new \ArgusSDK\Reporters\ComposerReporter(\$client, 'My App');
      \$r = \$reporter->send();
      echo 'Snapshot ' . \$r->snapshotId . ' queued (' . \$r->packagesReceived . ' packages).' . PHP_EOL;
    "

Security: Store your ARGUS_TOKEN as a GitHub Actions secret. Never commit the token to your repository or print it in logs.

Advanced — Standalone Usage with Custom Files

use ArgusSDK\ArgusClient;
use ArgusSDK\Reporters\ComposerReporter;
use ArgusSDK\Reporters\NpmReporter;

$client = new ArgusClient(
    token:   getenv('ARGUS_TOKEN'),
    baseUrl: 'https://app.argus-dep.app',
    timeout: 15,
);

// Composer with explicit paths
$reporter = new ComposerReporter(
    client:           $client,
    projectName:      'My App',
    lockFilePath:     '/path/to/composer.lock',
    manifestFilePath: '/path/to/composer.json',
);
$reporter->send();

// npm
$npmReporter = new NpmReporter(
    client:           $client,
    projectName:      'My App',
    lockFilePath:     '/path/to/package-lock.json',
    manifestFilePath: '/path/to/package.json',
);
$npmReporter->send();

Error Handling

All errors throw ArgusSDK\ArgusException:

use ArgusSDK\ArgusException;

try {
    $reporter->send();
} catch (ArgusException $e) {
    echo $e->getMessage();           // human-readable message
    echo $e->getHttpStatusCode();    // e.g. 429
    echo $e->getApiErrorCode();      // e.g. "RATE_LIMITED"
}

Security Notes

The ARGUS_TOKEN is never written to log files. If debug logging is enabled, the Authorization header is redacted to Bearer [REDACTED].
The SDK is read-only with respect to your lock/manifest files — it never writes to them.
Using an HTTP (non-HTTPS) URL in non-local environments emits a PHP warning.

License

MIT

argus-dep / sdk

Maintainers

Package info

Statistics

Security