argus-dep/sdk

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