Skip to content

Latest commit

 

History

History
144 lines (102 loc) · 6.37 KB

README.md

File metadata and controls

144 lines (102 loc) · 6.37 KB

Documentation

This document provides basic usage documentation for the Composer Audit Common Reports Plugin, as well as technical documentation on its functionality.

Requirements

  • Composer 2.4 or later
  • PHP 7.2.5 or later

Installation

You can either require the package globally or as a dev dependency for your project.

To make the plugin globally available run the following command:

composer global require nedbase/composer-audit-common-report-formats-plugin

To add the plugin available for a specific project, you may add it as a dev dependency:

composer require --dev nedbase/composer-audit-common-report-formats-plugin

Usage

To generate a JUnit formatted audit report, run the following command:

composer audit:junit

To generate a Trivy formatted audit report, run the following command:

composer audit:trivy

The same options and arguments that exist on Composer's native audit command are available for the audit:[format] command, except for the --format option, as the report format is implied by the audit:[format] command itself. So to generate a JUnit formatted audit report of regular dependencies only (so no dev dependencies) you may run:

composer audit:junit --no-dev

Technical documentation

This section describes the inner workings of the plugin. If you're considering contributing to this plugin, this will provide you with pointers on how to best implement your proposed change.

Composer commands

The plugin uses the Nedbase\Composer\CommandProvider class to register new commands with Composer. All commands registered must at least extend from the Composer\Command\BaseCommand, but the plugin also provides an extended class that is preferable: Nedbase\Composer\Command\ReportCommand.

ReportCommand class

This class is an abstract class that extends from Composer's AuditCommand and provides a framework for a generic reporting command. It requires two methods to be implemented:

  • getReportName(): the name of the report format that the command will implement. This value will be used to append to the command name; let's say we'll be implementing the foo report type, this command should return the string foo, which will result in the command audit:foo to be registered with Composer.
  • getReporter(): this method should return an instance of a class that implements Nedbase\Composer\Report\ReportInterface. On this class, the generate method will be called, with the JSON decoded output of the composer audit --format=json command, along with the command's output object. More on this interface further down in the documentation.

Optionally, you may override any other base methods. Recommended overrides are:

  • getDescription(): this will be the default description of the audit command. Overriding or extending the description is recommended. See the JUnitCommand implementation for an example.
  • getBaseReportFormat(): by default, the --format=json option will be passed to the composer audit command. If your implementation requires another one of Composer's native report formats as a source, specify this by overriding this method.

Because the ReportCommand extends from Composer's AuditCommand class, all options available for this command are available on the classes that extend from ReportCommand, except the format option, as this is inferred from the result of the getReportName() method.

Internally, when executed, the command alters the input by setting the value of the format option to whatever is returned by calling getBaseReportFormat() and then passes that input to its parent. The output is caught and passed to the ReportInterface instance that is returned by the getReporter() method. This class parses the input and writes its output to the command's Output object.

ReportInterface

For the actual processing of the data returned by the composer audit command into a specific format, a reporter class is used. Any reporter should implement Nedbase\Composer\Report\ReportInterface. Basically this means writing an implementation for the generate() method. This method accepts two parameters:

  • string $source: the source report, as generated by the command invoking the reporter. By default, this is the output of composer audit --format=json, so a string of JSON data.
  • OutputInterface $output: The Output object of the command invoking the reporter. The reporter class should directly output its generated data to this object.

For convenience, there is an abstract class Nedbase\Composer\Report\JsonBasedReporter, which has a protected method parseSource that can parse the JSON string provided as the first argument of the ReportInterface::generate() method by stripping any data preceding the audit command's JSON output and decoding the remaining JSON data.

Registering the new command

When you have created your new command and reporter, you should register the new command with composer. You can do this by adding a new instance of your command to the array of commands in the getCommands() method of the Nedbase\Composer\CommandProvider class.

You should be all set now. A new command in the form of audit:[my-report-format] should now be available when running composer.

Testing

In order to keep code in good working order we've implemented several testing frameworks and coding guidelines.

PHPUnit

In order for your changes to be adopted, your code should be unit tested and should pass all existing tests.

PHP CS Fixer

We're using PHP CS Fixer for code style. Make sure php-cs-fixer does not find any issues before submitting your changes.

Psalm

We're using Psalm for static code analysis. Psalm is configured in its most strict mode, so make sure to check if your changes don't contain any errors.