Automattic / Automattic/syndication

Feature: Extensible notification system for syndication events

Open
#192 0 comments 0 reactions 0 assignees View on GitHub
Priority::Medium type: enhancement
Dominant language
PHP
Stars
107
Forks
44
Avg merge
18m
Merged PRs (30d)
19

Description

## Overview

Implement an extensible notification system that alerts administrators when syndication events occur. This feature was partially implemented in the unreleased 2.1 branch and is being reimplemented with modern architecture patterns.

## Background

The 2.1 branch contained a notification system (`Syndication_Notifier` class) that supported email and Slack notifications. This issue captures the requirements for a fresh implementation using service-oriented architecture with support for additional notification channels.

## Requirements

### Notification Events

The system should support notifications for the following events (hooks already exist in develop):

| Event | Hook | Parameters |
|-------|------|------------|
| New post pushed | `syn_post_push_new_post` | `$result, $post_ID, $site, $transport_type, $client, $info` |
| Post updated (push) | `syn_post_push_edit_post` | `$result, $post_ID, $site, $transport_type, $client, $info` |
| Post deleted (push) | `syn_post_push_delete_post` | `$result, $ext_ID, $post_ID, $site_ID, $transport_type, $client` |
| New post pulled | `syn_post_pull_new_post` | `$result, $post, $site, $transport_type, $client` |
| Post updated (pull) | `syn_post_pull_edit_post` | `$result, $post, $site, $transport_type, $client` |

### Notification Channels

**Built-in channels:**
- **Email**: Send HTML emails via `wp_mail()`
- **Slack**: Send messages via incoming webhook URL

**Extensibility requirement:** The architecture must allow third-party developers to register additional notification channels (e.g., Microsoft Teams, Discord, PagerDuty, custom webhooks) without modifying core plugin code.

### Configuration

Global settings (under Push Syndication → Settings):
- Enable/disable each notification channel independently
- Per-channel configuration:
- **Email**: recipient address(es)
- **Slack**: webhook URL
- Per-channel event selection (which events trigger notifications)

### Notification Content

Each notification should include:
- Event type (created/updated/deleted)
- Post title and link to edit screen
- Endpoint name and link
- Success/failure status
- Error message (if applicable)
- Timestamp

### Architecture

Suggested service-oriented design:

```
┌─────────────────────────────────────────────────────────┐
│ NotificationService │
│ - Listens to syndication hooks │
│ - Creates NotificationEvent value objects │
│ - Dispatches to registered channels │
└─────────────────────────────────────────────────────────┘


┌─────────────────────────────────────────────────────────┐
│ NotificationChannelInterface │
│ + send(NotificationEvent $event): bool │
│ + get_id(): string │
│ + get_label(): string │
│ + render_settings(): void │
│ + is_configured(): bool │
└─────────────────────────────────────────────────────────┘

┌───────────────┼───────────────┐
▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│EmailChannel│ │SlackChannel│ │ Future │
└────────────┘ └────────────┘ │ Channels │
└────────────┘
```

**Value Objects:**
- `NotificationEvent`: Immutable object containing event type, post data, endpoint data, result, timestamp
- `NotificationResult`: Success/failure with optional error message

**Extensibility hook:**
```php
// Third-party developers can add channels:
add_filter( 'syn_notification_channels', function( array $channels ): array {
$channels[] = new My_Custom_Channel();
return $channels;
} );
```

## Acceptance Criteria

- [ ] NotificationService class listens to all syndication event hooks
- [ ] EmailChannel sends HTML emails with event details
- [ ] SlackChannel sends formatted messages to webhook URL
- [ ] Settings UI allows enabling/disabling channels and selecting events
- [ ] `syn_notification_channels` filter allows registering custom channels
- [ ] Unit tests for NotificationService and value objects
- [ ] Integration tests for email and Slack delivery
- [ ] Failed notifications are logged via Syndication_Logger

## Out of Scope

- Per-endpoint notification settings (future enhancement)
- Notification batching/digest mode (future enhancement)
- Retry logic for failed notifications (future enhancement)

## References

- Original feature request: #113
- 2.1 branch implementation: `includes/class-syndication-notifier.php`
- 2.1 settings implementation: `includes/admin/class-settings-screen.php`

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading includes/class-syndication-notifier.php and includes/admin/class-settings-screen.php, then inspect the existing syndication hooks listed in the issue. Map the proposed NotificationService, channels, value objects, settings, logging, and tests to the current plugin structure. Done means all acceptance criteria are implemented, including built-in delivery, the registration filter, and integration and unit tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
php
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.