#62 Notify the end of the process executions with Symfony Notifier

[njoubert-cleverage]

Description

Fixes #62

Notify the end of the process executions (failures, warnings...) with Symfony Notifier, configured globally and overridden by process.

Changes

• ProcessExecutionEndedEvent (new): dispatched by ProcessEventSubscriber when a top-level process execution has ended and has been saved (not for sub-processes), with the ProcessExecution entity and the error of a failed execution. It does not require symfony/notifier: listen to it to send your own notifications. New optional $eventDispatcher argument of ProcessEventSubscriber (no BC break).
• ProcessExecutionNotifier (new, listener of this event): sends a ProcessExecutionNotification when the notification is enabled and the end of the execution is among the configured statuses.
  • NotificationTrigger statuses: failed; finish_with_report (finished with log levels counted in its report, see logs.report_increment_level; custom report keys are ignored); finish.
  • Notification: subject (e.g. Process "app.import" failed), content (status, start date, duration, reported log levels, error, log file, execution id), exception of a failed execution (trace in the emails), importance by status (high / medium / low, used by the notifier channel_policy).
  • Channels: configured ones, else the channel_policy of the notifier. Recipients: configured ones (email and/or phone), else the admin_recipients of the notifier.
  • A sending error is logged (cleverage_ui_process channel) and does not change the result of the process; notifier not enabled (framework.notifier): warning logged, nothing sent.
• Configuration: clever_age_ui_process.notification (enabled: false, statuses: [failed, finish_with_report], channels: [], recipients: []), each key overridden by the notification option of a process (next to ui), resolved and validated by ProcessConfigurationsManager::getNotificationOptions().
• symfony/notifier stays optional (require-dev + suggest): the listener is registered only when it is installed; notification.enabled: true without it fails when building the container.
• Docs: reference/09-notifications.md (new), cookbooks/notify_process_failures.md (new, Slack + email), bundle configuration, UI options, index. CHANGELOG: Add notify ability #62 entry (unreleased).

Tests

• Unit tests of NotificationTrigger, ProcessExecutionNotification, ProcessExecutionNotifier (real Notifier with a recording channel), configuration, extension, options resolution and event dispatch.
• Functional test: processes of the test application executed with the notifier enabled (null chatter transport): notified when enabled by the process, failed process notified, nothing by default.
• 338 tests OK, no risky test with coverage (pcov, as the CI); 100% coverage of the new classes. PHPStan, PHP-CS-Fixer, Rector, Twig-CS-Fixer OK.

Checked in process-bundle-demo

cleverage/process-bundle-demo companion PR: fakechat+logger://default transport (notifications written in the logs).

• demo.ui.notification (logs a warning): New Chat message without specified recipient!: Process "demo.ui.notification" finished with reported logs
• demo.ui.notification_failing: ... Process "demo.ui.notification_failing" failed
• processes without the notification option: nothing sent.

Known limits

• Chat channels display the subject only, unless the transport builds its options from the notification (e.g. Slack: content and exception too). Documented.
• Subject and content are not translated; no link to the execution in the UI (id and log file only).

Requirements

• Documentation updates
  • Reference
  • Cookbooks
  • Changelog
• Unit tests

Breaking changes

None (new feature disabled by default; new optional constructor argument).

🤖 Generated with Claude Code