From 207a9df274650449f19423fd9605bc24ec230a06 Mon Sep 17 00:00:00 2001 From: Dan Untenzu Date: Fri, 13 Aug 2021 14:53:17 +0200 Subject: [PATCH] Clarify package usage Split installation and usage description. Extend description how the package works and when it runs. Explain need for Composer 2 in manual version checks (see #66) Refs #66 --- README.md | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 24a62f6..2d3dbe9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,9 @@ This package ensures that your application doesn't have installed dependencies w ## Installation +Add `"roave/security-advisories": "dev-latest"` to your `composer.json` `"require-dev"` section and you will +not be able to harm yourself with software with known security vulnerabilities. + ```sh composer require --dev roave/security-advisories:dev-latest ``` @@ -14,24 +17,36 @@ composer require --dev roave/security-advisories:dev-latest ## Usage This package does not provide any API or usable classes: its only purpose is to prevent installation of software -with known and documented security issues. -Simply add `"roave/security-advisories": "dev-latest"` to your `composer.json` `"require-dev"` section and you will -not be able to harm yourself with software with known security vulnerabilities. +with known and documented security issues. It provides a continuously updated +[list of these packages](composer.json), +causing Composer to show conflicts whenever a undesirable package version is to be installed. + +The checks are executed automatically when adding a new dependency via `composer require` +or when running `composer update`. + +Deploying an application with a valid `composer.lock` and via `composer install` won't trigger +any security versions checking. -For example, try following: +For example, try the following: ```sh composer require --dev roave/security-advisories:dev-latest -# following commands will fail: +# following commands will fail due to a conflict with roave/security-advisories: composer require symfony/symfony:2.5.2 composer require zendframework/zendframework:2.3.1 ``` -The checks are only executed when adding a new dependency via `composer require` or when running `composer update`: -deploying an application with a valid `composer.lock` and via `composer install` won't trigger any security versions -checking. +### Manual checks + +You may manually trigger a version check only by using the `--dry-run` flag on an update. + +This requires Composer version 2 however, due to a wont-fix issue in deprecated Composer 1.x. + +```sh +composer update --dry-run roave/security-advisories +``` - > You can manually trigger a version check by using the `--dry-run` switch on an update while not doing anything. Running `composer update --dry-run roave/security-advisories` is an effective way to manually trigger a security version check. +Conflicts with existing packages cause Composer to return a failure exit code. ## roave/security-advisories for enterprise