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 * text=auto
/bin export-ignore /bin export-ignore
/docker export-ignore /docker export-ignore
/docs/build export-ignore /docs/build export-ignore
/tests export-ignore /docs/hooks.py export-ignore
/.gitattributes export-ignore /tests export-ignore
/.gitignore export-ignore /.gitattributes export-ignore
/.gitlab-ci.yml export-ignore /.gitignore export-ignore
/.php_cs export-ignore /.gitlab-ci.yml export-ignore
/Dockerfile export-ignore /.php_cs export-ignore
/mkdocs.yml export-ignore /Dockerfile export-ignore
/phpunit.xml export-ignore /mkdocs.yml export-ignore
/phpunit.ci.xml 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 ...@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed ### Changed
- Decouple `PostUpdateCheckEvent` from command event - Decouple `PostUpdateCheckEvent` from command event
- Various improvements in documentation
- Use temporary directories for test applications in Unit tests - Use temporary directories for test applications in Unit tests
- Parallel execution of Unit tests in CI - Parallel execution of Unit tests in CI
......
This diff is collapsed.
...@@ -2,134 +2,22 @@ ...@@ -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) [![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) [![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) [![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/) [![Documentation](https://badgen.net/badge/read/the%20docs/cyan)](https://docs.elias-haeussler.de/composer-update-check/)
# Composer update check plugin # Composer update check plugin
> Composer Plugin to check outdated packages, based on their requirements > Composer Plugin to check outdated packages, based on their requirements
## Installation ## Documentation
```bash * [Documentation](https://docs.elias-haeussler.de/composer-update-check/)
composer req --dev eliashaeussler/composer-update-check * [Repository](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-check)
```
## Usage ## Changelog
```bash View all notable release notes in the [Changelog](CHANGELOG.md).
# 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
```
## License ## 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 \ ...@@ -7,4 +7,5 @@ RUN pip install \
mkdocs-git-revision-date-plugin \ mkdocs-git-revision-date-plugin \
mkdocs-localsearch \ mkdocs-localsearch \
mkdocs-exclude \ 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 # 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 The main feature is about checking whether all **root requirements** are
**up to date**. This is achieved by internally performing a simple **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 ...@@ -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 configuration**. This ensures that the displayed results are as reasonable
as possible. as possible.
### Command ![Update check for all required packages](assets/img/features/update-check.png)
## :no_entry_sign: Exclude dev-packages
```bash ```bash
composer update-check composer update-check --no-dev
``` ```
[:octicons-link-external-16: Reference](usage.md#command-line-usage){: target=_blank } [:octicons-link-external-16: Reference](usage.md#-no-dev){: target=_blank }
### Example
![Update check for all required packages](images/features/update-check.png)
## Without dev-packages
In case **only packages listed in `require`** should be checked, the option 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 `--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`. ...@@ -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` Note that packages are still checked if they are listed in the `require`
section as well. To completely exclude a specific package, the 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. choice.
### Command ![Update check without dev-packages](assets/img/features/update-check-no-dev.png)
```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
Specific packages can be explicitly excluded from the update check. This can ## :material-regex: Exclude by name or pattern
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.
!!! tip !!! 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. can be used repeatedly.
### Command
```bash ```bash
composer update-check -i "composer/*" composer update-check -i "composer/*"
``` ```
[:octicons-link-external-16: Reference](usage.md#-ignore-packages-i){: target=_blank } [: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 ## :material-security: Security scan
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
```bash ```bash
composer update-check --security-scan composer update-check --security-scan
...@@ -89,23 +67,17 @@ 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 } [:octicons-link-external-16: Reference](usage.md#-security-scan-s){: target=_blank }
### Example Since version 0.3.0 of the Plugin an **additional security scan** can
be performed to check whether currently required package versions are
![Update check with additional security scan](images/features/update-check-security-scan.png) **insecure**. This can especially be useful if frameworks are used which
are regularly updated.
## JSON output
As an alternative output, the update check result can also be printed in The security scan is being performed by the help of the
JSON format. This might be useful when using the update check as basis for [Packagist Security Advisories API endpoint](https://packagist.org/apidoc#list-security-advisories).
other tools or programs.
!!! hint ![Update check with additional security scan](assets/img/features/update-check-security-scan.png)
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.
### Command ## :material-code-json: JSON output
```bash ```bash
composer update-check --json composer update-check --json
...@@ -113,6 +85,12 @@ composer update-check --json ...@@ -113,6 +85,12 @@ composer update-check --json
[:octicons-link-external-16: Reference](usage.md#-json-j){: target=_blank } [: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) [![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) [![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) [![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 update check plugin
> A Composer Plugin to check outdated packages, based on their requirements.<