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

[FEATURE] Add project documentation

parent c06cbe43
......@@ -15,15 +15,13 @@ variables:
MAILHOG_SMTP_PORT: "1025"
MAILHOG_API_PORT: "8025"
workflow:
rules:
- if: '$CI_COMMIT_BRANCH'
stages:
- build
- lint
- sca
- test
- docs
- deploy
build:
stage: build
......@@ -35,7 +33,8 @@ build:
rules:
- if: '$CI_PIPELINE_SOURCE == "pipeline"'
when: never
- when: on_success
- if: '$CI_COMMIT_BRANCH'
when: on_success
lint:php:
stage: lint
......@@ -46,7 +45,8 @@ lint:php:
rules:
- if: '$CI_PIPELINE_SOURCE == "pipeline"'
when: never
- when: on_success
- if: '$CI_COMMIT_BRANCH'
when: on_success
lint:composer:
stage: lint
......@@ -57,7 +57,8 @@ lint:composer:
rules:
- if: '$CI_PIPELINE_SOURCE == "pipeline"'
when: never
- when: on_success
- if: '$CI_COMMIT_BRANCH'
when: on_success
sca:php:
stage: sca
......@@ -73,7 +74,8 @@ sca:php:
rules:
- if: '$CI_PIPELINE_SOURCE == "pipeline"'
when: never
- when: on_success
- if: '$CI_COMMIT_BRANCH'
when: on_success
test:
image: webdevops/php:${PHP_VERSION}
......@@ -130,3 +132,48 @@ test:
artifacts:
reports:
junit: .build/coverage/junit.xml
rules:
- if: '$CI_COMMIT_BRANCH'
when: on_success
docs:
stage: docs
image: docker:19.03.12
services:
- docker:19.03.12-dind
before_script:
- apk add --no-cache docker-compose
script:
- docker-compose -f docs/build/docker-compose.yaml build --pull
- docker-compose -f docs/build/docker-compose.yaml run --rm docs build
cache: {}
artifacts:
paths:
- site/
rules:
- if: '$RENDER_DOCS'
when: on_success
- if: '$CI_COMMIT_BRANCH == "master"'
when: on_success
deploy:docs:
stage: deploy
image: instrumentisto/rsync-ssh
dependencies:
- docs
before_script:
- which ssh-agent || (apt-get update -y && apt-get install openssh-client -y)
- eval $(ssh-agent -s)
- echo "$PRIVATE_KEY_FOR_DEPLOYMENT" | tr -d '\r' | ssh-add -
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- ssh-keyscan cp140.sp-server.net >> ~/.ssh/known_hosts
- chmod 644 ~/.ssh/known_hosts
script:
- 'rsync -avz --chmod=Du=rwx,Dgo=rx,Fu=rw,Fog=r site/ eliashae@cp140.sp-server.net:/home/eliashae/html/docs.elias-haeussler.de/composer-update-reporter/'
cache: {}
rules:
- if: '$RENDER_DOCS'
when: never
- if: '$CI_COMMIT_BRANCH == "master"'
when: on_success
......@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Introduce `AbstractService`
- Add method `getIdentifier()` to `ServiceInterface`
- Include root package name in service reports
- Project documentation
### Changed
......
This diff is collapsed.
[![Pipeline](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter/badges/master/pipeline.svg)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter/-/pipelines)
[![Coverage](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter/badges/master/coverage.svg)](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter/-/pipelines)
[![Packagist](https://badgen.net/packagist/v/eliashaeussler/composer-update-reporter)](https://packagist.org/packages/eliashaeussler/composer-update-reporter)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-reporter)](LICENSE)
[![License](https://badgen.net/packagist/license/eliashaeussler/composer-update-reporter)](LICENSE.md)
[![Documentation](https://badgen.net/badge/read/the%20docs/cyan)](https://docs.elias-haeussler.de/composer-update-reporter/)
# Composer update reporter plugin
> Composer Plugin to report outdated packages to several external services,
> based on the Plugin [eliashaeussler/composer-update-check](https://packagist.org/packages/eliashaeussler/composer-update-check)
## Installation
## Documentation
```bash
composer req --dev eliashaeussler/composer-update-reporter
```
* [Documentation](https://docs.elias-haeussler.de/composer-update-reporter/)
* [Repository](https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter)
## Supported services
## Changelog
* [Email](#email)
* [GitLab](#gitlab)
* [Mattermost](#mattermost)
* [Slack](#slack)
* [MS Teams](#ms-teams)
## Configuration
Services need to be enabled and configured, either in the `composer.json`
file of your project or using environment variables.
Configuration in `composer.json` needs to be placed in the `extra`
section like follows:
```json
{
"extra": {
"update-check": {
"<service name>": {
"<config key>": "<config value>"
}
}
}
}
```
### Email
Email reports are being processed using the [Symfony Mailer](https://packagist.org/packages/symfony/mailer).
Consult the [official documentation](https://symfony.com/doc/current/mailer.html) for help regarding DSN.
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ---- | -------- |
| `email.enable` | `EMAIL_ENABLE` | `bool` | yes |
| `email.dsn` | `EMAIL_DSN` | `string` | yes |
| `email.receivers` | `EMAIL_RECEIVERS` | `string` (comma-separated list) | yes |
| `email.sender` | `EMAIL_SENDER` | `string` | yes |
### GitLab
Learn more about GitLab Alerts in the
[official documentation](https://docs.gitlab.com/ee/operations/incident_management/alert_integrations.html#generic-http-endpoint).
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ---- | -------- |
| `gitlab.enable` | `GITLAB_ENABLE` | `bool` | yes |
| `gitlab.url` | `GITLAB_URL` | `string` | yes |
| `gitlab.authKey` | `GITLAB_AUTH_KEY` | `string` | yes |
### Mattermost
Learn more about Mattermost webhooks in the
[offical documentation](https://docs.mattermost.com/developer/webhooks-incoming.html).
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ---- | -------- |
| `mattermost.enable` | `MATTERMOST_ENABLE` | `bool` | yes |
| `mattermost.url` | `MATTERMOST_URL` | `string` | yes |
| `mattermost.channel` | `MATTERMOST_CHANNEL` | `string` | yes |
| `mattermost.username` | `MATTERMOST_USERNAME` | `string` | no |
### Slack
Learn more about Incoming Webhooks in the
[offical Slack documentation](https://api.slack.com/messaging/webhooks).
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ---- | -------- |
| `slack.enable` | `SLACK_ENABLE` | `bool` | yes |
| `slack.url` | `SLACK_URL` | `string` | yes |
### MS Teams
Learn more about Incoming Webhooks in the
[offical documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook).
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ---- | -------- |
| `teams.enable` | `TEAMS_ENABLE` | `bool` | yes |
| `teams.url` | `TEAMS_URL` | `string` | yes |
### Example
Example configuration in `composer.json`:
```json
{
"extra": {
"update-check": {
"email": {
"enable": true,
"dsn": "smtp://foo:baz@smtp.example.com:25",
"receivers": "john@example.org, marc@example.org",
"sender": "alerts@example.org"
},
"gitlab": {
"enable": true,
"url": "https://gitlab.example.org/vendor/project/alerts/notify.json",
"authKey": "5scqqjpgw3dzipuawi8fp19acy"
},
"mattermost": {
"enable": true,
"url": "https://mattermost.example.org/hooks/5scqqjpgw3dzipuawi8fp19acy",
"channel": "alerts",
"username": "alertbot"
},
"slack": {
"enable": true,
"url": "https://hooks.slack.com/services/TU5C6A7/B01J/ZG5AR77F/5scqqjpgw3dzipuawi8fp19acy"
},
"teams": {
"enable": true,
"url": "https://my-team.webhook.office.com/webhookb2/5scqqjpgw3dzipuawi8fp19acy/IncomingWebhook/5scqqjpgw3dzipuawi8fp19acy/5scqqjpgw3dzipuawi8fp19acy"
}
}
}
}
```
Example configuration using environment variables:
```bash
EMAIL_ENABLE=1
EMAIL_DSN="smtp://foo:baz@smtp.example.com:25"
EMAIL_RECEIVERS="john@example.org, marc@example.org"
EMAIL_SENDER="alerts@example.org"
GITLAB_ENABLE=1
GITLAB_URL="https://gitlab.example.org/vendor/project/alerts/notify.json"
GITLAB_AUTH_KEY="5scqqjpgw3dzipuawi8fp19acy"
MATTERMOST_ENABLE=1
MATTERMOST_URL="https://mattermost.example.org/hooks/5scqqjpgw3dzipuawi8fp19acy"
MATTERMOST_CHANNEL="alerts"
MATTERMOST_USERNAME="alertbot"
SLACK_ENABLE=1
SLACK_URL="https://hooks.slack.com/services/TU5C6A7/B01J/ZG5AR77F/5scqqjpgw3dzipuawi8fp19acy"
TEAMS_ENABLE=1
TEAMS_URL="https://my-team.webhook.office.com/webhookb2/5scqqjpgw3dzipuawi8fp19acy/IncomingWebhook/5scqqjpgw3dzipuawi8fp19acy/5scqqjpgw3dzipuawi8fp19acy"
```
## Usage
Once services are configured properly, the update check can be executed
as usual. The update check result will then be reported to all enabled
services using the dispatched event.
```bash
composer update-check
```
## Development
### Requirements
* [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
### Preparation
```bash
# Clone repository
git clone https://gitlab.elias-haeussler.de/eliashaeussler/composer-update-reporter.git
cd composer-update-reporter
# 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
```
### Simulate application
A Composer script `simulate` exists which lets you test the update
check reporter, which is provided by this plugin. All parameters
passed to the script will be redirected to the relevant Composer
command `update-check`.
```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)
......@@ -49,6 +49,17 @@
}
},
"scripts": {
"docs": [
"@docs:stop",
"@docs:start",
"sleep 5",
"@docs:open"
],
"docs:build": "@docs:exec run --rm docs build",
"docs:exec": "docker-compose -f docs/build/docker-compose.yaml",
"docs:open": "open http://$(docker-compose -f docs/build/docker-compose.yaml port docs 8000)",
"docs:start": "@docs:exec up -d",
"docs:stop": "@docs:exec down",
"lint": "php-cs-fixer fix",
"sca": "phpstan analyse -c phpstan.neon",
"simulate": "bin/simulate-application.sh",
......
# API
The plugin provides a slim API which can be used to unregister currently
registered services or to register new services.
## `Registry::registerService()`
!!! tip
Learn how to [create a custom service](custom-service.md) if you want to register it here.
Registers the given service class in the
[`Registry`]({{ repository.blob }}/src/Registry.php)
so that it can be used by the
[`Reporter`]({{ repository.blob }}/src/Reporter.php). It is required that
the given service class implements the
[`ServiceInterface`]({{ repository.blob }}/src/Service/ServiceInterface.php).
| Parameter | Description |
| ------------------- | ----------------------------------------------------------------- |
| `string $className` | The class name of a service to be registered within the registry. |
Example:
```php
Registry::registerService(\My\Vendor\Service\MyService::class);
```
## `Registry::unregisterService()`
Removes the given service class from the list of registered services
in the [`Registry`]({{ repository.blob }}/src/Registry.php).
| Parameter | Description |
| ------------------- | ------------------------------------------------------------ |
| `string $className` | The class name of a service to be removed from the registry. |
Example:
```php
Registry::unregisterService(\My\Vendor\Service\MyService::class);
```
## `Registry::getServices()`
Returns the list of currently registered services in the
[`Registry`]({{ repository.blob }}/src/Registry.php).
Example:
```php
$services = Registry::getServices();
```
## `Reporter::report()`
Reports the given `UpdateCheckResult` to all currently registered services.
| Parameter | Description |
| --------------------------- | --------------------------------------------------------------------- |
| `UpdateCheckResult $result` | The scan results to be reported to all currently registered services. |
Example:
```php
$reporter = new Reporter($composer);
$reporter->report($result);
```
h2 > .twemoji:first-child {
width: 1.125em;
margin-right: 0.25em;
}
FROM squidfunk/mkdocs-material
# Install custom plugins
RUN apk add --no-cache git
RUN pip install \
Pygments \
mkdocs-git-revision-date-plugin \
mkdocs-localsearch \
mkdocs-exclude \
mkdocs-simple-hooks \
mkdocs-macros-plugin
version: '3'
services:
docs:
build: .
container_name: composer-update-reporter-docs
ports:
- "8000"
volumes:
- ../../:/docs
---
hide:
- toc
---
??? info
The changelog is extracted from
[CHANGELOG.md]({{ repository.blob }}/CHANGELOG.md).
--8<-- "CHANGELOG.md"
# Configuration
Services need to be enabled and configured, either in the `composer.json`
file of your project or using environment variables.
Configuration in `composer.json` needs to be placed in the `extra`
section like follows:
```json
{
"extra": {
"update-check": {
"<service name>": {
"<config key>": "<config value>"
}
}
}
}
```
## E-mail
E-mail reports are being processed using the [Symfony Mailer](https://packagist.org/packages/symfony/mailer).
Consult the [official documentation](https://symfony.com/doc/current/mailer.html) for help regarding DSN.
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | ------------------------------- | -------- |
| `email.enable` | `EMAIL_ENABLE` | `bool` | yes |
| `email.dsn` | `EMAIL_DSN` | `string` | yes |
| `email.receivers` | `EMAIL_RECEIVERS` | `string` (comma-separated list) | yes |
| `email.sender` | `EMAIL_SENDER` | `string` | yes |
Example:
=== "composer.json"
```json
{
"extra": {
"update-check": {
"email": {
"enable": true,
"dsn": "smtp://foo:baz@smtp.example.com:25",
"receivers": "john@example.org, marc@example.org",
"sender": "alerts@example.org"
}
}
}
}
```
=== "Environment variables"
```bash
EMAIL_ENABLE=1
EMAIL_DSN="smtp://foo:baz@smtp.example.com:25"
EMAIL_RECEIVERS="john@example.org, marc@example.org"
EMAIL_SENDER="alerts@example.org"
```
## GitLab Alerts
[:octicons-link-external-16: Official documentation][1]{: target=_blank }
[1]: https://docs.gitlab.com/ee/operations/incident_management/integrations.html#configuration
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | -------- | -------- |
| `gitlab.enable` | `GITLAB_ENABLE` | `bool` | yes |
| `gitlab.url` | `GITLAB_URL` | `string` | yes |
| `gitlab.authKey` | `GITLAB_AUTH_KEY` | `string` | yes |
Example:
=== "composer.json"
```json
{
"extra": {
"update-check": {
"gitlab": {
"enable": true,
"url": "https://gitlab.example.org/vendor/project/alerts/notify.json",
"authKey": "5scqqjpgw3dzipuawi8fp19acy"
}
}
}
}
```
=== "Environment variables"
```bash
GITLAB_ENABLE=1
GITLAB_URL="https://gitlab.example.org/vendor/project/alerts/notify.json"
GITLAB_AUTH_KEY="5scqqjpgw3dzipuawi8fp19acy"
```
## Mattermost
[:octicons-link-external-16: Official documentation][2]{: target=_blank }
[2]: https://docs.mattermost.com/developer/webhooks-incoming.html
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | --------------------- | -------- | -------- |
| `mattermost.enable` | `MATTERMOST_ENABLE` | `bool` | yes |
| `mattermost.url` | `MATTERMOST_URL` | `string` | yes |
| `mattermost.channel` | `MATTERMOST_CHANNEL` | `string` | yes |
| `mattermost.username` | `MATTERMOST_USERNAME` | `string` | no |
Example:
=== "composer.json"
```json
{
"extra": {
"update-check": {
"mattermost": {
"enable": true,
"url": "https://mattermost.example.org/hooks/5scqqjpgw3dzipuawi8fp19acy",
"channel": "alerts",
"username": "alertbot"
}
}
}
}
```
=== "Environment variables"
```bash
MATTERMOST_ENABLE=1
MATTERMOST_URL="https://mattermost.example.org/hooks/5scqqjpgw3dzipuawi8fp19acy"
MATTERMOST_CHANNEL="alerts"
MATTERMOST_USERNAME="alertbot"
```
## Slack
[:octicons-link-external-16: Official documentation][3]{: target=_blank }
[3]: https://api.slack.com/messaging/webhooks
| `composer.json` config key | Environment variable | Type | Required |
| -------------------------- | -------------------- | -------- | -------- |
| `slack.enable` | `SLACK_ENABLE` | `bool` | yes |
| `slack.url` | `SLACK_URL` | `string` | yes |
Example: