Verified Commit 6281399f authored by Elias Häußler's avatar Elias Häußler 🐛
Browse files

[DOCS] Rewrite and improve complete documentation

parent 68bad93a
Pipeline #758 failed with stages
in 6 minutes and 54 seconds
* text=auto
/bin export-ignore
/docker export-ignore
/docs/build export-ignore
/tests export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
/.gitlab-ci.yml export-ignore
/.php_cs export-ignore
/Dockerfile export-ignore
/mkdocs.yml export-ignore
/phpunit.xml export-ignore
/phpunit.ci.xml export-ignore
* text=auto
/bin export-ignore
/docker export-ignore
/docs/build export-ignore
/docs/hooks.py export-ignore
/tests export-ignore
/.gitattributes export-ignore
/.gitignore export-ignore
/.gitlab-ci.yml export-ignore
/.php_cs export-ignore
/Dockerfile export-ignore
/mkdocs.yml export-ignore
/phpstan.neon export-ignore
/phpunit.xml export-ignore
/phpunit.coverage.xml export-ignore
......@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
- Decouple `PostUpdateCheckEvent` from command event
- Various improvements in documentation
- Use temporary directories for test applications in Unit tests
- Parallel execution of Unit tests in CI
......
This diff is collapsed.
......@@ -2,134 +2,22 @@
[![Coverage](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/badges/master/coverage.svg)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/-/pipelines)
[![Packagist](https://badgen.net/packagist/v/eliashaeussler/composer-update-check)](https://packagist.org/packages/eliashaeussler/composer-update-check)
[![Docker](https://img.shields.io/docker/v/eliashaeussler/composer-update-check?label=docker&sort=semver)](https://hub.docker.com/r/eliashaeussler/composer-update-check)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-check)](LICENSE)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-check)](LICENSE.md)
[![Documentation](https://badgen.net/badge/read/the%20docs/cyan)](https://docs.elias-haeussler.de/composer-update-check/)
# Composer update check plugin
> Composer Plugin to check outdated packages, based on their requirements
## Installation
## Documentation
```bash
composer req --dev eliashaeussler/composer-update-check
```
* [Documentation](https://docs.elias-haeussler.de/composer-update-check/)
* [Repository](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check)
## Usage
## Changelog
```bash
# Check all root requirements
composer update-check
# Skip dev-requirements
composer update-check --no-dev
# Exclude custom packages from update check
composer update-check -i "my-vendor/*" -i "roave/security-advisories"
# Exclude dev-requirements and custom packages
composer update-check -i "my-vendor/*" --no-dev
```
### Usage with Docker
```bash
# Use latest version (Composer v2)
docker run --rm -it -v $(pwd):/app eliashaeussler/composer-update-check
# Use latest version (Composer v1)
docker run --rm -it -v $(pwd):/app eliashaeussler/composer-update-check:v1
# Use specific version (Composer v2)
docker run --rm -it -v $(pwd):/app eliashaeussler/composer-update-check:0.6.0
# Use specific version (Composer v1)
docker run --rm -it -v $(pwd):/app eliashaeussler/composer-update-check:0.6.0-v1
```
Read more about usage with Docker in the
[documentation](https://docs.elias-haeussler.de/composer-update-check/docker.html).
### Additional security scan
In addition to the basic usage, outdated packages can also be scanned
for security vulnerabilities. Using the `--security-scan` (shorthand: `-s`)
parameter one can easily check if any of the outdated packages are
insecure.
The security scan is being performed by the help of the
[Packagist Security Advisories API endpoint](https://packagist.org/apidoc#list-security-advisories).
### Format output as JSON
All outputs generated by the `update-check` command can be formatted
as JSON using the `--json` (shorthand: `-j`) parameter:
```bash
composer update-check --json
```
## Development
### Preparation
```bash
# Clone repository
git clone https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check.git
cd composer-update-check
# Install Composer dependencies
composer install
```
### Run tests
Unit tests of this plugin can be executed using the provided Composer
script `test`. You can pass all available arguments to PHPUnit.
```bash
# Run tests
composer test
# Run tests and print coverage result
composer test -- --coverage-text
```
### Run Docker tests
All test applications can also be executed with the generated Docker
images. The Docker image to be used for testing needs to be specified
along with optional parameters for the `update-check` command.
```bash
# Run tests for the latest Docker image
./bin/run-docker-tests.sh eliashaeussler/composer-update-check:latest
# Run tests with optional parameters
./bin/run-docker-tests.sh eliashaeussler/composer-update-check:latest --security-scan --no-dev
```
### Simulate application
A Composer script `simulate` exists which lets you run the Composer
command `update-check`, which is provided by this plugin. All parameters
passed to the script will be redirected to the Composer command.
```bash
# Run "composer update-check" command without parameters
composer simulate
# Pass parameters to "composer update-check" command
composer simulate -- -i "composer/*"
composer simulate -- --no-dev
```
Alternatively, this script can be called without Composer context:
```bash
./bin/simulate-application.sh
```
View all notable release notes in the [Changelog](CHANGELOG.md).
## License
[GPL 3.0 or later](LICENSE)
[GNU General Public License 3.0 (or later)](LICENSE.md)
# API
!!! important
The standalone PHP API was introduced in version 0.4.0.
In case you're using a previous version, the API cannot be accessed directly.
## `UpdateChecker::__construct()`
Initializes a new [`UpdateChecker`]({{ repository.blob }}/src/UpdateChecker.php)
object for the given Composer installation
| Parameter | Description |
| --------------------------------- | ------------------------------------------------------------------------------ |
| `Composer $composer` | A `Composer` object which describes the Composer installation to be checked. |
| [`OutputBehavior`][1]` $behavior` | The constructed `OutputBehavior` object which describes behavior of user-oriented output. |
| [`Options`][2]` $options` | Transfer object of all resolved options to be configured for the update check. |
[1]: {{ repository.blob }}/src/IO/OutputBehavior.php
[2]: {{ repository.blob }}/src/Options.php
```php
$behavior = new OutputBehavior(
new Style(Style::JSON),
new Verbosity(Verbosity::VERBOSE),
$composer->getIO()
);
$options = new Options();
$options->setIncludeDevPackages(false);
new UpdateChecker($composer, $behavior, $options);
```
## `UpdateChecker::run()`
Runs the update check and returns an
[`UpdateCheckResult`]({{ repository.blob }}/src/Package/UpdateCheckResult.php) object
Example:
```php
$packageBlacklist = [
'my-vendor/*',
'roave/security-advisories',
];
$updateChecker->run($packageBlacklist, false);
```
## `UpdateChecker::getPackageBlacklist()`
Returns packages which were blacklisted (= ignored) during update check
Example:
```php
$blacklistedPackages = $updateChecker->getPackageBlacklist();
```
h2 > .twemoji:first-child {
width: 1.125em;
margin-right: 0.25em;
}
......@@ -7,4 +7,5 @@ RUN pip install \
mkdocs-git-revision-date-plugin \
mkdocs-localsearch \
mkdocs-exclude \
mkdocs-simple-hooks
mkdocs-simple-hooks \
mkdocs-macros-plugin
---
hide:
- toc
---
??? info
The changelog is extracted from
[CHANGELOG.md]({{ repository.blob }}/CHANGELOG.md).
--8<-- "CHANGELOG.md"
# How to contribute
Contributions to the Composer update check plugin are very welcome. :slight_smile:
Please follow the guide on this page if you want to contribute. Make sure
that all required code quality checks are green. If you need help, feel free
to file an issue and I will try to assist you wherever needed.
## :octicons-terminal-24: Preparation
```bash
# Clone repository
git clone https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check.git
cd composer-update-check
# Install Composer dependencies
composer install
```
## :octicons-file-code-24: Check code quality
Code quality can be checked by running the following commands:
```bash
# Run PHP linting
composer lint
# Run PHP static code analysis
composer sca
# Run Composer normalization
composer normalize
```
## :octicons-bug-24: Run tests
Unit tests can be executed using the provided Composer script `test`.
You can pass all available arguments to PHPUnit.
```bash
# Run tests
composer test
# Run tests and generate code coverage
composer test:coverage
```
## :octicons-server-24: Run Docker tests
All test applications can also be executed with the generated Docker
images. All available parameters for the `update-check` command can be passed.
```bash
# Run tests for the Docker image using Composer 2.x
./bin/run-docker-tests.sh --composer-version 2
# Run tests with optional parameters
./bin/run-docker-tests.sh --composer-version 2 --security-scan --no-dev
```
## :technologist: Simulate application
A Composer script `simulate` exists which lets you run the Composer
command `update-check`. All parameters passed to the script will be
redirected to the Composer command.
```bash
# Run "composer update-check" command without parameters
composer simulate
# Pass parameters to "composer update-check" command
composer simulate -- -i "composer/*"
composer simulate -- --no-dev
```
Alternatively, this script can be called without Composer context:
```bash
./bin/simulate-application.sh
```
## :material-file-document-edit-outline: Build documentation
```bash
# Build documentation and watch for changes
composer docs
# Build documentation for production use
composer docs:build
```
# Events
## `PostUpdateCheckEvent`
[:octicons-link-external-16: Reference]({{ repository.blob }}/src/Event/PostUpdateCheckEvent.php){: target=_blank }
This event is being dispatched once the update check process is complete. It provides
the complete `UpdateCheckResult` object and allows further handling of outdated packages.
### Example
```php linenums="1"
<?php
declare(strict_types=1);
namespace My\Vendor;
use Composer\EventDispatcher\EventSubscriberInterface;
use Composer\Plugin\PluginInterface;
use EliasHaeussler\ComposerUpdateCheck\Event\PostUpdateCheckEvent;
class Plugin implements PluginInterface, EventSubscriberInterface
{
// ...
public static function getSubscribedEvents(): array
{
return [
PostUpdateCheckEvent::NAME => [
['onPostUpdateCheck']
],
];
}
public function onPostUpdateCheck(PostUpdateCheckEvent $event): void
{
$updateCheckResult = $event->getUpdateCheckResult();
// ...
}
}
```
# Features
## Base check
## :mag_right: Base check
```bash
composer update-check
```
[:octicons-link-external-16: Reference](usage.md){: target=_blank }
The main feature is about checking whether all **root requirements** are
**up to date**. This is achieved by internally performing a simple
......@@ -10,19 +16,15 @@ Using the native Composer command allows to **fully respect all Composer
configuration**. This ensures that the displayed results are as reasonable
as possible.
### Command
![Update check for all required packages](assets/img/features/update-check.png)
## :no_entry_sign: Exclude dev-packages
```bash
composer update-check
composer update-check --no-dev
```
[:octicons-link-external-16: Reference](usage.md#command-line-usage){: target=_blank }
### Example
![Update check for all required packages](images/features/update-check.png)
## Without dev-packages
[:octicons-link-external-16: Reference](usage.md#-no-dev){: target=_blank }
In case **only packages listed in `require`** should be checked, the option
`--no-dev` can be used. It skips all packages listed in `require-dev` by
......@@ -30,58 +32,34 @@ excluding them from the list of packages internally passed to `composer update`.
Note that packages are still checked if they are listed in the `require`
section as well. To completely exclude a specific package, the
[`--ignore-packages` parameter](#blacklisted-packages) might be the better
[`--ignore-packages` parameter](#exclude-by-name-or-pattern) might be the better
choice.
### Command
```bash
composer update-check --no-dev
```
[:octicons-link-external-16: Reference](usage.md#-no-dev){: target=_blank }
### Example
![Update check without dev-packages](images/features/update-check-no-dev.png)
## Blacklisted packages
![Update check without dev-packages](assets/img/features/update-check-no-dev.png)
Specific packages can be explicitly excluded from the update check. This can
be done by either specifying the full package name or using an asterisk as
placeholder, e.g. `my-vendor/*`.
All packages are internally parsed using the native PHP function
[`fnmatch`](https://www.php.net/manual/de/function.fnmatch.php) to check
whether they should be excluded from the update check.
## :material-regex: Exclude by name or pattern
!!! tip
Multiple packages can be excluded at the same time as the `-i` parameter
Multiple packages can be excluded at the same time since the `-i` parameter
can be used repeatedly.
### Command
```bash
composer update-check -i "composer/*"
```
[:octicons-link-external-16: Reference](usage.md#-ignore-packages-i){: target=_blank }
### Example
**Specific packages** can be explicitly excluded from the update check. This
can be done by either specifying the **full package name** or using an asterisk
as **placeholder**, e.g. `my-vendor/*`.
![Update check without ignored packages](images/features/update-check-blacklist.png)
All packages are internally parsed using the native PHP function
[`fnmatch`](https://www.php.net/manual/de/function.fnmatch.php) to check
whether they should be excluded from the update check.
## Security scan
![Update check without ignored packages](assets/img/features/update-check-blacklist.png)
Since version 0.3.0 of the Plugin an additional security scan can be
performed to check whether currently required package versions are
insecure. This can especially be useful if frameworks are used which
are regularly updated.
The security scan is being performed by the help of the
[Packagist Security Advisories API endpoint](https://packagist.org/apidoc#list-security-advisories).
### Command
## :material-security: Security scan
```bash
composer update-check --security-scan
......@@ -89,23 +67,17 @@ composer update-check --security-scan
[:octicons-link-external-16: Reference](usage.md#-security-scan-s){: target=_blank }
### Example
![Update check with additional security scan](images/features/update-check-security-scan.png)
## JSON output
Since version 0.3.0 of the Plugin an **additional security scan** can
be performed to check whether currently required package versions are
**insecure**. This can especially be useful if frameworks are used which
are regularly updated.
As an alternative output, the update check result can also be printed in
JSON format. This might be useful when using the update check as basis for
other tools or programs.
The security scan is being performed by the help of the
[Packagist Security Advisories API endpoint](https://packagist.org/apidoc#list-security-advisories).
!!! hint
If you want to use the update check result for additional reports,
you might be interested in the
[`PostUpdateCheckEvent`](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/-/blob/master/src/Event/PostUpdateCheckEvent.php)
which is being dispatched after each successful update check.
![Update check with additional security scan](assets/img/features/update-check-security-scan.png)
### Command
## :material-code-json: JSON output
```bash
composer update-check --json
......@@ -113,6 +85,12 @@ composer update-check --json
[:octicons-link-external-16: Reference](usage.md#-json-j){: target=_blank }
### Example
As an **alternative output**, the update check result can also be printed in
**JSON format**. This might be useful when using the update check as basis for
other tools or programs.
If you want to use the update check result for additional reports, you might
be interested in the [`PostUpdateCheckEvent`](events.md#postupdatecheckevent)
which is being dispatched after each successful update check.
![Update check with JSON-formatted output](images/features/update-check-json.png)
![Update check with JSON-formatted output](assets/img/features/update-check-json.png)
[![Pipeline](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/badges/master/pipeline.svg)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/-/pipelines)
[![Coverage](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/badges/master/coverage.svg)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/-/pipelines)
---
hide:
- toc
---
[![Pipeline]({{ repository.url }}/badges/master/pipeline.svg)]({{ repository.url }}/-/pipelines)
[![Coverage]({{ repository.url }}/badges/master/coverage.svg)]({{ repository.url }}/-/pipelines)
[![Packagist](https://badgen.net/packagist/v/eliashaeussler/composer-update-check)](https://packagist.org/packages/eliashaeussler/composer-update-check)
[![Docker](https://img.shields.io/docker/v/eliashaeussler/composer-update-check?label=docker&sort=semver)](https://hub.docker.com/r/eliashaeussler/composer-update-check)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-check)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check/-/blob/master/LICENSE)
[![Documentation](https://badgen.net/badge/read/the%20docs/cyan)](https://docs.elias-haeussler.de/composer-update-check/)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-check)](license.md)
# Composer update check plugin
> A Composer Plugin to check outdated packages, based on their requirements.
## Features
## :rocket: Features
* [x] Report outdated packages<br>
* [x] Find outdated packages<br>
* [x] Multiple exclusion patterns (ignore packages, skip dev-requirements)<br>
* [x] Perform security scan<br>
* [x] Optional security scan<br>
* [x] Allow integration of additional plugins
## What are the differences to other plugins and commands?
## :hatched_chick: What are the differences to other plugins and commands?
Against other plugins and commands, this Plugin takes the **version constraints**
into account and reports outdated packages based on the individual **requirements**
......@@ -34,16 +38,40 @@ Given the following requirements of a `composer.json` file:
}
```
Using the native Composer command `composer outdated`, one can only check
if major or minor version updates are available. In this case the command
output would either show the major update (currently version `9.4.0`) or
the minor update to version `5.2.0`.
Now compare the output of the native `composer outdated` command with
the output from the `composer update-check` command provided by this plugin:
=== "Composer"
![Composer outdated](assets/img/comparison/composer-outdated.png){ width=500 align=right }
Using the native Composer command `composer outdated`, one can only check
if major or minor version updates are available.
In this case the command output would either show the major update (currently version
`9.x.x`) or the minor update (currently version `5.7.x`).
[:octicons-link-external-16: Reference](https://getcomposer.org/doc/03-cli.md#outdated){: target=_blank }
=== "Update check plugin"
![Composer update-check](assets/img/comparison/composer-update-check.png){ width=500 align=right }
The Composer command `composer update-check` provided by this plugin allows